--- title: "Get enriched company profile" method: GET path: "/v1/company/{company_number}" tags: ["Company"] --- # Get enriched company profile `GET /v1/company/{company_number}` ## Request - Base URL: `https://api.registrum.co.uk` - URL: `https://api.registrum.co.uk/v1/company/{company_number}` - Auth: API key in header `X-API-Key` Get an enriched company profile by company number. Returns the company's core details plus derived fields that aren't available from the raw Companies House data: - **company_age_years** - calculated from incorporation date - **company_category** - inferred size (micro/small/medium/large) based on accounts type - **accounts.overdue** - whether annual accounts are past their filing deadline - **confirmation_statement.overdue** - whether the confirmation statement is overdue Data is cached for 30 days. If the Companies House API is down, stale cached data is returned with `cached: true` in the response. **Example:** `/v1/company/00445790` returns the enriched profile for Tesco PLC. --- **Upstream usage:** 1 upstream call per unique company on first fetch (cached for 30 days). Repeating a lookup for the same company within 30 days is free - no upstream call is made. At high volume, you can safely look up ~100 different companies per minute before responses begin to slow. Beyond that, requests queue briefly (typically a few seconds) while upstream capacity recovers. ## Path parameters - `company_number` string, required: The Companies House company number. 8 alphanumeric characters (e.g., `00445790` for Tesco PLC, `SC123456` for a Scottish company). Numeric-only numbers are automatically zero-padded, so `445790` and `00445790` both work. ## Response `200` Enriched company profile returned successfully - CompanyEnvelope: Response envelope for GET /v1/company/{company_number}. - `status` string: 'success' or 'error' - `data` CompanyProfile: An enriched company profile with data derived from the Companies House record. - `company_number` string, required: 8-character Companies House number (e.g., '00445790') - `company_name` string, required: Official registered company name - `company_status` string, nullable: Current status: 'active', 'dissolved', 'liquidation', 'receivership', etc. - `company_type` string, nullable: Legal type: 'ltd', 'plc', 'llp', etc. - `date_of_creation` string, date, nullable: Date the company was incorporated - `company_age_years` integer, nullable: Calculated years since incorporation - `registered_office_address` Address: A UK registered office address. - `premises` string, nullable: Building name or number - `address_line_1` string, nullable: Street address - `address_line_2` string, nullable: Additional address line - `locality` string, nullable: Town or city - `region` string, nullable: County or region - `postal_code` string, nullable: UK postcode - `country` string, nullable: Country - `sic_codes` string[]: Standard Industrial Classification codes describing the business activity - `accounts` AccountsInfo: Filing status for the company's annual accounts. - `last_accounts_type` string, nullable: Type of last filed accounts (e.g., 'full', 'micro-entity', 'group') - `last_accounts_made_up_to` string, date, nullable: Period end date of last filed accounts - `next_accounts_due` string, date, nullable: Deadline for next accounts filing - `overdue` boolean: True if accounts are past their filing deadline - `confirmation_statement` ConfirmationStatement: Filing status for the company's annual confirmation statement. - `last_made_up_to` string, date, nullable: Date of last confirmation statement - `next_due` string, date, nullable: Deadline for next confirmation statement - `overdue` boolean: True if confirmation statement is overdue - `company_category` string, nullable: Inferred size: 'micro', 'small', 'medium', 'large', 'dormant' - `has_charges` boolean, nullable: Whether the company has registered charges (e.g., mortgages) - `has_insolvency_history` boolean, nullable: Whether the company has any insolvency history - `summary_md` string, nullable: Pre-formatted Markdown summary of the company profile, suitable for embedding directly into an LLM prompt or agent reasoning chain. Covers status, address, SIC codes, accounts filing dates, and key flags. Null only if company data is missing. - `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 at Companies House - `422`: Validation Error - `502`: Companies House API is 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)