Retrieve Company House Officer Report

GET /api/v2/company_house_officer_report/{api_reference} operationId: company_house_officer_report_show

Live: https://gdapi.globaldata.net.au/api/v2/company_house_officer_report/{api_reference} · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/company_house_officer_report/{api_reference}

Polls the status of a UK Companies House officer report that was previously queued via POST /company_house_officer_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 Environment

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

Name	Officer ID	Type	Notes
John David SMITH	ABC123DEF456	Natural	Director with 3 appointments
Jane Elizabeth DOE	XYZ789GHI012	Natural	Secretary with 1 appointment
Robert James JOHNSON	JKL345MNO678	Natural	Director with 5 appointments
Christopher Mark TAYLOR	DEL789AYE012	Natural	Returns 202 on first poll
CORPORATE SECRETARIES LIMITED	VWX567YZA890	Corporate	Corporate secretary
David DISQUALIFIED	DIS123QUA456	Natural	Disqualified director (use `disqualified=true`)

Note: The officer DEL789AYE012 (Christopher Mark TAYLOR) 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_officer_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_officer_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_officer_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 officer report payload sourced from the Companies House `GET /officers/{officer_id}/appointments` endpoint. For non-disqualified officers the top-level object is an `appointmentList` containing the officer's personal details and an `items` array of every appointment (role) they hold or have held across different companies. Disqualified officer reports include a `disqualifications` array instead.
`report.officer_id`	string The unique officer identifier within Companies House. Example: `XYZ789GHI012`
`report.name`	string The full name of the officer as registered with Companies House. Example: `Jane Elizabeth DOE`
`report.date_of_birth`	string The officer's date of birth truncated to year and month (`YYYY-MM`). Omitted when Companies House does not provide it. Example: `1980-03`
`report.etag`	string The ETag of the upstream Companies House resource. Example: `sandbox-etag-002`
`report.kind`	string The kind of record. Possible values include: `personal-appointment` - standard officer appointments `personal-disqualification` - disqualified officer record Example: `personal-appointment`
`report.type`	string The type of officer. Possible values: `natural` - a human individual `corporate` - a corporate body acting as an officer Enum: `natural`, `corporate` Example: `natural`
`report.is_corporate_officer`	boolean Indicates whether the officer is a corporate body rather than a natural person. Example: `false`
`report.disqualified`	boolean Indicates whether the report was requested with the `disqualified` flag. When `true`, the `disqualifications` array is populated instead of `items`. Example: `false`
`report.report_date`	string (date-time) ISO 8601 UTC timestamp indicating when the report was generated. Example: `2026-02-07T23:48:28Z`
`report.total_results`	integer The total number of appointments (or disqualifications) held by this officer. Example: `1`
`report.items_per_page`	integer The pagination page size used when collecting data from Companies House. Example: `50`
`report.start_index`	integer The starting index of the items (always `0` in the report as all pages are collected). Example: `0`
`report.items`	array of objects Array of the officer's appointments across companies. Each entry represents a single role (e.g. director, secretary) at a specific company. Active appointments have no `resigned_on` field; former appointments include `resigned_on`.
`report.items[].name`	string The officer's name as recorded for this appointment. Example: `Jane Elizabeth DOE`
`report.items[].officer_role`	string The role held at the company. Common values include `director`, `secretary`, `corporate-secretary`, `corporate-director`, `llp-member`, `llp-designated-member`, `managing-officer`, among others. Example: `secretary`
`report.items[].appointed_on`	string (date) The date the officer was appointed to this role. Example: `2020-01-15`
`report.items[].resigned_on`	string (date) The date the officer resigned from this role. Absent for active appointments. Example: `2019-12-31`
`report.items[].appointed_to`	object The company this appointment relates to.
`report.items[].appointed_to.company_name`	string The registered name of the company. Example: `TEST COMPANY LTD`
`report.items[].appointed_to.company_number`	string The Companies House company number. Example: `12345678`
`report.items[].appointed_to.company_status`	string The current status of the company (e.g. `active`, `dissolved`). Example: `active`
`report.items[].address`	object The correspondence address recorded for this appointment.
`report.items[].address.premises`	string Example: `456`
`report.items[].address.address_line_1`	string Example: `Sample Road`
`report.items[].address.address_line_2`	string
`report.items[].address.care_of`	string
`report.items[].address.locality`	string Example: `London`
`report.items[].address.region`	string
`report.items[].address.country`	string Example: `United Kingdom`
`report.items[].address.postal_code`	string Example: `EC1A 2CC`
`report.items[].address.po_box`	string
`report.items[].name_elements`	object Broken-down components of the officer's name.
`report.items[].name_elements.title`	string Example: `Ms`
`report.items[].name_elements.forename`	string Example: `Jane`
`report.items[].name_elements.other_forenames`	string Example: `Elizabeth`
`report.items[].name_elements.surname`	string Example: `DOE`
`report.items[].name_elements.honours`	string
`report.items[].former_names`	array of objects Previous names for the officer, if any.
`report.items[].former_names[].forenames`	string
`report.items[].former_names[].surname`	string
`report.items[].nationality`	string The officer's nationality. May be absent for some appointments. Example: `British`
`report.items[].country_of_residence`	string The officer's country of residence. May be absent. Example: `England`
`report.items[].occupation`	string The officer's stated occupation. May be absent.
`report.items[].links`	object Links to related Companies House resources.
`report.items[].links.company`	string Relative link to the company profile. Example: `/company/12345678`
`report.items[].identification`	object Identification details for corporate officers. Absent for natural persons.
`report.items[].identification.identification_type`	string Example: `uk-limited-company`
`report.items[].identification.legal_authority`	string
`report.items[].identification.legal_form`	string
`report.items[].identification.place_registered`	string
`report.items[].identification.registration_number`	string
`report.items[].is_pre_1992_appointment`	boolean Whether the officer was appointed before 1992. Example: `false`
`report.items[].appointed_before`	string (date) Present only when `is_pre_1992_appointment` is `true`.
`report.items[].contact_details`	object Contact details for corporate managing officers.
`report.items[].contact_details.contact_name`	string
`report.items[].responsibilities`	string Responsibilities of a managing officer.
`report.disqualifications`	array of objects Array of disqualification records. Only present when the report was requested with `disqualified=true`. When present, the `items` array will typically be empty.
`report.disqualifications[].case_identifier`	string Example: `DIS/2020/001`
`report.disqualifications[].disqualification_type`	string Example: `court-order`
`report.disqualifications[].disqualified_from`	string (date) Example: `2020-06-01`
`report.disqualifications[].disqualified_until`	string (date) Example: `2030-05-31`
`report.disqualifications[].reason`	object
`report.disqualifications[].reason.section`	string Example: `6`
`report.disqualifications[].reason.act`	string Example: `Company Directors Disqualification Act 1986`
`report.disqualifications[].reason.description_identifier`	string Example: `conviction-of-indictable-offence`
`report.disqualifications[].company_names`	array of strings
`report.disqualifications[].heard_on`	string (date) Example: `2020-05-15`
`report.disqualifications[].court_name`	string Example: `High Court of Justice`

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 Officer Report Next Company House Document

Response

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

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

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 Officer Report

Response Behaviour

Sandbox Environment

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.