--- title: "Get structured financial data from filed accounts" method: GET path: "/v1/company/{company_number}/financials" tags: ["Financials"] --- # Get structured financial data from filed accounts `GET /v1/company/{company_number}/financials` ## Request - Base URL: `https://api.registrum.co.uk` - URL: `https://api.registrum.co.uk/v1/company/{company_number}/financials` - Auth: API key in header `X-API-Key` Get structured financial data extracted from the company's latest filed iXBRL accounts. Returns balance sheet and profit & loss figures for the current and prior reporting year, where available. All monetary values are in actual GBP (e.g. `5200000` = £5,200,000). **What you get:** - **profit_and_loss** - turnover, gross profit, operating profit, profit before/after tax, depreciation. Only available for companies that file full accounts. - **balance_sheet** - fixed assets, current assets, creditors, net assets, equity. Available for virtually all UK companies (legally mandated). - **other** - average number of employees during the period. - **data_quality** - tells you exactly what was extracted, what's missing, and why. Use `accounts_type` to understand field availability, and `filing_type` / `filed_on` / `period_end_source` to audit *which* Companies House filing the figures came from. **Which filing is used:** the most recent filing that is genuinely a set of annual accounts for this company (`AA`, `AAMD`, legacy `AC(NI)`). Companies House files change-of-accounting- reference-date forms (`AA01`) and similar administrative documents in the same filing-history category, and they can be filed after the last real accounts - those are skipped. If `turnover` is null, `data_quality.turnover_untagged_suspected: true` means the filing probably prints turnover without an iXBRL tag: the figure is in the filed document but not readable from its tags. `data_quality.period_end` is the accounting period end, not the date the filing was submitted; the submission date is `data_quality.filed_on`. **Why some fields are null:** UK law allows smaller companies to withhold P&L data: - **micro** (`accounts_type: "micro"`) - balance sheet only; turnover and profit are legally exempt from disclosure. ~50% of UK companies file micro accounts. - **abbreviated** (`accounts_type: "abbreviated"`) - balance sheet only; small company exemption from P&L disclosure. - **full** (`accounts_type: "full"`) - all fields available (medium/large companies). If a field is null, check `data_quality.missing_fields` for the list and `data_quality.has_profit_loss` to understand whether P&L was filed at all. **Sources:** Data is extracted from whichever format is available in the filed accounts: - **iXBRL** (inline XBRL) - structured markup, high precision, `data_quality.source: "ixbrl"`. Covers most UK companies since CH made iXBRL filing mandatory for most company types. - **PDF** - text/table extraction attempted as a fallback. In practice, PDF annual accounts on Companies House are rendered as image-based PDFs (from design software or scanning) and yield no extractable text. If no parseable filing is available (no digital filing, or an image-based PDF) or the company is dissolved/in liquidation/administration, returns HTTP 200 with `available: false`, `unavailable_reason` (`"dissolved"`, `"no_ixbrl_filings"` or `"image_pdf"`), `company_status`, and accounts metadata from the company profile. This lets pipelines branch cleanly without exception handling. HTTP 404 is only returned when the company number itself does not exist in Companies House. Data is cached for 90 days. Financial filings don't change between annual submissions, so cached data is reliably current. **Example:** `/v1/company/00445790/financials` returns Tesco PLC's latest filed accounts. --- **Upstream usage:** 2–3 upstream calls on cold cache (filing history + document metadata + document download). After first fetch, cached for 90 days at no cost. On cold cache, limit to ~30 different companies per minute to stay within upstream capacity. ## Path parameters - `company_number` string, required: Companies House company number (e.g. `01234567` for a typical limited company). Numeric-only numbers are automatically zero-padded. ## Response `200` Financial data extracted and returned successfully - FinancialsEnvelope: Response envelope for GET /v1/company/{company_number}/financials. - `status` string: 'success' or 'error' - `data` union: Extracted financials, or the `FinancialsUnavailable` shape (`available: false`) when no accounts could be read - CompanyFinancials: Structured financial data extracted from a company's filed accounts. Source may be iXBRL (structured markup - precise) or PDF (text/table parsing - good coverage but check data_quality.field_confidence for per-field reliability). All monetary values are in actual GBP (pounds). A value of 5200000 means £5,200,000. The data_quality section explains what was and wasn't extracted, and why. Use accounts_type to understand what fields to expect: - 'full': all sections available - 'abbreviated': balance sheet only (no turnover or profit) - 'micro': balance sheet only (micro-entities are legally exempt from P&L disclosure) - 'dormant': minimal balance sheet only - `company_number` string, required: Companies House company number. - `company_name` string, nullable: Registered company name. - `accounts_type` string, required: Type of accounts filed. Mirrors data_quality.accounts_type for convenience. - `period_end` string, nullable: Accounting period end date (YYYY-MM-DD). - `period_start` string, nullable: Accounting period start date (YYYY-MM-DD). - `currency` string: Currency of all monetary values. - `data_quality` DataQuality, required: Metadata about what was extracted and why fields may be missing. This is the transparency layer - every null in profit_and_loss or balance_sheet has an explanation here. - `source` string: How financial data was extracted. 'ixbrl' = structured inline XBRL markup (high precision). 'pdf_extracted' = PDF text/table parsing (good coverage, see field_confidence for per-field reliability). - `accounts_type` string, required: Type of accounts filed: 'full', 'abbreviated', 'micro', 'dormant', or 'unknown'. Micro and abbreviated accounts legally exclude P&L - turnover and profit fields will be null. This is expected, not a data error. Changed 2026-08-01 (CH-Api#61): this was previously derived by keyword-matching Companies House's machine-readable filing code against a list of English prose phrases, and anything unmatched defaulted to 'full'. About 17% of filers were mis-typed - most commonly `unaudited-abridged`, which is now correctly 'abbreviated'. Values that were already right are unchanged. See `accounts_description_code` for the verbatim Companies House code and `accounts_type_source` for how this value was resolved. - `accounts_type_source` string, nullable: How `accounts_type` was determined: 'ch_filing_description' (read from the Companies House filing code - the normal case), 'xbrl_namespace' (inferred from the accounting taxonomy declared inside the document, e.g. FRS-105 = micro), 'pl_presence_inference' (the filing carries no type but the document plainly contains a profit and loss account), or 'unresolved' (nothing identified it; `accounts_type` is 'unknown' and scoring falls back to the balance sheet only). - `accounts_description_code` string, nullable: The verbatim Companies House accounts-type code from the filing description, e.g. 'total-exemption-full', 'unaudited-abridged', 'micro-entity'. Null when the filing description carries no accounts type at all (`accounts-with-made-up-date`). Exposed so you can apply your own classification rather than trusting ours. - `completeness` number, required: Fraction of expected fields successfully extracted (0.0–1.0). The denominator is set per accounts_type: 20 fields for 'full', 13 for 'abbreviated', 5 for 'micro', 4 for 'dormant', and 12 (balance sheet only) for 'unknown'. A score of 0.85 on full accounts is normal. Note this score generally ROSE on 2026-08-01 for abridged and small-company filers (CH-Api#61): they had been scored against a profit and loss account they are legally forbidden to file. - `fields_attempted` integer, required: Number of fields expected for this accounts_type - the denominator of `completeness`. 20 for 'full', 13 for 'abbreviated', 5 for 'micro', 4 for 'dormant', 12 for 'unknown'. - `fields_extracted` integer, required: Number of fields successfully extracted from the filing. - `has_profit_loss` boolean, required: Whether P&L data (turnover, profit, etc.) was found in the filing. False for micro-entities and abbreviated accounts - this is legal, not an error. - `has_balance_sheet` boolean, required: Whether balance sheet data was found. Should be True for all UK companies. - `missing_fields` string[], required: List of field names that are null in this response. For full accounts, this may include optional fields not filed. For micro/abbreviated accounts, this will include all P&L fields. - `field_confidence` object: Per-field confidence score (0.0–1.0) for PDF-extracted data. Empty for iXBRL (iXBRL extraction is deterministic - implicit 1.0). Use this to filter out low-confidence PDF extractions. Scores below 0.70 indicate a broad/fuzzy label match. - `period_end` string, nullable: Accounting period end date (YYYY-MM-DD) - the date the accounts are made up to. Until 2026-08-01 (CH-Api#60) this was the date the filing was submitted to Companies House, which is a different and later date (commonly by months). It is now taken from the filing's `made_up_date`, or from the document's own reporting contexts. See `period_end_source` for which. The submission date is still available, unchanged, as `filed_on`. - `period_end_source` string, nullable: Where `period_end` came from, so you can audit it: 'description_values.made_up_date' (the Companies House filing's own made-up-to date - the normal case), 'document_context' (the reporting period declared inside the filed document itself), 'description_values.action_date', or 'filing_date' (a legacy paper filing that carries no period metadata - treat with caution). - `filed_on` string, nullable: The date the selected filing was submitted to Companies House (YYYY-MM-DD). Distinct from `period_end`: accounts for a period ending 31 December are typically filed the following year. - `filing_type` string, nullable: The Companies House form code of the filing these figures were extracted from: 'AA' (annual accounts), 'AAMD' (amended accounts) or 'AC(NI)' (legacy Northern Irish accounts). Administrative forms in the same filing-history category - 'AA01' change of accounting reference date and friends - are never selected (CH-Api#60). - `period_start` string, nullable: Accounting period start date (YYYY-MM-DD), where available. - `currency` string: Currency of all monetary values. Almost always GBP for UK companies. - `taxonomy_version` string, nullable: XBRL taxonomy version detected from the filing namespace. - `turnover_tag_unmapped` boolean, nullable: Parse-failure flag for turnover (CH-Api#150). true = the iXBRL document contains a turnover/revenue-named tag that we do not recognise AND no turnover was extracted, so a null turnover here is probably our miss, not the filing omitting it - see `turnover_unmapped_concepts`. false = either turnover was extracted or no such tag exists (null turnover then genuinely means not published). null = not checked: PDF-extracted data, or a response cached before this check existed. - `turnover_unmapped_concepts` string[], nullable: Up to 5 raw tag names (e.g. 'core:TurnoverFromWidgets') behind `turnover_tag_unmapped: true`. Empty list when the flag is false; null when not checked (PDF data or a pre-existing cached response). - `turnover_untagged_suspected` boolean, nullable: true = turnover is null because the filing probably prints the Turnover row without any iXBRL tag (CH-Api#179): cost of sales or gross profit is tagged but no turnover is, and no turnover-named tag was missed. The figure exists in the filed document but cannot be read from its tags; we do not guess it from text. false = turnover extracted, or no evidence the filing has sales. null = not checked: PDF-extracted data, or a response cached before this check. - `dimensioned_fallback_fields` string[], nullable: Fields whose value comes from a dimension-qualified fact (e.g. one segment or business line) because the filing tags no entity-level total for them (CH-Api#180). Treat those values as a part, not the whole. Empty list when every value is entity-level; null for PDF-extracted data. - `profit_and_loss` ProfitAndLoss, required: Profit & loss account figures. Only available in full accounts. - `turnover` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `gross_profit` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `operating_profit` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `profit_before_tax` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `tax` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `profit_after_tax` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `depreciation` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `balance_sheet` BalanceSheet, required: Balance sheet figures. Available for all companies (UK law mandates it). - `fixed_assets` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `intangible_assets` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `current_assets` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `stocks` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `debtors` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `cash` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `creditors_within_one_year` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `creditors_after_one_year` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `net_assets` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `equity` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `share_capital` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `retained_earnings` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `other` OtherMetrics, required: Non-financial metrics extracted from accounts. - `employees` FinancialValue: A financial figure with current and prior year comparison. - `current` integer, nullable: Value for the current reporting period, in actual GBP (£). Null if not reported in this filing. - `prior` integer, nullable: Comparative value for the prior reporting period, in actual GBP (£). Null if not included in the filing. - `summary_md` string, nullable: Pre-formatted Markdown table of key financial figures, suitable for embedding directly into an LLM prompt or agent reasoning chain. Covers turnover, profit, net assets, and employees with current and prior year comparisons. Null if no financial data is available (e.g. image-based PDF filing). - FinancialsUnavailable: The `/financials` payload when no accounts could be read for the company. Returned (with HTTP 200) instead of `CompanyFinancials` when the company has no filed accounts we can parse. Check `available` before reading anything else: when false, the `profit_and_loss`, `balance_sheet`, `other`, `data_quality` and `summary_md` keys are present but null. - `company_number` string, required: Companies House company number. - `company_name` string, nullable: Registered company name. - `available` boolean, required: Always false in this shape. `CompanyFinancials` payloads do not use this key to signal success; distinguish the two shapes by this key's presence. - `unavailable_reason` string, required: Why no financial data could be returned (e.g. no accounts filed, or filed as an image-only document). - `company_status` string, nullable: Company status from the Companies House profile (e.g. 'active'). - `accounts_category` string, nullable: Companies House accounts category of the last filing (e.g. 'full', 'group', 'micro-entity'). - `last_accounts_date` string, nullable: Period end date of the last filed accounts (YYYY-MM-DD). - `accounts_next_due` string, nullable: Date the next accounts are due (YYYY-MM-DD). - `profit_and_loss` unknown - `balance_sheet` unknown - `other` unknown - `data_quality` unknown - `summary_md` unknown - `cached` boolean: True if this response was served from cache rather than fetched live - `cache_age_seconds` integer, nullable: How many seconds ago this data was fetched from Companies House (null if not cached) - `fetched_at` string, nullable: ISO 8601 instant (UTC) when this data was actually fetched from Companies House. Use this, not cache_age_seconds, to show a user when the data was last checked: an age is measured at the moment this response was produced, so anything that caches the response downstream will overstate freshness by however long it held it. This instant does not drift. Null when unknown - render nothing rather than a guessed date. - `data_source` string: 'live' - fetched from Companies House right now; 'cached' - served from local cache (data is recent, no upstream call needed); 'cached_rate_conserved' - served from cache because the CH API budget is above 70% utilisation; data may be up to 30 days old in this state - `credits_used` integer: Number of API credits consumed by this request - `credits_remaining` integer, nullable: API credits remaining this month (null in dev mode) ## Other responses - `400`: Invalid company number format, or the company number is empty (blank path segment) - `401`: Missing or invalid API key - `404`: Company not found (company number does not exist in Companies House). - `422`: Validation Error - `502`: Companies House API or Document API temporarily unavailable - `503`: Request shed to protect shared Companies House capacity; retry after the seconds given in the Retry-After header --- [API](https://skmtc.dev/registrum/apis/registrum-api.md) · [All operations](https://skmtc.dev/registrum/apis/registrum-api/llms.txt) · [OpenAPI document](https://skmtc.dev/registrum/apis/registrum-api/revisions/2bf0ecf7cc02?raw)