# Retrieve Company House Report

`GET /company_house_report/{api_reference}`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/company_house_report/{api_reference}`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/company_house_report/{api_reference}`

Polls the status of a UK Companies House report that was previously queued via `POST /company_house_report`. Provide the `api_reference` returned from the original request to determine whether the report is ready, download the JSON payload, or stream a PDF copy. This retrieval call is not billable and can be repeated until the report is ready.

## Response Behaviour

- While the report is still compiling, the API responds with HTTP `202`. Keep polling with an exponential backoff.
- Once ready, the endpoint returns HTTP `200` with the full JSON report.
- Append `?pdf=true` to stream a formatted PDF copy of the same report. When `pdf=true`, the response body is a PDF (`application/pdf`) instead of JSON.
- The service polls upstream data for up to 30 seconds; if no report is available at that point you will receive a `202` response. Continue polling with the same `api_reference`.

## Sandbox Usage

The sandbox dataset is deterministic and does not use live data. First request a report for one of the sandbox company numbers via `POST /company_house_report`, then poll this endpoint with the returned `api_reference`.

**Note:** The company `55667788` (DELAYED REPORT LTD) will return HTTP `202` on the first poll to simulate asynchronous processing. Subsequent polls will return the report.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `api_reference` | path | string (uuid) | **Required.** The API reference (UUID) returned when the report was queued via `POST /company_house_report`. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `pdf` | query | boolean | When set to `true`, returns the report as a PDF document instead of JSON. Omit (or send `false`) to receive the JSON payload. Default: `false` |

## Responses

### 200 Report is ready. Returns JSON by default or a PDF when `pdf=true`.

Content type: `application/json`, `application/pdf`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` when the report payload is returned. Example: `Ok` |
| `function` | string | Name of the API function that handled the request. Example: `company_house_report_show` |
| `api_reference` | string (uuid) | Audit reference for **this** retrieval call (not the original queue reference). Example: `7cbb094c-0f27-42f4-9f36-9cf0b2f6d5ff` |
| `report` | object | Full UK Companies House company report. The top-level fields come from the Companies House company profile endpoint. Additional sections (`officers`, `filing_history`, `persons_with_significant_control`) are fetched from their respective Companies House endpoints and included when available. |
| `report.company_name` | string | The registered name of the company. Example: `TEST COMPANY LTD` |
| `report.company_number` | string | The Companies House company number. Example: `12345678` |
| `report.company_status` | string | The current status of the company (e.g. `active`, `dissolved`, `liquidation`, `receivership`, `administration`, `converted-closed`). Example: `active` |
| `report.company_status_detail` | string | Additional detail about the company status, if any. |
| `report.type` | string | The type of company (e.g. `ltd`, `plc`, `llp`, `private-unlimited`, etc.). Example: `ltd` |
| `report.subtype` | string | The company subtype, if applicable. |
| `report.date_of_creation` | string (date) | The date the company was created/incorporated. Example: `2020-01-15` |
| `report.date_of_cessation` | string (date) | The date the company was dissolved or ceased. Present only for dissolved/ceased companies. |
| `report.jurisdiction` | string | The jurisdiction the company is registered in (e.g. `england-wales`, `scotland`, `northern-ireland`). Example: `england-wales` |
| `report.registered_office_address` | object | The company's registered office address. |
| `report.registered_office_address.premises` | string |  |
| `report.registered_office_address.address_line_1` | string | Example: `123 Test Street` |
| `report.registered_office_address.address_line_2` | string | Example: `Test District` |
| `report.registered_office_address.care_of` | string |  |
| `report.registered_office_address.locality` | string | Example: `London` |
| `report.registered_office_address.region` | string |  |
| `report.registered_office_address.country` | string | Example: `United Kingdom` |
| `report.registered_office_address.po_box` | string |  |
| `report.registered_office_address.postal_code` | string | Example: `EC1A 1BB` |
| `report.registered_office_is_in_dispute` | boolean | Whether the registered office address is in dispute. |
| `report.accounts` | object (dynamic) | Accounting information including reference dates and the last/next filing periods. |
| `report.annual_return` | object (dynamic) | Annual return information (pre-2016 companies). |
| `report.can_file` | boolean | Whether the company can currently file with Companies House. Example: `true` |
| `report.confirmation_statement` | object (dynamic) | Confirmation statement due dates and status. |
| `report.corporate_annotation` | string | Corporate annotation text, if any. |
| `report.external_registration_number` | string | The registration number of an external company. |
| `report.foreign_company_details` | object (dynamic) | Details of a foreign company, if applicable. |
| `report.branch_company_details` | object (dynamic) | Details of a branch company, if applicable. |
| `report.partial_data_available` | boolean | Indicates partial data availability. |
| `report.previous_company_names` | array of objects | List of previous names the company has used. |
| `report.previous_company_names[].name` | string |  |
| `report.previous_company_names[].ceased_on` | string (date) |  |
| `report.previous_company_names[].effective_from` | string (date) |  |
| `report.service_address` | object (dynamic) | The service address, if different from the registered office. |
| `report.sic_codes` | array of objects | Standard Industrial Classification codes expanded with descriptions. |
| `report.sic_codes[].code` | string | The SIC code. Example: `62020` |
| `report.sic_codes[].description` | string | Human-readable description of the SIC code. Example: `Information technology consultancy activities` |
| `report.super_secure_managing_officer_count` | integer | Count of super-secure managing officers, if any. |
| `report.undeliverable_registered_office_address` | boolean | Whether the registered office address has been flagged as undeliverable. |
| `report.report_date` | string (date-time) | ISO 8601 UTC timestamp indicating when the report was generated. Example: `2026-02-03T10:00:00Z` |
| `report.officers` | array of objects | Array of officers (directors, secretaries, etc.) associated with the company. Active officers (no `resigned_on`) are listed first, sorted by appointment date descending. Resigned officers follow, sorted by resignation date ascending. Only present when the company has an officers record at Companies House. |
| `report.officers[].officer_id` | string | The unique officer identifier within Companies House. Example: `ABC123DEF456` |
| `report.officers[].name` | string | The officer's name in `SURNAME, Forenames` format. Example: `SMITH, John David` |
| `report.officers[].officer_role` | string | The role held (e.g. `director`, `secretary`, `corporate-director`, `corporate-secretary`, `llp-member`, `llp-designated-member`). Example: `director` |
| `report.officers[].appointed_on` | string (date) | The date the officer was appointed. Example: `2020-01-15` |
| `report.officers[].resigned_on` | string (date) | The date the officer resigned. Absent for active officers. |
| `report.officers[].appointed_before` | string (date) | Present when `is_pre_1992_appointment` is `true`. |
| `report.officers[].is_pre_1992_appointment` | boolean | Whether the appointment pre-dates 1992 records. |
| `report.officers[].date_of_birth` | string | Date of birth truncated to year and month (`YYYY-MM`). Example: `1975-06` |
| `report.officers[].nationality` | string | The officer's nationality. Example: `British` |
| `report.officers[].country_of_residence` | string | The officer's country of residence. Example: `England` |
| `report.officers[].occupation` | string | The officer's occupation. |
| `report.officers[].person_number` | string | Internal Companies House person number. |
| `report.officers[].address` | object (dynamic) | The correspondence address of the officer. |
| `report.officers[].former_names` | array of objects | Previous names for the officer. |
| `report.officers[].former_names[].forenames` | string |  |
| `report.officers[].former_names[].surname` | string |  |
| `report.officers[].identification` | object | Identification details for corporate officers. |
| `report.officers[].identification.identification_type` | string | Example: `uk-limited-company` |
| `report.officers[].identification.legal_authority` | string |  |
| `report.officers[].identification.legal_form` | string |  |
| `report.officers[].identification.place_registered` | string |  |
| `report.officers[].identification.registration_number` | string | Example: `12345678` |
| `report.officers[].identity_verification_details` | object (dynamic) | Identity verification information, if available. |
| `report.officers[].contact_details` | object (dynamic) | Contact details for corporate managing officers. |
| `report.officers[].principal_office_address` | object (dynamic) | Principal office address for corporate managing officers. |
| `report.officers[].responsibilities` | string | Responsibilities of a managing officer. |
| `report.filing_history` | object | The company's filing history. Only present when the company has filings at Companies House. Up to 200 most recent filings are returned. |
| `report.filing_history.total_files` | integer | The total number of filings for this company. Example: `25` |
| `report.filing_history.returned_files` | integer | The number of filings included in this response (capped at 200). Example: `25` |
| `report.filing_history.files` | array of objects | Array of individual filing records. |
| `report.filing_history.files[].transaction_id` | string | Unique transaction identifier for this filing. |
| `report.filing_history.files[].document_id` | string | Document identifier that can be used with the Company House Document endpoint to download the filing as a PDF. |
| `report.filing_history.files[].date` | string (date) | The date of the filing. |
| `report.filing_history.files[].type` | string | The type code of the filing (e.g. `AA`, `CS01`, `AP01`, `TM01`). |
| `report.filing_history.files[].category` | string | The category of filing (e.g. `accounts`, `confirmation-statement`, `officers`, `capital`, `mortgage`, `address`, `resolution`). |
| `report.filing_history.files[].subcategory` | string | Sub-category of the filing (e.g. `appointments`, `termination`, `change`, `create`, `satisfy`). |
| `report.filing_history.files[].description` | string | Human-readable description of the filing. |
| `report.filing_history.files[].pages` | integer | Number of pages in the document. |
| `report.filing_history.files[].barcode` | string | Barcode identifier for the filing. |
| `report.filing_history.files[].paper_filed` | boolean | Whether the filing was submitted on paper. |
| `report.filing_history.files[].annotations` | array of objects | Annotations associated with the filing. |
| `report.filing_history.files[].associated_filings` | array of objects | Related filings associated with this filing. |
| `report.filing_history.files[].resolutions` | array of objects | Resolution details, if applicable. |
| `report.persons_with_significant_control` | array of objects | Array of persons with significant control (PSCs) over the company. Only present when the company has PSC records at Companies House. |
| `report.persons_with_significant_control[].kind` | string | The type of PSC (e.g. `individual-person-with-significant-control`, `corporate-entity-person-with-significant-control`, `legal-person-person-with-significant-control`). Example: `individual-person-with-significant-control` |
| `report.persons_with_significant_control[].name` | string | The name of the individual or entity. Example: `Mr John David Smith` |
| `report.persons_with_significant_control[].address` | object (dynamic) | The correspondence address of the PSC. |
| `report.persons_with_significant_control[].date_of_birth` | string | Date of birth truncated to year and month (`YYYY-MM`). Only for individuals. |
| `report.persons_with_significant_control[].country_of_residence` | string | Country of residence. Only for individuals. |
| `report.persons_with_significant_control[].nationality` | string | Nationality of the PSC. |
| `report.persons_with_significant_control[].natures_of_control` | array of strings | List of natures of control held (e.g. `ownership-of-shares-75-to-100-percent`, `voting-rights-75-to-100-percent`, `right-to-appoint-and-remove-directors`). |
| `report.persons_with_significant_control[].identification` | object (dynamic) | Identification details for corporate entity PSCs. |
| `report.persons_with_significant_control[].name_elements` | object (dynamic) | Broken-down name components for individual PSCs. |
| `report.persons_with_significant_control[].notified_on` | string (date) | The date the PSC was notified. |
| `report.persons_with_significant_control[].ceased` | boolean | Whether the PSC has ceased. |
| `report.persons_with_significant_control[].ceased_on` | string (date) | The date the PSC ceased, if applicable. |
| `report.persons_with_significant_control[].is_sanctioned` | boolean | Whether the PSC is sanctioned. |
| `report.persons_with_significant_control[].description` | string | Description of the PSC entry. |
| `report.persons_with_significant_control[].principal_office_address` | object (dynamic) | Principal office address for legal person/corporate entity PSCs. |

**Sample 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",
        "date_of_creation": "2020-01-15",
        "jurisdiction": "england-wales",
        "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"
            },
            "next_accounts": {
                "due_on": "2026-10-15",
                "overdue": false
            },
            "accounting_reference_date": {
                "day": "15",
                "month": "01"
            }
        },
        "confirmation_statement": {
            "overdue": false,
            "next_due": "2026-07-15",
            "last_made_up_to": "2025-06-15",
            "next_made_up_to": "2026-06-15"
        },
        "sic_codes": [
            {
                "code": "62020",
                "description": "Information technology consultancy activities"
            },
            {
                "code": "62090",
                "description": "Other information technology and computer service 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",
                    "address_line_2": "Test District",
                    "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,
                    "barcode": "SANDBOX001",
                    "category": "accounts",
                    "description": "accounts-with-accounts-type-full",
                    "document_id": "sandbox-document-001",
                    "transaction_id": "SANDBOX00001"
                },
                {
                    "date": "2025-06-15",
                    "type": "CS01",
                    "pages": 3,
                    "barcode": "SANDBOX002",
                    "category": "confirmation-statement",
                    "description": "confirmation-statement-with-updates",
                    "document_id": "sandbox-document-002",
                    "transaction_id": "SANDBOX00002"
                }
            ]
        },
        "persons_with_significant_control": [
            {
                "kind": "individual-person-with-significant-control",
                "name": "Mr John David Smith",
                "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",
                "date_of_birth": "1975-06",
                "nationality": "British"
            }
        ]
    }
}
```

Also available as a PDF (application/pdf)

### 202 Report is still being prepared (returned when no data is available after the 30-second polling window).

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Status message indicating the report is not ready yet. Example: `Extract is still being processed. Please try again later.` |

**Sample response**

```json
{
    "message": "Extract is still being processed. Please try again later."
}
```

### 404 No report was found for the provided `api_reference`, or it belongs to another account/environment.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Error message describing that the record could not be located. Example: `Not Found.` |

**Sample response**

```json
{
    "message": "Not Found."
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))