Skip to main content
Use this journey to create a reproducible annual-revenue observation for a model or research record. A number without its concept, unit, reporting period, and source filing is not the finished result.

Prerequisites

  • SECAPI_API_KEY, curl, and jq; Node.js 18+ for the record script.
  • One issuer identifier. This example uses AAPL.

1. Identify the source 10-K

Expected output: one latest AAPL Form 10-K identity record. Save accessionNumber, filingDate, filingUrl, and requestId; they identify the document to inspect when a later fact is surprising. 404 filing_not_found means the selected issuer/form did not resolve, not that the issuer has never filed.

2. Retrieve annual revenue observations

Expected output: up to four annual fact observations. resolvedTag records the concept selected by the service. Values remain in the returned unit, so do not format them as dollars or compare them to another observation until units and periods match.

3. Write the source-linked observation record

Create revenue-record.mjs:
Expected output: a JSON record that carries each raw observation and source link. Reopen the cited filing statement and notes before attributing a revenue change to the business.

Failure modes

  • 401 or 403 means the process did not send a valid entitled key.
  • Empty data can mean the issuer, filters, or resolved concept did not match; inspect resolvedTag and completeness before substituting a value.
  • Do not compare quarterly and annual values, or different units, as though they are equivalent. Retain periodStart, periodEnd, fp, and filedAt.
  • A restatement changes the observation’s filing context. Decide explicitly whether the model uses the latest restated fact or an originally reported one.

Next step

Read the facts reference for the complete concept-resolution and period-filter contract.