# UK Companies House The UK Companies House API allows you to search for and retrieve detailed information about companies and officers registered with Companies House in the United Kingdom. Reports can be returned as **JSON** for system integration or **PDF** for human-readable documents. ## What is Companies House? Companies House is the United Kingdom's registrar of companies. It maintains the official register of all incorporated companies in England, Wales, Scotland, and Northern Ireland. The register includes information about company registration details, directors, secretaries, persons with significant control (PSCs), and filed documents. The Companies House API enables you to search the register, retrieve company reports, officer reports, and filed documents on demand. This data plays an important role in due-diligence, KYB (Know Your Business), compliance, and operational workflows. ## Available Functions The UK Companies House API provides the following functions: - **Company Search** - Search for companies by name or company number - **Officer Search** - Search for officers (directors, secretaries) by name - **Company Report** - Generate comprehensive company reports with officers, PSCs, and filing history - **Officer Report** - Generate reports on individual officers including their appointments - **Document Download** - Retrieve filed documents (annual accounts, confirmation statements, etc.) ## API Usage There are seven API endpoints used to interact with UK Companies House data: | Endpoint Name | Description | |---------------|-------------| | [Company House Search](#company-house-search) | Searches for companies by name or company number | | [Company House Officer Search](#company-house-officer-search) | Searches for officers by name | | [Company House Report](#company-house-report) | Requests a comprehensive company report | | [Retrieve Company House Report](#retrieve-company-house-report) | Retrieves the results of a company report request | | [Company House Officer Report](#company-house-officer-report) | Requests a comprehensive officer report | | [Retrieve Company House Officer Report](#retrieve-company-house-officer-report) | Retrieves the results of an officer report request | | [Company House Document](#company-house-document) | Downloads a filed document by document ID | ## Quick Start The following sections show the typical workflow for using the UK Companies House API. ### Company Report Workflow 1. Use **Company House Search** to find a company by name or company number. 2. Identify the company of interest and note its `company_number`. 3. Use the **Company House Report** endpoint to request the report, providing the `company_number`. 4. Use **Retrieve Company House Report** with the returned `api_reference` to poll for the report and retrieve it in JSON or PDF format. ### Officer Report Workflow 1. Use **Company House Officer Search** to search for an officer by name. 2. From the matches, select the officer of interest and note the `officer_id`. 3. Use the **Company House Officer Report** endpoint to request the report, providing the `officer_id`. 4. Use **Retrieve Company House Officer Report** with the returned `api_reference` to poll for the report and retrieve it in JSON or PDF format. ### Document Download Workflow 1. Retrieve a company report to obtain the filing history. 2. Identify the document of interest and note its `document_id`. 3. Use the **Company House Document** endpoint to download the document as a PDF. ## Processing Time The system begins generating reports as soon as the request endpoint is called. - Report generation normally completes within a few seconds. - During busy periods, processing can take longer. - The **Retrieve** endpoints can be used to check the status and retrieve the report once it is ready. - The service polls for up to 30 seconds. If the report is still not ready, a `202` status code is returned and you should continue polling. ## Sandbox Environment The sandbox environment uses deterministic test data and does not return live data. Use the sample company numbers, officer IDs, and document IDs below to receive predictable responses. ### Sandbox Companies | Company Name | Company Number | Status | Notes | |:-------------|:---------------|:-------|:------| | TEST COMPANY LTD | 12345678 | Active | Standard company with 2 officers | | SAMPLE HOLDINGS PLC | 87654321 | Active | PLC with multiple officers including corporate secretary | | DORMANT SERVICES LTD | 11223344 | Dormant | Dormant company | | DISSOLVED EXAMPLE LTD | 99887766 | Dissolved | Dissolved company with previous names | | SCOTTISH ENTERPRISE SC | SC654321 | Active | Scottish company | | DELAYED REPORT LTD | 55667788 | Active | Returns 202 on first poll (simulates async processing) | ### Sandbox Officers | Name | Officer ID | Type | DOB (Y-M) | Appointments | |:-----|:-----------|:-----|:----------|:-------------| | John David SMITH | ABC123DEF456 | Natural | 1975-06 | 3 | | Jane Elizabeth DOE | XYZ789GHI012 | Natural | 1980-03 | 1 | | Robert James JOHNSON | JKL345MNO678 | Natural | 1968-11 | 5 | | Christopher Mark TAYLOR | DEL789AYE012 | Natural | 1990-05 | 1 (delayed report) | | CORPORATE SECRETARIES LIMITED | VWX567YZA890 | Corporate | N/A | 25 | | David DISQUALIFIED | DIS123QUA456 | Natural (Disqualified) | 1970-01 | 0 | ### Sandbox Documents Document IDs in the sandbox must use the `sandbox-document-*` prefix format. Examples from company filing histories include: | Document ID | Description | |:------------|:------------| | sandbox-document-001 | TEST COMPANY LTD annual accounts | | sandbox-document-002 | TEST COMPANY LTD confirmation statement | | sandbox-document-003 | SAMPLE HOLDINGS PLC annual accounts | Any document ID starting with `sandbox-document-` will return a valid placeholder PDF. ## Billing > Note: Calls to the Company House Report and Officer Report endpoints outside of the sandbox environment will be billed. Refer to your commercial agreement or pricing documentation for details. ## API Endpoints More technical details on the API endpoints (including full request/response schemas, status codes, and error formats) are available in the [API Reference section](/docs/reference#uk-companies-house) of the documentation. ### Company House Search The Company House Search endpoint searches the UK Companies House register for companies matching the provided search term. The search is intelligent and will detect if the search term matches a company number format: - **Company number search**: If the search term matches the 8-character company number format, a direct lookup is performed. - **Name search**: Otherwise, a fuzzy name search is performed against registered company names. #### Example Request ```json { "company": "Test Company", "is_operational": true, "max_results": 50 } ``` #### Example Response ```json { "message": "Ok", "function": "company_house_search", "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95", "records": [ { "company_number": "12345678", "company_name": "TEST COMPANY LTD", "company_status": "active", "company_type": "ltd", "date_of_creation": "2020-01-15", "registered_office_address": { "address_line_1": "123 Test Street", "address_line_2": "Test District", "locality": "London", "postal_code": "EC1A 1BB", "country": "United Kingdom" } } ], "records_returned": 1, "total_records_available": 1 } ``` See the [Company House Search API documentation](/docs/reference/company_house_search) for detailed information on the request and response. ### Company House Officer Search The Company House Officer Search endpoint searches the UK Companies House register for officers matching the provided name. An optional `date_of_birth` parameter can be provided to narrow results. When supplied, only officers whose date of birth matches the given year and month are returned. The day component is accepted for convenience but is not used for matching, as Companies House only provides month and year of birth for most officers. #### Example Request ```json { "name": "John Smith", "date_of_birth": "1975-06-15", "max_results": 50 } ``` #### Example Response ```json { "message": "Ok", "function": "company_house_officer_search", "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95", "records": [ { "officer_id": "ABC123DEF456", "title": "John David SMITH", "date_of_birth": "1975-06", "address": { "address_line_1": "Test Street", "address_line_2": "Test District", "locality": "London", "postal_code": "EC1A 1BB", "country": "United Kingdom" }, "address_snippet": "123 Test Street, Test District, London, United Kingdom, EC1A 1BB", "appointment_count": 3, "description": "Total number of appointments 3 - Born June 1975" } ], "records_returned": 1, "more_results": false } ``` See the [Company House Officer Search API documentation](/docs/reference/company_house_officer_search) for detailed information on the request and response. ### Company House Report The Company House Report endpoint requests a comprehensive company report. The response confirms the job was queued and returns an `api_reference` for polling. > Note: Calls to this endpoint outside of the sandbox will be billed. #### Example Request ```json { "company_number": "12345678" } ``` #### Example Response ```json { "message": "Ok", "function": "company_house_report", "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95" } ``` The endpoint returns immediately with an `api_reference`, and the system begins generating the report in the background. See the [Company House Report API documentation](/docs/reference/company_house_report) for detailed information on the request and response. ### Retrieve Company House Report The Retrieve Company House Report endpoint retrieves the results of a company report request. The report contains the company's profile information (name, status, type, registered address, accounts, confirmation statement), an `officers` array with all current and former officers, a `filing_history` object containing the most recent filings (up to 200), and a `persons_with_significant_control` array. Each section is only included when the corresponding data exists at Companies House. Both JSON and PDF formats are available. To return a PDF, append `?pdf=true` to the URL. #### Example Request ``` GET /company_house_report/fe4291ca-d831-4760-96df-c9cb03b3cd95 ``` #### Example Response ```json { "message": "Ok", "function": "company_house_report_show", "api_reference": "7cbb094c-0f27-42f4-9f36-9cf0b2f6d5ff", "report": { "company_name": "TEST COMPANY LTD", "company_number": "12345678", "company_status": "active", "type": "ltd", "jurisdiction": "england-wales", "date_of_creation": "2020-01-15", "can_file": true, "report_date": "2026-02-03T10:00:00Z", "registered_office_address": { "address_line_1": "123 Test Street", "address_line_2": "Test District", "locality": "London", "postal_code": "EC1A 1BB", "country": "United Kingdom" }, "accounts": { "overdue": false, "next_due": "2026-10-15", "last_accounts": { "type": "full", "made_up_to": "2025-01-15" }, "accounting_reference_date": { "day": "15", "month": "01" } }, "confirmation_statement": { "overdue": false, "next_due": "2026-07-15", "last_made_up_to": "2025-06-15" }, "sic_codes": [ { "code": "62020", "description": "Information technology consultancy activities" } ], "officers": [ { "name": "SMITH, John David", "officer_id": "ABC123DEF456", "officer_role": "director", "appointed_on": "2020-01-15", "date_of_birth": "1975-06", "nationality": "British", "country_of_residence": "England", "address": { "premises": "123", "address_line_1": "Test Street", "locality": "London", "postal_code": "EC1A 1BB", "country": "United Kingdom" } }, { "name": "DOE, Jane Elizabeth", "officer_id": "XYZ789GHI012", "officer_role": "secretary", "appointed_on": "2020-01-15", "date_of_birth": "1980-03", "nationality": "British", "country_of_residence": "England", "address": { "premises": "456", "address_line_1": "Sample Road", "locality": "London", "postal_code": "EC1A 2CC", "country": "United Kingdom" } } ], "filing_history": { "total_files": 5, "returned_files": 5, "files": [ { "date": "2025-10-01", "type": "AA", "pages": 15, "category": "accounts", "description": "accounts-with-accounts-type-full", "document_id": "sandbox-document-001", "transaction_id": "SANDBOX00001" } ] }, "persons_with_significant_control": [ { "name": "Mr John David Smith", "kind": "individual-person-with-significant-control", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "notified_on": "2020-01-15", "country_of_residence": "England", "nationality": "British" } ] } } ``` #### Waiting for the report to be ready When the report is not yet complete, the endpoint may wait for up to 30 seconds. If the report is still not ready, the endpoint will return a `202` status code: ```json { "message": "Extract is still being processed. Please try again later." } ``` You can then repeat the request with the same `api_reference` until the report is returned. See the [Retrieve Company House Report API documentation](/docs/reference/company_house_report_show) for detailed information. ### Company House Officer Report The Company House Officer Report endpoint requests a comprehensive officer report. The response confirms the job was queued and returns an `api_reference` for polling. > Note: Calls to this endpoint outside of the sandbox will be billed. #### Example Request ```json { "officer_id": "ABC123DEF456", "disqualified": false, "type": "natural" } ``` #### Example Response ```json { "message": "Ok", "function": "company_house_officer_report", "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95" } ``` See the [Company House Officer Report API documentation](/docs/reference/company_house_officer_report) for detailed information. ### Retrieve Company House Officer Report The Retrieve Company House Officer Report endpoint retrieves the results of an officer report request. The report contains the officer's personal details and an `items` array listing every appointment (role) they hold or have held across different companies. Each item includes the company details (`appointed_to`), the role (`officer_role`), appointment date, and correspondence address. Active appointments have no `resigned_on` field; former appointments include `resigned_on`. For disqualified officers (requested with `disqualified=true`), the report includes a `disqualifications` array instead of appointment items. Both JSON and PDF formats are available. To return a PDF, append `?pdf=true` to the URL. #### Example Request ``` GET /company_house_officer_report/fe4291ca-d831-4760-96df-c9cb03b3cd95 ``` #### Example Response ```json { "message": "Ok", "function": "company_house_officer_show", "api_reference": "7cbb094c-0f27-42f4-9f36-9cf0b2f6d5ff", "report": { "officer_id": "XYZ789GHI012", "name": "Jane Elizabeth DOE", "date_of_birth": "1980-03", "etag": "sandbox-etag-002", "kind": "personal-appointment", "type": "natural", "is_corporate_officer": false, "disqualified": false, "report_date": "2026-02-03T10:00:00Z", "total_results": 1, "items_per_page": 50, "start_index": 0, "items": [ { "name": "Jane Elizabeth DOE", "officer_role": "secretary", "appointed_on": "2020-01-15", "appointed_to": { "company_name": "TEST COMPANY LTD", "company_number": "12345678", "company_status": "active" }, "address": { "premises": "456", "address_line_1": "Sample Road", "locality": "London", "country": "United Kingdom", "postal_code": "EC1A 2CC" }, "nationality": "British", "name_elements": { "title": "Ms", "forename": "Jane", "other_forenames": "Elizabeth", "surname": "DOE" }, "country_of_residence": "England", "links": { "company": "/company/12345678" }, "is_pre_1992_appointment": false } ] } } ``` #### Waiting for the report to be ready When the report is not yet complete, the endpoint may wait for up to 30 seconds. If the report is still not ready, the endpoint will return a `202` status code: ```json { "message": "Extract is still being processed. Please try again later." } ``` You can then repeat the request with the same `api_reference` until the report is returned. See the [Retrieve Company House Officer Report API documentation](/docs/reference/company_house_officer_report_show) for detailed information. ### Company House Document The Company House Document endpoint retrieves a filed document from Companies House. Documents are returned as PDF files. #### Example Request ``` GET /company_house_document/sandbox-document-001 ``` This returns the document as a PDF file in the response body. > **Sandbox Note:** Document IDs must use the `sandbox-document-*` prefix in the sandbox environment. Valid sandbox document IDs can be found in the `filing_history` section of company reports (e.g., `sandbox-document-001`, `sandbox-document-002`). #### Error Responses If the document is not available in PDF format, a `415 Unsupported Media Type` error is returned: ```json { "message": "Document media type is not supported" } ``` See the [Company House Document API documentation](/docs/reference/company_house_document) for detailed information.