collect_* functions

Seven module-level functions do all the data retrieval. Every one of them takes creds (an OAuth2Credentials) as the first argument, validates its inputs, and dispatches to the RESTAdapter.

The calling convention

Preferred form (new, v3.0.0):

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

Deprecated form (v2 compatibility, emits DeprecationWarning):

collect_data(None, creds, "12/31/2025", "480228", "call")

# In 3.0.0 the keyword form from old 2.x docs also works (same warning):
collect_reporting_periods(session=None, creds=creds, series="call")

Passing a non-None session as the first argument raises SOAPDeprecationError — the library assumes you’re trying to pass the old FFIECConnection and tells you how to migrate.

All examples below use the new form. Internally, every function resolves the two forms via a private _resolve_session_and_creds() helper; you don’t need to think about it beyond knowing the deprecation is there.

Shared parameters

These appear on most collect_* functions and behave identically everywhere.

Parameter	Values	Notes
output_type	"list", "pandas", "polars", "xbrl", "pdf"	See the Output formats table below. "bytes" is deprecated (use "xbrl").
date_output_format	"string_original", "string_yyyymmdd", "python_format"	Controls the quarter column dtype.
force_null_types	None, "pandas", "numpy"	Accepted on all 7 methods for API symmetry. On list-returning methods it’s a documented no-op. None defaults to "pandas" (pd.NA) on DataFrame paths.

Output formats

output_type	Returns	Available on
"list"	Python list	all 7 methods
"pandas"	pd.DataFrame / pd.Series	all 7 methods
"polars"	pl.DataFrame (install [polars] extra)	all 7 methods
"xbrl"	raw UTF-8 XBRL XML bytes (starts <?xml)	collect_data, collect_ubpr_facsimile_data
"pdf"	raw PDF bytes (starts %PDF)	collect_data only — UBPR endpoint is XBRL-only

# Save a Call Report as a PDF (audit-friendly archive)
pdf_bytes = collect_data(
    creds, reporting_period="12/31/2024", rssd_id="480228",
    series="call", output_type="pdf",
)
Path("480228_2024Q4.pdf").write_bytes(pdf_bytes)

# Grab the raw XBRL for downstream XML processing
xbrl_bytes = collect_data(
    creds, reporting_period="12/31/2024", rssd_id="480228",
    series="call", output_type="xbrl",
)
xml_text = xbrl_bytes.decode("utf-8")   # clean UTF-8; library strips any BOM

output_type="bytes" is deprecated as of 3.0.0. On collect_ubpr_facsimile_data it still works (translated to "xbrl" + a DeprecationWarning); on every other method it now raises ValidationError after the warning. Migrate to "xbrl" or "pdf" as appropriate.

Accepted reporting-period formats: "MM/DD/YYYY", "YYYY-MM-DD", "YYYYMMDD", "#QYYYY" (e.g. "4Q2025"), or a datetime object at quarter-end.

RSSD IDs are always strings of digits (e.g. "480228"). Integers are rejected with ValidationError.

collect_reporting_periods

def collect_reporting_periods(
    creds,
    series: str = "call",
    output_type: str = "list",
    date_output_format: str = "string_original",
) -> list[str] | list[datetime] | pd.Series

Returns all reporting periods the webservice will serve for series, in ascending chronological order (oldest first).

from ffiec_data_connect import OAuth2Credentials, collect_reporting_periods

creds = OAuth2Credentials(username="...", bearer_token="eyJ...")
periods = collect_reporting_periods(creds, series="call")
# ['3/31/2001', '6/30/2001', ..., '12/31/2025']

Use series="ubpr" for UBPR periods, or call collect_ubpr_reporting_periods for the same result — the two paths converge internally.

collect_data

def collect_data(
    creds,
    reporting_period: str | datetime,
    rssd_id: str,
    series: str,  # "call" or "ubpr"
    output_type: str = "list",
    date_output_format: str = "string_original",
    force_null_types: str | None = None,
) -> list[dict] | pd.DataFrame | pl.DataFrame

The primary data function. Retrieves an XBRL facsimile for a single institution at a single reporting period, parses it through the xbrl_processor, normalizes via DataNormalizer, and returns in the requested shape.

df = collect_data(
    creds,
    reporting_period="12/31/2025",
    rssd_id="480228",
    series="call",
    output_type="pandas",
)
# columns: mdrm, rssd, id_rssd, quarter, data_type,
#          int_data, float_data, bool_data, str_data

See Output formats for the column dtypes and the data_type/typed-value-column convention. See Peer analysis for patterns that iterate this function across many RSSDs.

collect_filers_on_reporting_period

def collect_filers_on_reporting_period(
    creds,
    reporting_period: str | datetime,
    output_type: str = "list",
) -> list[dict] | pd.DataFrame

Returns the panel of reporters for reporting_period — every RSSD plus its attributes (name, charter, city, state, FDIC cert, etc.). Use this to build a per-quarter universe before looping collect_data across it.

panel = collect_filers_on_reporting_period(
    creds, reporting_period="12/31/2025", output_type="pandas",
)
# panel[["ID_RSSD", "Name", "State", "FDICCertNumber"]].head()

DataNormalizer runs on this endpoint — ZIP leading zeros and numeric-ID string-coercions happen here. See data normalization for the full list.

collect_filers_since_date

def collect_filers_since_date(
    creds,
    reporting_period: str | datetime,
    since_date: str | datetime,
    output_type: str = "list",
) -> list[str] | pd.Series

Returns the RSSD IDs of reporters who filed for reporting_period on or after since_date. Useful for incremental pipelines — see incremental updates.

new_filers = collect_filers_since_date(
    creds,
    reporting_period="12/31/2025",
    since_date="1/15/2026",
)
# ['37', '480228', ...]

RSSDs come back as strings (normalized — REST returns ints).

collect_filers_submission_date_time

def collect_filers_submission_date_time(
    creds,
    since_date: str | datetime,
    reporting_period: str | datetime,
    output_type: str = "list",
    date_output_format: str = "string_original",
) -> list[dict] | pd.DataFrame

Like collect_filers_since_date, but returns each filer’s submission timestamp as well. Fields: ID_RSSD, SubmissionDateTime (normalized to MM/dd/yyyy HH:mm:ss AM/PM).

subs = collect_filers_submission_date_time(
    creds,
    since_date="1/1/2026",
    reporting_period="12/31/2025",
    output_type="pandas",
)
# subs.sort_values("SubmissionDateTime").tail()

collect_ubpr_reporting_periods

def collect_ubpr_reporting_periods(
    creds,
    output_type: str = "list",
    date_output_format: str = "string_original",
) -> list[str] | pd.DataFrame

UBPR-specific reporting periods. Same semantics as collect_reporting_periods(creds, series="ubpr"); provided separately because UBPR went through a different internal REST path.

ubpr_periods = collect_ubpr_reporting_periods(creds)

collect_ubpr_facsimile_data

def collect_ubpr_facsimile_data(
    creds,
    reporting_period: str | datetime,
    rssd_id: str,
    output_type: str = "list",  # "list" | "pandas" | "polars" | "xbrl"
    force_null_types: str | None = None,
) -> bytes | list[dict] | pd.DataFrame

UBPR equivalent of collect_data. Returns ratio time-series for a single institution at a single period.

ubpr = collect_ubpr_facsimile_data(
    creds,
    reporting_period="12/31/2025",
    rssd_id="480228",
    output_type="pandas",
)

output_type="xbrl" returns the raw XBRL payload unparsed — useful if you want to archive the facsimile or process it with a different XBRL tool. output_type="bytes" is a deprecated alias for "xbrl" (emits a DeprecationWarning; still works on this method for back-compat). collect_ubpr_facsimile_data does NOT accept date_output_format (UBPR output uses string_original internally before dtype coercion).

Signature cheatsheet

Function	Positional args (after creds)	Returns
collect_reporting_periods	—	list of period strings
collect_data	reporting_period, rssd_id, series	facsimile rows (typed)
collect_filers_on_reporting_period	reporting_period	panel of reporters
collect_filers_since_date	reporting_period, since_date	RSSD IDs that filed
collect_filers_submission_date_time	since_date, reporting_period	RSSD + submission timestamp
collect_ubpr_reporting_periods	—	list of UBPR period strings
collect_ubpr_facsimile_data	reporting_period, rssd_id	UBPR rows (typed), or raw bytes

See also

• Output formats — per-output_type shape.
• Async and rate limits — running many of these calls in parallel via AsyncCompatibleClient.
• Upstream methods.py.