Integrate SEC company facts with accounting context intact

Identify the public data interface

SEC’s data API documentation describes unauthenticated submissions and XBRL data interfaces on data.sec.gov. These public read interfaces are distinct from filer-facing APIs used to submit filings or manage filing access. The company-facts route is keyed by a ten-digit CIK, including leading zeros.

The same documentation states that data.sec.gov does not support browser CORS. The publication therefore uses offline synthetic fixtures instead of pretending a browser button directly calls a live company-facts endpoint. A future live collector would need an appropriate server-side design and the SEC’s fair-access requirements, with no workstation-dependent production service.

Select a fact’s meaning before its value

Define the entity, taxonomy, tag and unit path. Then determine whether the concept is an instant or duration measure and which period is intended. A label such as Assets is useful to a reader but does not replace the machine identity and accounting context.

For a synthetic example, select an instant fact ending 2025-12-31 with value 5,000,000 and unit USD. The normalized record retains that end date, period kind, filed date and accession evidence. A second fact for the same end date in EUR or with a different accounting context must not be merged simply because its label and number resemble the first.

The supplied adapter specifically accepts us-gaap:Assets in USD for one issuer and excludes records with a start field as duration contexts. Its source_record contains the accession; the full accounting context remains in the separate source artifact.

Preserve filing evidence without inventing order

Suppose two invented facts have the same end date and filed date but different accession identifiers and values. Their identifiers distinguish candidates; a date-only filed field does not necessarily establish intraday order. Retain both and report ambiguity under the declared selection policy rather than picking the last array entry.

The workbench uses availability_basis sec_filed_date for this bounded mapping. It does not claim that midnight UTC is the filing’s dissemination time. A more demanding intraday study needs separately verified timing evidence and a clear relation between that evidence and the fact selected from the filing.

Use the filing to resolve context

SEC’s Inline XBRL explanation describes how tagged facts connect to reporting-period and other contextual information in a human-readable filing. That makes the filing a useful inspection destination when a normalized number is ambiguous. The adapter should retain enough source identity to locate the evidence that requires review.

A synthetic duration example exposes the limit: revenue of 100 for January through March is not interchangeable with revenue of 100 for January through December, even when both records share a December filing date. The instant fixture does not normalize every possible duration context. Unsupported facts should be routed or rejected explicitly rather than collapsed into an end-date-only table.

Define acceptance beyond parse success

Tests should include multiple unit arrays, absent concepts, duplicate candidates, unexpected period fields and conflicting accessions. A successful JSON parse confirms syntax only. The acceptance result must state which concept and context were actually selected and which candidates were excluded.

Current SEC fair-access guidance calls for a declared User-Agent and efficient, moderated requests. Bulk archives may be preferable for large collection tasks, subject to their documented behavior. The synthetic sample establishes no live availability, filing accuracy, company valuation or investment recommendation. It demonstrates a reproducible mapping while keeping the accounting and timing uncertainties that prevent a broader claim visible.

Keep in the decision record

• Choose entity, concept, unit and period before selecting a value.
• Preserve accession conflicts and date-only filing evidence.
• The instant fixture is not a universal XBRL financial-statement parser.

Source notes

1. SEC — EDGAR Application Programming Interfaces, updated 8 April 2025
2. SEC — Inline XBRL, updated 17 January 2025
3. SEC — Accessing EDGAR Data

Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.

Continue the analysis