What the SEC Company Facts API contains
SEC Company Facts provides machine-readable XBRL facts associated with an issuer's CIK. A company-level response groups reported facts by taxonomy and concept, with observations that may carry values, units, accession numbers, forms, fiscal years and period dates. It is useful for building financial time series, but selecting a field by name alone does not guarantee that two observations describe the same accounting period or financial meaning.
Choose the right taxonomy and concept
Common financial concepts appear under the us-gaap taxonomy, while some issuers use extension concepts or report a different breakdown. An apparent synonym may have a different accounting definition. Define a mapping from the desired analytical metric to accepted taxonomy concepts and document any fallback logic. For example, a debt metric built from only a noncurrent debt component should not silently be labeled total debt.
Interpret units and periods
Each concept can contain unit-specific arrays, such as USD, shares or USD-per-share. Never combine values from different units without a conversion policy. Balance-sheet facts generally describe an instant, while income-statement and cash-flow facts cover durations with start and end dates. A three-month quarter and a year-to-date nine-month duration are not interchangeable, even when both have the same fiscal-quarter label.
Handle filings, amendments and restatements
The same reporting period can appear in several filings, including annual reports, quarterly reports and amendments. Preserve accession numbers, form types, filing dates, fiscal period labels and the observation's period boundaries. Choose a reproducible selection policy: for example, latest filed observation as of a specified cutoff date, with the source accession retained. Historical backtests require point-in-time selection to avoid incorporating values that were published later.
Distinguish missing, zero and unavailable
A concept missing from Company Facts is not automatically a zero balance. It may be absent because the issuer did not report that concept, used a different taxonomy, or had no applicable disclosure. Represent missing observations explicitly and attach a reason when it can be established. A reported zero should remain a numeric zero. Avoid filling absent financial values with assumptions unless the derived field is labeled and the formula is documented.
Build a reproducible normalization pipeline
Start by identifying the issuer CIK and retrieving the source facts. Select accepted taxonomy concepts, validate units, group observations by their actual period dates, and apply amendment and duplicate rules. Retain both raw facts and normalized outputs, together with schema version, extraction time and provenance. Compare a representative set of calculated metrics with the underlying filings, particularly for companies with unusual fiscal calendars or amended statements.
Common quality checks
Test whether period end dates precede filing dates where expected, whether duration lengths are plausible, and whether instant facts have no invented start date. Look for multiple competing observations for one metric and period. Record mapping coverage by issuer rather than claiming every company exposes every requested metric. These checks matter more than simply increasing the number of extracted fields.
Evaluate structured financial data
See the SEC Financial Filings dataset for the available product description, and review methodology and evaluation steps before integrating. A reliable financial dataset makes field definitions, reporting periods and source lineage inspectable instead of hiding normalization decisions.