ffiec-data-connect (Python)

ffiec-data-connect is a REST-only, OAuth2 JWT-authenticated Python client for the FFIEC CDR webservice. SOAP support was removed after the FFIEC shut down the SOAP endpoint on 2026-02-28; symbols that used to instantiate SOAP paths now raise SOAPDeprecationError. The current installable version is 3.0.0 — first stable release of the 3.x line. See Install.

This reference mirrors the public surface re-exported from ffiec_data_connect/__init__.py. Anything not listed here is either internal (underscore-prefixed, methods_enhanced, xbrl_processor, utils) or deliberately unstable — don’t rely on it.

What you will use day-to-day

A minimal working call looks like this:

from ffiec_data_connect import OAuth2Credentials, collect_data

creds = OAuth2Credentials(
    username="your_ffiec_username",
    bearer_token="eyJ...",  # 90-day JWT from the CDR portal
)

df = collect_data(
    creds,
    reporting_period="12/31/2025",
    rssd_id="480228",
    series="call",
    output_type="pandas",
)

That’s the whole API in miniature: one credential constructor, one collect_* function, a pandas DataFrame back. The rest of this section is the catalogue.

Getting started

Install — pip install --pre ffiec-data-connect, Python 3.11+.
Authentication — get a 90-day JWT from the FFIEC CDR portal.
Quickstart — first data pull in under two minutes.

Reference

Credentials — OAuth2Credentials and the deprecated WebserviceCredentials stub.
Functions — the seven collect_* functions.
Client and adapters — AsyncCompatibleClient, RateLimiter, ProtocolAdapter / RESTAdapter / create_protocol_adapter.
REST API reference — narrative on the HTTP surface, plus the interactive OpenAPI viewer at /api/.
Exceptions — the FFIECError tree.
Data normalizer — compatibility shim for REST → SOAP-shape payloads.
Configuration — legacy error-mode toggles, SOAP-cache stubs.

Workflows

Output formats — list, pandas, polars; dates; nulls.
Bulk download — patterns for many institutions/periods.
Async and rate limits — staying under 2500/hour.
Incremental updates — detect refilings.
Peer analysis — UBPR peer comparisons.

Operations

Troubleshooting — errors by frequency.
Migration from v2 — SOAP removed; new calling convention.

Contributing

Development setup — running from source.
Testing — test layout and conventions.

Version pinned by this reference

ffiec-data-connect == 3.0.0

This is the first stable release on the 3.x line. If you’re on an earlier version (2.x or older), the calling convention and credential class are different — see the v2 migration guide.