Companyfacts: preserve the context behind every number
SEC API Editorial · · 3 min read
Why a financial fact needs a concept, unit, reporting period, and source accession—and how to avoid misleading last-value shortcuts.
A number is not a financial statement
The companyfacts endpoint brings together company concept data, but a successful JSON response does not mean your application has produced a normalized financial statement. A number only becomes useful when its context survives your transformation. What does it measure? In which units? Over which period? Which filing disclosed it? A clean-looking table can hide all four questions.
Build your first representation around those questions. Preserve the source concept and unit with every observation. Retain reporting dates and filing provenance rather than collapsing observations into a single unlabeled value. This may feel more verbose than a quick metric dictionary, but it gives the next developer enough information to understand and verify the output.
Treat units as part of the identity
The SEC documentation describes separate arrays for different units associated with disclosures. Your processing should not assume that every numeric value in a concept can be combined directly. A monetary figure, a share count, and a per-share figure do not become comparable because they are all JSON numbers.
An effective ingestion check carries the unit all the way to storage and display. If a downstream consumer requests one unit, select that unit explicitly and make the selection visible. If the expected unit is absent, report absence rather than replacing it with whichever array appears first. In a test fixture, include more than one unit so the shortcut fails loudly. Formatting a value with a currency symbol should be the final presentation step, not an inference about what the source meant.
Period selection deserves its own logic
The most recent observation is not automatically the observation that answers a particular annual or quarterly question. Your application needs to decide which reporting interval the user requested and then evaluate candidate facts against that interval. Sorting by one date field does not replace that reasoning.
Suppose an analyst asks for a measure over a particular fiscal year. Start with an explicit requested interval, inspect the available periods, and show the selected boundaries alongside the value. If several observations could satisfy the request, retain the alternatives and explain the selection rule. This guide does not provide an accounting normalization algorithm; its recommendation is to keep enough evidence that such an algorithm can be evaluated instead of hiding the ambiguity inside a generic “latest” helper.
Keep later disclosures traceable
A robust pipeline should anticipate more than one disclosed observation for a concept and period. Do not design storage so that an incoming value silently overwrites every earlier record with the same label. Keeping accession and filing context makes it possible to explain why a displayed value changed after a subsequent ingestion.
For an application that offers a preferred value, store both the source observations and the selection decision. Record when the selection rule changed, because a change in your transformation is different from a change in the source data. If you cannot distinguish the two, investigating a customer discrepancy becomes much harder. A public correction ledger can document material explanatory mistakes, while the internal provenance trail supports a more detailed technical investigation.
Be clear about coverage
The SEC XBRL API documentation describes the scope of its aggregated facts, including standard taxonomies and entity-wide context. Do not present that scope as a promise to extract every custom disclosure, business segment, or arbitrary table from a filing. Those tasks may require different data and processing.
A useful interface states what it returns and what it does not establish. Missing data should remain missing, not become zero. A coverage note should be close to the result so it remains visible when a user exports or shares the analysis. Test with absent concepts and unexpected units, not just the company that made your initial demo look convincing. Finally, include the original filing route in the workflow so users can inspect the source when a number needs interpretation.
Sources and provenance
Technical claims are grounded in the sources below. Automated articles receive a separate model review and deterministic publication checks. These checks do not guarantee that every detail is correct.
- SEC EDGAR API documentation · checked 10/27/2026