Documentation

Fundamentals

Balance sheet, income statement and cash flow in one shape — regardless of which of the four data pools they come from. The /v1 endpoints are the recommended route; the older /statements and /financials endpoints return the raw form and remain unchanged.

What it is good for is on the product page: Fundamentals

GET /ca/universe

Get Ca Universe

Canadian equities universe (SEC-registered / cross-listed issuers whose full IS/BS/CF/CI/EQ statements are already in sec_statements, sourced from EDGAR/DERA XBRL). Query the statements themselves via GET /statements/{ticker_or_cik}. Built by build_ca_registry.py.

Note: purely domestic TSX/TSXV issuers without an SEC filing are not covered here — EDGAR has no structured XBRL for them and SEDAR+ offers no bulk API.

Name	Type	Meaning
`province`	string, in query optional	Filter by Canadian province, e.g. Ontario
`with_ticker`	boolean, in query optional · default `False`	Only companies with a resolvable ticker
`limit`	integer, in query optional · default `500`	—

Example

curl "$API/ca/universe" \
  -H "X-API-Key: $KEY"

GET /financials/recent

Recent Financial Publications

Recently filed financial reports (from sec_financials.filed), one entry per filing, enriched with ticker / name / ISIN from ticker_reference.

Name	Type	Meaning
`days`	integer, in query optional · default `2`	Look back this many days (by filing date)
`form`	string, in query optional	Filter by form, e.g. 10-K or 10-Q
`limit`	integer, in query optional · default `200`	—

Example

curl "$API/financials/recent" \
  -H "X-API-Key: $KEY"

POST /financials/sync/all

Sync Financials All

Resumable bulk sync of SEC XBRL financials over all equity tickers that have a CIK. Skips CIKs synced within min_days_between days (default 7, tracked in the sync_financials ledger), so a re-run only fetches what is due.

Returns a job_id — poll GET /tickers/jobs/{job_id}.

No parameters.

Request body `FinancialsSyncRequest`

Name	Type	Meaning
`min_days_between`	integer optional · default `7`	Min Days Between
`concurrency`	integer optional · default `5`	Concurrency
`rate_limit`	integer optional · default `300`	Rate Limit
`market`	string optional · default `stocks`	Market
`type_filters`	array optional · default `['STOCK', 'CS', 'ADRC']`	Type Filters
`active`	boolean optional · default `True`	Active
`limit`	integer optional	Limit

Example

curl -X POST "$API/financials/sync/all" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

GET /financials/{ticker_or_cik}

Get Financials

Read persisted SEC XBRL financials for a company from sec_financials, pivoted into one object per reporting period (metrics as a dict). No live fetch — run POST /financials/{ticker_or_cik} first to populate.

A period is (accn, form, start, end) — start belongs in the key, because a 10-Q tags both the quarter and the cumulative year-to-date figure against the same end. periodType (Q/H/9M/FY/instant) makes that explicit; period=quarter filters straight to quarterly values.

fy/fp/fiscalLabel describe the PERIOD (derived from the filing in which it was the reporting period), filingFy/filingFp the filing the value came from.

splitFactor and metricsSplitAdjusted restate EPS and share counts onto today's share basis. As-filed values in metrics remain untouched: filings from before a split state pre-split EPS, and that is exactly what mixes a time series across several filings (Netflix: EPS 5.87 vs 0.80 after a 10:1 split).

Name	Type	Meaning
`ticker_or_cik`	string, in path required	—
`form`	string, in query optional	Filter by form, e.g. 10-K or 10-Q
`end`	string, in query optional	Specific period end date, e.g. 2026-04-26
`metrics`	string, in query optional	Comma-separated metric filter, e.g. revenue,eps_diluted
`period`	string, in query optional · default `all`	Period length filter: all\|quarter\|ytd\|fy\|duration\|instant
`splitAdjust`	boolean, in query optional · default `True`	Add split-normalized per-share metrics
`dedupe`	boolean, in query optional · default `False`	One row per period: keep the most recently filed version
`latest`	boolean, in query optional · default `False`	Return only the most recent period
`limit`	integer, in query optional · default `120`	Max number of periods

Example

curl "$API/financials/SAP" \
  -H "X-API-Key: $KEY"

POST /financials/{ticker_or_cik}

Sync Financials

Fetch SEC XBRL companyfacts for a company and persist the core financial concepts (revenue, EPS, balance-sheet items, cashflow) into the sec_financials collection (source="sec.xbrl").

Accepts ticker, ISIN, CIK, or WKN — resolved to a CIK via EDGAR.

Name	Type	Meaning
`ticker_or_cik`	string, in path required	—

Example

curl -X POST "$API/financials/SAP" \
  -H "X-API-Key: $KEY"

GET /statements/esef/coverage

Esef Coverage

Per country: filings imported, entities, and failures by cause.

No parameters.

Example

curl "$API/statements/esef/coverage" \
  -H "X-API-Key: $KEY"

POST /statements/esef/sync

Esef Sync

Pulls ESEF filings — with a job document, a ledger and the ability to cancel.

The sync_esef ledger records every fxo_id with its status. That makes a failed filing distinguishable from one never attempted: failures stay visible and are retried deliberately, instead of quietly riding along on every run.

No parameters.

Request body `EsefSyncRequest`

Name	Type	Meaning
`countries`	array optional · default `['GB', 'DK', 'FR', 'NL', 'SE', 'IT']`	Countries
`stmts`	array optional · default `['BS', 'IS', 'CI', 'CF', 'EQ']`	Stmts
`force`	boolean optional · default `False`	Force
`concurrency`	integer optional · default `2`	Concurrency
`rate_limit`	integer optional · default `60`	Rate Limit
`limit`	integer optional	Limit

Example

curl -X POST "$API/statements/esef/sync" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

GET /statements/{ticker_or_cik}

Get Statements

Full as-filed financial statements from sec_statements (SEC DERA Financial Statement Data Sets): every line item incl. company-specific extension tags, in original presentation order, with the filer's labels. Populated by import_dera_financial_statements.py — no live fetch.

Name	Type	Meaning
`ticker_or_cik`	string, in path required	—
`stmt`	string, in query optional · default `CF`	Statement type: CF, BS, IS, CI, EQ (comma-separated for several)
`form`	string, in query optional	Filter by form, e.g. 10-K or 10-Q
`latest`	boolean, in query optional · default `False`	Return only the most recent filing per statement type
`limit`	integer, in query optional · default `8`	Max number of filings

Example

curl "$API/statements/SAP" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/compare

Compare

Several issuers in one table.

source, taxonomy and currency appear per row — the consumer MUST be able to see that they are holding an IFRS/EUR row against a us-gaap/USD row. We deliberately convert nothing.

Name	Type	Meaning
`identifiers`	string, in query required	Komma-separiert, max. 25
`metrics`	string, in query optional · default `revenue,net_income,total_assets`	—
`period`	string, in query optional · default `fy`	—
`years`	integer, in query optional · default `5`	—

Example

curl "$API/v1/fundamentals/compare?identifiers=SAP,MSFT,ORCL&metrics=revenue&years=2" \
  -H "X-API-Key: $KEY"

{
  "rows": [
    { "identifier": "SAP",  "source": "sec.dera", "taxonomy": "us-gaap",
      "currency": "EUR", "periods": { "2025-12-31": { "revenue": 34176000000 } } },
    { "identifier": "MSFT", "source": "sec.dera", "taxonomy": "us-gaap",
      "currency": "USD", "periods": { "2025-06-30": { "revenue": 281724000000 } } }
  ],
  "warnings": ["currency.mixed"]
}

GET /v1/fundamentals/mapping/gaps

Mapping Gaps

The most frequent unmapped lines — the basis for sharpening the mapping.

The lexicon grows out of measurement, not assumption; this endpoint is the measurement.

Name	Type	Meaning
`source`	string, in query optional	—
`stmt`	string, in query optional	—
`limit`	integer, in query optional · default `50`	—

Example

curl "$API/v1/fundamentals/mapping/gaps" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/metrics/catalog

Metrics Catalog

The canonical metric vocabulary — static and cacheable.

So nobody has to guess which names exist and what sign they carry.

No parameters.

Example

curl "$API/v1/fundamentals/metrics/catalog" \
  -H "X-API-Key: $KEY"

{
  "metrics": [
    { "name": "revenue", "stmt": "IS", "sign": "positive",
      "label": "Umsatzerlöse" },
    { "name": "cost_of_revenue", "stmt": "IS", "sign": "magnitude",
      "label": "Herstellungskosten" },
    { "name": "total_assets", "stmt": "BS", "sign": "positive",
      "label": "Bilanzsumme" }
  ]
}

GET /v1/fundamentals/ratios/reasons

Gruende

Die geschlossene Liste der Gruende, aus denen eine Kennzahl fehlt.

No parameters.

Example

curl "$API/v1/fundamentals/ratios/reasons" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/resolve/{identifier}

Resolve

Which issuer, which country, which pools — the debug endpoint.

Name	Type	Meaning
`identifier`	string, in path required	—

Example

curl "$API/v1/fundamentals/resolve/SAP" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/{identifier}/balance-sheet

Balance Sheet

Bilanz je Stichtag, jüngste zuerst.

Name	Type	Meaning
`identifier`	string, in path required	—
`period`	string, in query optional · default `FY`	FY \| Q \| YTD \| ALL
`limit`	integer, in query optional · default `8`	—
`source`	string, in query optional	—

Example

curl "$API/v1/fundamentals/SAP/balance-sheet" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/{identifier}/cash-flow

Cash Flow

Kapitalflussrechnung je Periode, jüngste zuerst.

Name	Type	Meaning
`identifier`	string, in path required	—
`period`	string, in query optional · default `FY`	FY \| Q \| YTD \| ALL
`limit`	integer, in query optional · default `8`	—
`source`	string, in query optional	—

Example

curl "$API/v1/fundamentals/SAP/cash-flow" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/{identifier}/coverage

Coverage

What exists for this company, and how reliable it is.

One call instead of guesswork: which pools, which statements, which time range, how many metrics were mapped.

Name	Type	Meaning
`identifier`	string, in path required	—

Example

curl "$API/v1/fundamentals/SAP/coverage" \
  -H "X-API-Key: $KEY"

{
  "entity": { "name": "SAP SE", "isin": "DE0007164600" },
  "pots": [
    { "source": "sec.dera", "stmts": ["IS", "BS", "CF"],
      "from": "2009-12-31", "to": "2025-12-31", "documents": 61 },
    { "source": "esef", "stmts": ["IS", "BS", "CF", "CI", "EQ"],
      "from": "2020-12-31", "to": "2025-12-31", "documents": 6 }
  ],
  "preferred": "sec.dera"
}

GET /v1/fundamentals/{identifier}/income-statement

Income Statement

Erfolgsrechnung je Periode, jüngste zuerst.

Name	Type	Meaning
`identifier`	string, in path required	—
`period`	string, in query optional · default `FY`	FY \| Q \| YTD \| ALL
`limit`	integer, in query optional · default `8`	—
`source`	string, in query optional	—

Example

curl "$API/v1/fundamentals/SAP/income-statement" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/{identifier}/key-metrics

Key Metrics

Kennzahlen, die den Abschluss verdichten oder mit dem Markt verbinden.

Name	Type	Meaning
`identifier`	string, in path required	—
`period`	string, in query optional · default `TTM`	TTM \| FY \| Q \| YTD
`limit`	integer, in query optional · default `8`	—
`currency`	string, in query optional · default `reported`	reported \| usd \| eur \| native — Waehrung der Marktkapitalisierung in den Kennzahlen

Example

curl "$API/v1/fundamentals/SAP/key-metrics" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/{identifier}/metrics

Metrics Only

The flat endpoint: metrics per period only, no lines, no tags.

This is the shape you can consume without any knowledge of XBRL.

Name	Type	Meaning
`identifier`	string, in path required	—
`metrics`	string, in query optional	Komma-separiert; leer = alle
`period`	string, in query optional · default `fy`	fy \| quarter \| ytd \| instant \| all
`years`	integer, in query optional · default `10`	—
`source`	string, in query optional	—

Example

curl "$API/v1/fundamentals/SAP/metrics?metrics=revenue,net_income&years=3" \
  -H "X-API-Key: $KEY"

{
  "entity": { "name": "SAP SE", "isin": "DE0007164600" },
  "source": "sec.dera",
  "periods": [
    { "end": "2025-12-31", "type": "FY", "currency": "EUR",
      "metrics": { "revenue": 34176000000, "net_income": 3086000000 } },
    { "end": "2024-12-31", "type": "FY", "currency": "EUR",
      "metrics": { "revenue": 34176000000, "net_income": 3086000000 } }
  ]
}

GET /v1/fundamentals/{identifier}/ratios

Ratios

Verhaeltniszahlen aus dem Abschluss — Margen, Renditen, Umschlag.

Name	Type	Meaning
`identifier`	string, in path required	—
`period`	string, in query optional · default `TTM`	TTM \| FY \| Q \| YTD
`limit`	integer, in query optional · default `8`	—
`currency`	string, in query optional · default `reported`	reported \| usd \| eur \| native — Waehrung der Marktkapitalisierung in den Kennzahlen

Example

curl "$API/v1/fundamentals/SAP/ratios" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/{identifier}/segments

Segments

Umsatz nach Segment, Region, Produkt und Kunde — mit Probe je Aufgliederung.

Name	Type	Meaning
`identifier`	string, in path required	—
`art`	string, in query optional	segment \| region \| produkt \| kunde
`jahr`	integer, in query optional	Kalenderjahr des Stichtags

Example

curl "$API/v1/fundamentals/SAP/segments" \
  -H "X-API-Key: $KEY"

GET /v1/fundamentals/{identifier}/statements

Statements

Complete statements in one uniform shape.

periods is the table header, lines[].values are the cells — identical for all four pools. The label and the tag stand as reported, next to the canonical metric.

Name	Type	Meaning
`identifier`	string, in path required	—
`stmt`	string, in query optional · default `IS,BS,CF`	IS,BS,CF,CI,EQ
`period`	string, in query optional · default `all`	—
`years`	integer, in query optional · default `5`	—
`source`	string, in query optional	—
`lines`	string, in query optional · default `all`	all \| mapped

Example

curl "$API/v1/fundamentals/SAP/statements?stmt=IS&years=2" \
  -H "X-API-Key: $KEY"

{
  "entity": { "name": "SAP SE", "isin": "DE0007164600", "country": "DE" },
  "source": "sec.dera",
  "statements": [
    {
      "stmt": "IS",
      "currency": "EUR",
      "crossChecked": true,
      "structureConfidence": "high",
      "periods": [
        { "id": "p0", "end": "2025-12-31", "type": "FY" },
        { "id": "p1", "end": "2024-12-31", "type": "FY" }
      ],
      "lines": [
        { "order": 1, "depth": 0, "label": "Total revenue",
          "tag": "Revenues", "taxonomy": "us-gaap", "metric": "revenue",
          "values": { "p0": 34176000000, "p1": 34176000000 } },
        { "order": 2, "depth": 1, "label": "Cost of revenue",
          "tag": "CostOfRevenue", "metric": "cost_of_revenue",
          "values": { "p0": 9834000000, "p1": 9612000000 } }
      ]
    }
  ],
  "warnings": []
}

Fundamentals

Get Ca Universe

Example

Recent Financial Publications

Example

Sync Financials All

Request body FinancialsSyncRequest

Example

Get Financials

Example

Sync Financials

Example

Esef Coverage

Example

Esef Sync

Request body EsefSyncRequest

Example

Get Statements

Example

Compare

Example

Mapping Gaps

Example

Metrics Catalog

Example

Gruende

Example

Resolve

Example

Balance Sheet

Example

Cash Flow

Example

Coverage

Example

Income Statement

Example

Key Metrics

Example

Metrics Only

Example

Ratios

Example

Segments

Example

Statements

Example

Request body `FinancialsSyncRequest`

Request body `EsefSyncRequest`