Retrieve Company House Report

GET /api/v2/company_house_report/{api_reference} operationId: company_house_report_show

Live: https://gdapi.globaldata.net.au/api/v2/company_house_report/{api_reference} · Sandbox: 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.

Path parameters

Field Description

Field	Description
`api_reference`required	string (uuid) The API reference (UUID) returned when the report was queued via `POST /company_house_report`. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95`

api_referencerequired

string (uuid)

The API reference (UUID) returned when the report was queued via POST /company_house_report.

Example: fe4291ca-d831-4760-96df-c9cb03b3cd95

Query parameters

Field Description

Field	Description
`pdf`	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`

pdf

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`.

application/json application/pdf

Field	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.

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).

application/json

Field Description

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

message

string

Status message indicating the report is not ready yet.

Example: 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.

application/json

Field Description

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

message

string

Error message describing that the record could not be located.

Example: Not Found.

Standard error responses: 400 401 402 403 429 5XX See common error responses

Previous Company House Report Next Company House Officer Search

Response

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

{
    "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"
            }
        ]
    }
}

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

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

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

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

{
    "message": "Not Found."
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}

Retrieve Company House Report

Response Behaviour

Sandbox Usage

Path parameters

Query parameters

Responses

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

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

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

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

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