REST API Reference

This section provides a complete reference for the FFIEC CDR REST API endpoints. The API uses OAuth2 Bearer token authentication with JWT tokens that are valid for 90 days.

Warning

This is an UNOFFICIAL API Specification

This OpenAPI specification was reverse-engineered from official FFIEC documentation and extensive testing with the live API. While validated against actual API behavior, it should not be considered authoritative. The official documentation is CDR-PDD-SIS-611 v1.10.

Important

Non-Standard REST API Design

The FFIEC REST API deviates significantly from typical RESTful conventions:

Parameter Passing:

  • ALL parameters are passed as HTTP headers, not query parameters or path parameters

  • This includes data that would typically be in the URL path (like RSSD IDs) or query string

  • Headers are case-sensitive and must match exactly (e.g., UserID not userid)

HTTP Status Codes:

  • Status codes do not follow standard HTTP semantics

  • Client errors often return 5xx codes instead of appropriate 4xx codes

  • Invalid requests may return 500 (Internal Server Error) instead of 400 (Bad Request)

Authentication Headers:

  • UserID: Your FFIEC PWS username (note capital ‘ID’)

  • Authentication: Bearer {token} (NOT the standard Authorization header)

  • JWT tokens begin with ey and end with .

Note

Why Use ffiec-data-connect?

The ffiec-data-connect library abstracts away these API complexities, providing:

  • Automatic header construction with correct casing

  • Proper error code translation and handling

  • Built-in retry logic for transient failures

  • Data type normalization and validation

  • A consistent, Pythonic interface

This schema was developed during the creation of ffiec-data-connect and is provided as a reference for developers who need to understand the underlying API behavior.

Base URL

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

Rate Limiting

  • Maximum 2,500 requests per hour per user

  • Rate limit resets on a rolling basis

API Specification

The following OpenAPI specification documents all available REST API endpoints, request parameters, and response schemas:

GET /RetrieveReportingPeriods

Retrieve available reporting periods for Call data series

This method retrieves a list of all reporting period end dates available for the Call data series.

Status Codes:
Request Headers:

  • UserID – FFIEC PWS username (Required)

  • Authentication – User’s security token with “Bearer “ preceding it (Required)

  • dataSeries – Data series name (must be “Call”) (Required)

GET /RetrievePanelOfReporters

Retrieve Panel of Reporters for a reporting period

This method retrieves information for the financial institutions in the Panel of Reporters (POR) expected to file for a given Call reporting period.

Status Codes:
Request Headers:

  • UserID – FFIEC PWS username (Required)

  • Authentication – Bearer token with “Bearer “ prefix (Required)

  • dataSeries – Data series name (must be “Call”) (Required)

  • reportingPeriodEndDate – Date string of the reporting period end date (MM/DD/YYYY) (Required)

GET /RetrieveFilersSinceDate

Retrieve filers since a specific date

This method retrieves a list of ID RSSDs for financial institutions that have filed for the given reporting period after the provided lastUpdateDateTime and whose new filings are available for public distribution.

Status Codes:
Request Headers:

  • UserID – FFIEC PWS username (Required)

  • Authentication – Bearer token with “Bearer “ prefix (Required)

  • dataSeries – Data series name (must be “Call”) (Required)

  • reportingPeriodEndDate – Date string of the reporting period end date (MM/DD/YYYY) (Required)

  • lastUpdateDateTime – Date (and optional time) string for when the reports were last filed (Required)

GET /RetrieveFilersSubmissionDateTime

Retrieve filers with submission timestamps

This method retrieves the ID RSSDs and submission date and time of the reporters who have filed after the provided lastUpdateDateTime and whose new filings are available for public distribution.

Status Codes:
Request Headers:

  • UserID – FFIEC PWS username (Required)

  • Authentication – Bearer token with “Bearer “ prefix (Required)

  • dataSeries – Data series name (must be “Call”) (Required)

  • reportingPeriodEndDate – Date string of the reporting period end date (MM/DD/YYY) (Required)

  • lastUpdateDateTime – Date (and optional time) string for when the reports were last filed. (MM/DD/YYYY) (Required)

GET /RetrieveFacsimile

Retrieve individual bank facsimile data

This method retrieves a byte array stream of the requested facsimile file. The client must de-serialize the stream into a file in its local file system. SDF text files can be viewed and modified using spreadsheet or database software (e.g., Excel, Access) or with a text editor (e.g., NotePad). XBRL files require an XBRL editor.

Status Codes:
Request Headers:

  • UserID – FFIEC PWS username (Required)

  • Authentication – Bearer token with “Bearer “ prefix (Required)

  • dataSeries – Data series name (must be “Call”) (Required)

  • reportingPeriodEndDate – Date string of the reporting period end date (MM/DD/YYYY) (Required)

  • fiIdType – The type of identifier being provided (Required)

  • fiId – The financial institution’s identifier (Required)

  • facsimileFormat – The report format to retrieve (Required)

GET /RetrieveUBPRReportingPeriods

Retrieve UBPR reporting periods

This method retrieves a list of all reporting period end dates available for the UBPR data series.

Status Codes:
Request Headers:

  • UserID – FFIEC PWS username (Required)

  • Authentication – Bearer token with “Bearer “ prefix (Required)

GET /RetrieveUBPRXBRLFacsimile

Retrieve UBPR XBRL facsimile

Call to retrieve a byte array stream of the requested XBRL instance document. The client must de-serialize the stream into a file in its local file system. XBRL files require an XBRL editor.

Status Codes:
Request Headers:

  • UserID – FFIEC PWS username (Required)

  • Authentication – Bearer token with “Bearer “ prefix (Required)

  • reportingPeriodEndDate – Date string of the reporting period end date (MM/DD/YYYY) (Required)

  • fiIdType – The type of identifier being provided (Required)

  • fiId – The financial institution’s identifier (Required)

Common Response Codes

Code

Description

200

Success - Request processed successfully

401

Unauthorized - Authentication failed or token expired

403

Forbidden - Invalid token or missing required headers

404

Not Found - Endpoint or resource not available

429

Too Many Requests - Rate limit exceeded (2500 requests/hour)

500

Internal Server Error - Server-side issue

Date Formats

The REST API uses consistent date formatting:

  • Reporting periods: MM/DD/YYYY (e.g., 12/31/2024)

  • DateTime values: M/D/YYYY H:MM:SS AM/PM (e.g., 2/20/2024 3:23:30 PM)

Example Usage with Python

Using the ffiec_data_connect package:

from ffiec_data_connect import OAuth2Credentials
from datetime import datetime, timedelta
import ffiec_data_connect as fdc

# Setup credentials
creds = OAuth2Credentials(
    username="your_username",
    bearer_token="eyJhbGci...",  # Your JWT token
    token_expires=datetime.now() + timedelta(days=90)
)

# Collect reporting periods
periods = fdc.collect_reporting_periods(
    session=None,  # None for REST API
    creds=creds,
    series="call",
    output_type="list"
)

# Collect data for a specific bank
data = fdc.collect_data(
    session=None,
    creds=creds,
    rssd_id="37",
    reporting_period="12/31/2024",
    series="call"
)

Direct API Usage with curl

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

# Get panel of reporters
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"

Migration from SOAP to REST

Key differences when migrating from SOAP:

  1. Authentication: Use JWT tokens instead of username/password

  2. Headers: All parameters in headers, not SOAP envelope

  3. Date Format: Still uses MM/DD/YYYY format like SOAP

  4. Response Format: JSON instead of XML/XBRL

  5. Performance: Significantly faster response times

Warning

The legacy SOAP API will be discontinued on February 28, 2026. All integrations must migrate to REST before this date.

Additional Resources