# Retrieve Company House Officer Report

`GET /company_house_officer_report/{api_reference}`

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

## 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_officer_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_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` |

**Sample 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
            }
        ]
    }
}
```

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