---
title: "Retrieve Company Financials"
method: GET
path: "/companies/{id}/financials/"
tags: ["Companies"]
---

# Retrieve Company Financials

`GET /companies/{id}/financials/`

## Request

- Base URL: `https://api.financialreports.eu`
- URL: `https://api.financialreports.eu/companies/{id}/financials/`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

**Experimental endpoint — the response schema may change without an API version bump.**

Returns standardized financial KPIs for a company as a structured document: a company envelope containing `periods`, each holding its Income Statement, Balance Sheet and Cash Flow `statements`, each holding `line_items`.

When several filings report the same period, the candidates are ranked and one statement is selected. A filing the company reports its own financials in beats one it does not, such as an employee benefit plan's Form 11-K or a filing notice. A statement in the currency the company reports in beats an off-currency one, which is usually a subsidiary's filing that resolved to the parent. A complete statement beats a fragment, such as the single restated line in an amendment. Only then does the most recently published filing win. A selected statement denominated in a currency other than the company's carries `currency_mismatch: true`.

**Currency is as presented, and is never converted.** `currency` is the currency the statement is denominated in as the filer presented it - the presentation currency, not the functional currency, which we do not capture. No figure in this payload is ever translated into another currency at any rate, and `value` being in absolute units makes values comparable across scales, not across currencies. A company that re-presents in a new currency therefore produces a series whose units change partway through, with no restatement of the earlier years: compare `currency.code` across periods before aggregating or charting. A line item may carry its own `currency` differing from the statement's - that is a dual-currency filing, not an error.

Each statement carries `source_filing`: the filing the figures were read from, with `document_url` and `viewer_url` pointing at our hosted copy of that document. This is returned to every account. The publishing authority's identity and its own direct URL remain masked unless the account has source unmasking enabled. The full `sources` array — every contributing filing, including candidates that selection rejected — is returned only with source unmasking (`sources_masked` reports which applies). `as_of=YYYY-MM-DD` restricts selection to filings released on or before that date; it does not reproduce the values served on that date, because figures are corrected in place. Each line item's `updated_at` says when its value was last written. `as_known_at` returns each value as we held it at a past time (recorded since 2026-10-19T17:05:18Z), selected under today's rules, and `include=revisions` lists each value's recorded changes.

Use the `depth` and `parent_code` fields on each line item to render the Capital IQ-style statement hierarchy.

`value` and `raw_value` are exact **decimal strings**, not numbers - parse them with a decimal type. `raw_value` and `scale` come back `null` when the figure was computed rather than read off the page. `source_page` is reserved and is currently `null` on every line item; provenance is filing-level. `confidence` is non-null only where the KPI verifier independently re-derived the figure and agreed - null means unjudged, not low-confidence.

**Scope - this is not the bulk dataset.** This endpoint serves one selected statement per (fiscal year, period, statement type). The comparative statements themselves, restatements, the `validation_n_hard`/`validation_n_soft` quality flags, `derivation_method` and stable row ids are available only in the S3 `line_items/` parquet delivery, not here at any plan level. The `is_comparative` flag on each statement does tell you whether the selected figures were read from a later report's prior-year column.

**Cost:** 40 credits per request, flat - independent of how many periods or line items are returned, and not reduced by filtering. Pay-as-you-go accounts read the full history by default. If an account has been limited to a rolling window on filing release date, the response carries a `history_window` object; read the effective limit from `history_window.max_history_days`. The deep back-catalogue is not reachable through such a window.

**Access Level Required:** Requires **Financial KPIs (Level 3)**.

## Path parameters

- `id` integer, required

## Query parameters

- `as_known_at` string
- `as_of` string
- `fiscal_period` '9M' | 'FY' | 'H1' | 'H2' | 'Q1' | 'Q2' | 'Q3' | 'Q4'
- `fiscal_year` integer
- `fiscal_year_from` integer
- `fiscal_year_to` integer
- `include` 'revisions'
- `line_items` string
- `statement_type` 'BS' | 'CFS' | 'IS'

## Response `200`

Structured company financials document.

- object
  - `company_id` integer, required
  - `template` 'industrial' | 'bank' | 'insurer': The company's KPI template. Banks and insurers also get their template's own line items; see `templates` on /api/line-item-definitions/ for which items are meaningful for it.
  - `currency` object, nullable
    - `code` string
    - `name` string
    - `symbol` string, nullable
  - `sources_masked` boolean, required
  - `filters` object, required
    - `statement_type` string, nullable
    - `fiscal_year` integer, nullable
    - `fiscal_year_from` integer, nullable
    - `fiscal_year_to` integer, nullable
    - `fiscal_period` string, nullable
    - `line_items` string[], nullable
    - `as_of` string, date, nullable
    - `as_known_at` string, date-time: The instant values were reconstructed at, in UTC: a bare date is echoed as the end of that day, a future time as now.
    - `include` string[]
  - `period_count` integer, required
  - `periods` object[], required
    - `fiscal_year` integer, nullable
    - `fiscal_period` string, nullable
    - `period_start_date` string, date, nullable
    - `period_end_date` string, date, nullable
    - `statements` object[]
      - `statement_type` 'IS' | 'BS' | 'CFS', required
      - `statement_type_display` string, required
      - `currency` object, nullable, required
        - `code` string
        - `name` string
        - `symbol` string, nullable
      - `currency_mismatch` boolean, required: True when this statement's currency differs from the company's modal reporting currency - the code held by more than 60% of the statements we serve for that company. When no code clears 60% (a genuinely dual-currency issuer, or one mid-transition) there is no modal currency and this is `false` on every statement, including the off-currency ones. A data-quality signal, not provenance, so it is returned even to masked accounts. It compares a statement against its company's history; it does not mean the statement itself mixes currencies.
      - `extraction` object, required
        - `model` string, nullable
        - `prompt_version` string, nullable
        - `extracted_at` string, date-time, nullable
        - `notes` string, nullable
      - `line_items` object[], required
        - `code` string, required
        - `name` string, required
        - `statement_type` 'IS' | 'BS' | 'CFS' | 'SUP', required: The KPI's home statement in the taxonomy, which can differ from the statement it was extracted onto. `SUP` appears here but is never a statement type.
        - `depth` integer, required
        - `parent_code` string, nullable, required
        - `sort_order` integer, required
        - `value` string, decimal, nullable, required: Value in absolute units, as an exact DECIMAL STRING - not a number. Parse with a decimal type; float loses precision at financial magnitudes. NULL when the figure was quarantined as unrecoverable.
        - `raw_value` string, decimal, nullable, required: The figure as printed in the document, as an exact decimal string. When non-null, `value == raw_value * multiplier(scale)` to rounding (within 1% or 0.01). NULL - together with `scale` - when `value` is null, when `value` was rebuilt by a repair sweep (the `balanced_plug` and `debt_hierarchy` derivations), or whenever `raw_value * scale` does not reproduce `value` (e.g. a value rescaled against the company's other filings), because then the printed figure is no longer the value's provenance. A `partial_aggregate` total is tagged at extraction time, where `raw_value` IS the value's provenance, so it is served normally.
        - `scale` 'units' | 'thousands' | 'lakhs' | 'millions' | 'crores' | 'billions' | 'null', nullable, required: Reporting scale of `raw_value`. Withheld with it.
        - `currency` string, nullable, required: The value's own currency code, which may differ from the statement's reporting currency for per-share figures. NULL for ratios.
        - `confidence` number, float, nullable, required: Confidence that this value is the figure the document states, or null where nothing has judged it. Non-null only on rows the KPI verifier SERVED: it runs a second, independent selection pass over the filing and agrees with the extracted value, and the number is that pass's probability for the row it picked. Null does NOT mean low confidence - it means unjudged, which is every row the verifier has not yet swept and every row it sent to review instead of serving. Treat it as a filter, not a score: branch on non-null, do not compare nulls.
        - `source_page` integer, nullable, required: RESERVED - currently null on every line item. Provenance is filing-level (`sources`), not page-level. Deliberately still reserved: the KPI verifier knows the line of the converted markdown it read a value from, which is not a page number, so it does not write one here.
        - `revisions` object[]: Present only with `include=revisions`: every recorded change to this value, oldest first (with `as_known_at`, up to that time). Empty when none was recorded. Recording started 2026-10-19T17:05:18Z; `pre_recording` entries are older corrections whose `changed_at` is approximate (the change happened at or before it).
          - `changed_at` string, date-time, required
          - `op` 'insert' | 'update' | 'delete' | 'pre_recording', required: `insert`: first written. `update`: corrected. `delete`: removed (it may be written again by a later `insert`). `pre_recording`: a correction from before recording started, approximate time.
          - `old_value` string, decimal, nullable, required: `value` before the change; null on insert.
          - `new_value` string, decimal, nullable, required: `value` after the change; null on delete. A change to another field of the value (its as-reported figure, currency or statement) has old_value == new_value.
          - `reason` 'extraction' | 'cleanup' | 'repair' | 'manual' | 'unknown', required: `extraction`: (re-)extraction from the document. `cleanup`: an automated rule-based correction. `repair`: an operator-run correction pass. `manual`: a hand edit. `unknown`: not recorded.
        - `withdrawn_reason` 'reattributed' | 'purged': Present only with `as_known_at`, and only on a statement (and on its values) that was served for this company at that time and is not served for it today because it was withdrawn: `reattributed` - the statement now belongs to another company record, where it may be served; `purged` - reserved: its filing was removed altogether (not served yet; the filing's type, release time and links would be null unless recorded). Absent everywhere else.
        - `updated_at` string, date-time, required: When this value was last written. Equal to the extraction time for an untouched value; moves when a later correction pass rewrites the value in place (a re-extraction replaces the whole statement and sets a new one). Compare it with the value from your previous poll to detect a changed figure without diffing. It does not move when a whole statement is withdrawn or when a different filing starts supplying the period - watch `source_filing` for that.
      - `withdrawn_reason` 'reattributed' | 'purged': Present only with `as_known_at`, and only on a statement (and on its values) that was served for this company at that time and is not served for it today because it was withdrawn: `reattributed` - the statement now belongs to another company record, where it may be served; `purged` - reserved: its filing was removed altogether (not served yet; the filing's type, release time and links would be null unless recorded). Absent everywhere else.
      - `is_comparative` boolean, required: True when this period was read from the comparative (prior-year) column of a later report, because no report presented it as its own period. A data-quality signal, not provenance, so it is returned even to masked accounts.
      - `source_filing` object, nullable
        - `id` integer, nullable
        - `filing_type` string, nullable: Our own normalised filing-type code, not the publishing authority's label.
        - `release_datetime` string, date-time, nullable
        - `document_url` string, uri, nullable: Direct link to our hosted copy of the document. Null in the rare case we hold no document for the filing.
        - `viewer_url` string, uri, nullable: Link to the document on our own platform.
      - `sources` object[]: Every filing that reported this (period, statement_type), including the candidates selection rejected. Omitted unless the account has source unmasking. The selected filing is always available as `source_filing`.
        - `filing_id` integer
        - `filing_type` string, nullable
        - `release_datetime` string, date-time, nullable
        - `is_selected` boolean: Exactly one entry per statement is the selected one.
  - `notice` string
  - `history_window` object
    - `limited` boolean
    - `max_history_days` integer
    - `cutoff` string, date-time
    - `detail` string

## Other responses

- `400`: Invalid query parameter.
- `403`: Missing or invalid API key, or the plan does not include this endpoint.
- `404`: Company not found.
- `429`: Rate limit, plan quota or spend cap reached.

## Changes

- **2026-10-20** `55935bdabd20`: 2 info
  - added the optional property `periods/items/statements/items/line_items/items/withdrawn_reason` to the response with the `200` status
  - added the optional property `periods/items/statements/items/withdrawn_reason` to the response with the `200` status
- **2026-10-19** `a780251d6b05`: 5 info
  - added the new optional `query` request parameter `as_known_at`
  - added the new optional `query` request parameter `include`
  - added the optional property `filters/as_known_at` to the response with the `200` status
  - added the optional property `filters/include` to the response with the `200` status
  - …1 more

[Operation history](https://skmtc.dev/financialreports/apis/financialfilings-api/changes/companies/:id/financials/get.md)

---

[API](https://skmtc.dev/financialreports/apis/financialfilings-api.md) · [All operations](https://skmtc.dev/financialreports/apis/financialfilings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/financialreports/apis/financialfilings-api/revisions/55935bdabd20?raw)