REST API reference — Call.Report

This page is the narrative companion to the interactive OpenAPI reference. It describes what ffiec-data-connect is actually calling under the hood — useful if you’re debugging a response, calling the API from a language other than Python, or building tooling around it.

The authoritative upstream reference is CDR-PDD-SIS-611 v1.10. Our OpenAPI specification at /api/ffiec_rest_api_openapi.yaml is reverse-engineered from that document plus extensive testing against the live API. It’s validated against real behavior but not officially blessed.

Base URL

https://ffieccdr.azure-api.us/public

Rate limits

2,500 requests per hour per user, rolling. The window resets continuously — see Async and rate limits for how to pace a batch job against this, and why you should plan for ~2,400/hr effective.

Non-standard design

The API deviates from typical REST conventions in ways that matter for anyone hand-constructing requests:

Everything goes in headers. Every parameter — including things that would normally be in the path or query string — is a header. RSSD IDs, reporting period dates, data series selectors, all of it.

Header names are case-sensitive. UserID (capital I, capital D), not userid or Userid. Authentication, not the standard Authorization. dataSeries, not data-series or DataSeries.

HTTP status codes are unreliable. A 400-worthy input error often comes back as 500 Internal Server Error. Don’t treat 5xx as “retry forever” — check the body.

Auth headers:

UserID: your FFIEC PWS username (capital I, capital D).
Authentication: Bearer eyJ.... Note — this is not the HTTP standard Authorization header.

JWTs begin with ey and end with .. Tokens are valid for 90 days. See Auth for the full token-obtaining flow.

Common response codes

Code	Meaning
200	Success
401	Auth failed or token expired
403	Invalid token, or required headers missing
404	Endpoint or resource not available
429	Rate limit exceeded
500	Server error — or a malformed request (see above)

Date formats

Reporting periods — MM/DD/YYYY (e.g. 12/31/2024)
Datetimes — M/D/YYYY H:MM:SS AM/PM (e.g. 2/20/2024 3:23:30 PM)

Why most callers should use the library

ffiec-data-connect exists because calling this API directly from scratch is unpleasant. The library handles:

Header construction with the correct casing
Mapping unreliable status codes to typed exceptions
Retry-with-backoff for transient 5xx
XBRL → pandas/Polars normalization
JWT expiration detection before you fire a request

If you’re writing Python, use the library. If you’re writing Go, Rust, TypeScript, etc., this page plus /api/ is the map.

Direct requests with curl

Get reporting periods for the Call series:

curl -X GET "https://ffieccdr.azure-api.us/public/RetrieveReportingPeriods" \
     -H "UserID: your_username" \
     -H "Authentication: Bearer eyJhbGci..." \
     -H "dataSeries: Call"

Get the panel of reporters for a specific period:

curl -X GET "https://ffieccdr.azure-api.us/public/RetrievePanelOfReporters" \
     -H "UserID: your_username" \
     -H "Authentication: Bearer eyJhbGci..." \
     -H "dataSeries: Call" \
     -H "reportingPeriodEndDate: 12/31/2024"

Python equivalent

The same thing via the library:

from ffiec_data_connect import OAuth2Credentials
import ffiec_data_connect as fdc

creds = OAuth2Credentials(
    username="your_username",
    bearer_token="eyJhbGci...",
)

periods = fdc.collect_reporting_periods(creds, series="call", output_type="list")

panel = fdc.collect_filers_on_reporting_period(
    creds,
    series="call",
    reporting_period="12/31/2024",
    output_type="pandas",
)

Historical note — SOAP

The FFIEC previously ran a SOAP webservice alongside this REST API. SOAP was discontinued on 2026-02-28. If you’re migrating a SOAP integration, see Migration from v2.