Financial Data API — Documentation

Financial Data API serves US company fundamentals as structured, period-keyed statements assembled from public SEC XBRL filings. One call returns three arrays (income statements, balance sheets, and cash-flow statements) for any company in the scored universe, with stable line-item keys mapped from XBRL concepts.

All fundamentals are derived from public SEC XBRL filings, so values are official-source and redistribution-safe. The financials endpoint requires the data:read scope.

What data is available

GET /companies/{idOrLookup}/financials returns three statement arrays, each element a single reporting period, newest first. Line items are mapped from SEC XBRL concepts into stable keys, so the same field name works across companies and periods. A line item is absent when the company did not report that concept for the period.

Income statement

revenue, cost_of_revenue, gross_profit, operating_expenses, research_and_development, selling_general_and_administrative, operating_income, net_income, earnings_per_share_diluted, weighted_average_shares_diluted.

Balance sheet

total_assets, current_assets, cash_and_equivalents, inventory, accounts_receivable, accounts_payable, current_liabilities, total_liabilities, long_term_debt, shareholders_equity.

Cash flow statement

net_cash_flow_from_operations.

Statements are available at annual or quarterly frequency. Coverage is the S&P 500 union Nasdaq-100 scored universe of US issuers; see the companies endpoint for membership and use GET /coverage for live breadth.

A missing line-item key means “not reported”, not zero. Treat absent keys as no value rather than assuming a value of zero.

Authentication

Send your key as x-api-key (or Authorization: Bearer) with the data:read scope. See Authentication.

Look up by ticker, CIK, or entity id

The idOrLookup path segment accepts a Financial Data API entity id, a ticker, or a CIK. There is no separate resolve step required:

By ticker

GET /companies/AAPL/financials

By CIK

GET /companies/0000320193/financials

By entity id

GET /companies/ent_aapl/financials

If you want to confirm the entity first, resolve a ticker or CIK with GET /entities/resolve. See the companies endpoint. It is optional: the path lookup matches ticker and CIK directly.

Parameters

Unknown query parameters are rejected with bad_request. Only period and limit are accepted here.

Example: AAPL annuals

curl "https://api.financialdatapi.com/companies/AAPL/financials?period=annual&limit=3" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

const { data: financials } = await client.request(
  "/companies/AAPL/financials",
  { period: "annual", limit: 3 }
);

for (const stmt of financials.income_statements) {
  console.log(stmt.periodEnd, stmt.revenue, stmt.net_income);
}

Response

{
  "data": {
    "entity_id": "ent_aapl",
    "ticker": "AAPL",
    "cik": "0000320193",
    "income_statements": [
      {
        "period": "annual",
        "periodEnd": "2025-09-27",
        "currency": "USD",
        "revenue": 416161000000,
        "cost_of_revenue": 210352000000,
        "gross_profit": 205809000000,
        "operating_income": 132972000000,
        "net_income": 112010000000,
        "earnings_per_share_diluted": 7.39,
        "weighted_average_shares_diluted": 15150000000
      }
    ],
    "balance_sheets": [
      {
        "period": "annual",
        "periodEnd": "2025-09-27",
        "currency": "USD",
        "total_assets": 364980000000,
        "current_assets": 152987000000,
        "cash_and_equivalents": 30299000000,
        "total_liabilities": 290437000000,
        "long_term_debt": 85750000000,
        "shareholders_equity": 74543000000
      }
    ],
    "cash_flow_statements": [
      {
        "period": "annual",
        "periodEnd": "2025-09-27",
        "currency": "USD",
        "net_cash_flow_from_operations": 118254000000
      }
    ]
  },
  "meta": { "api_version": "v1" },
  "requestId": "..."
}

Example figures above are illustrative. Pull live values from the endpoint.

Response shape

Every statement object shares three common fields plus its line items:

Line items by statement

Income statement

Balance sheet

total_assets, current_assets, cash_and_equivalents, inventory, accounts_receivable, accounts_payable, current_liabilities, total_liabilities, long_term_debt, shareholders_equity.

Cash flow statement

net_cash_flow_from_operations.

A line item is absent from a statement object when the company did not report that concept for the period. Treat missing keys as “not reported”, not zero.

Worked example: resolve, then pull

Find the company in the universe

List /companies (or resolve a ticker) to get the identity and sector, and confirm membership before fetching statements.

Request statements by ticker

Call /companies/{ticker}/financials with period=annual and a limit. No separate id lookup is required, because the path accepts ticker and CIK.

Read period-keyed line items

Iterate income_statements, balance_sheets, and cash_flow_statements. Each element is one period; line items are stable keys. Missing keys mean the concept was not reported.

Trace any value to its filing

Each statement value originates from an observation. Pull the same fundamentals through GET /entities/{entityId}/observations and follow GET /provenance/observations/{id} to the named SEC source and ingestion run.

Notes and caveats

Where the data comes from

Statements are assembled from individual SEC XBRL fundamentals observations, one per line item per period. The financials endpoint groups them into per-period statement objects so you do not have to.

Vintages and revisions

When a period has multiple reported vintages, the most recent value is used for each line item. The full history, including superseded values, remains queryable through the observations API with the as_of and knowledge-time filters. Note that as_of currently approximates the ingestion timestamp rather than full provider-vintage reconstruction.

Coverage breadth

The universe is US issuers in the S&P 500 and Nasdaq-100. Use GET /coverage for the current catalog totals and covered categories rather than assuming a fixed count.

Companies

The scored universe and entity resolution by ticker or CIK.

Economic calendar & events

Company filings surface as issuer_filing events in the unified events feed.

Provenance

Trace any statement value back to its named SEC source and ingestion run.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Financial statements

What data is available

Income statement

Balance sheet

Cash flow statement

Authentication

Look up by ticker, CIK, or entity id

By ticker

By CIK

By entity id

Parameters

Example: AAPL annuals

Response shape

Line items by statement

Worked example: resolve, then pull

Notes and caveats

Companies

Economic calendar & events

Provenance

​What data is available

Income statement

Balance sheet

Cash flow statement

​Authentication

​Look up by ticker, CIK, or entity id

By ticker

By CIK

By entity id

​Parameters

​Example: AAPL annuals

​Response shape

​Line items by statement

​Worked example: resolve, then pull

​Notes and caveats

​Related

Companies

Economic calendar & events

Provenance

What data is available

Authentication

Look up by ticker, CIK, or entity id

Parameters

Example: AAPL annuals

Response shape

Line items by statement

Worked example: resolve, then pull

Notes and caveats

Related