# Company House Officer Search

`POST /company_house_officer_search`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/company_house_officer_search`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/company_house_officer_search`

Searches the UK Companies House register for officers (directors, secretaries, and other officials) matching the provided name and returns a list of results.

## Search Behaviour

The search performs a fuzzy match against officer names registered with Companies House. Results include current and former officers across all registered companies.

An optional `date_of_birth` filter 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.

## Sandbox Environment

The sandbox dataset is deterministic and does not use live data. Use one of the following sample officer names to receive predictable matches:

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

Search using names like `John Smith`, `JOHNSON`, or `CORPORATE SECRETARIES`.

## Request body

The search criteria for finding officers.

| Field | Type | Description |
|-------|------|-------------|
| `name` | string [max 255 characters] | **Required.** The name of the officer to search for. Maximum 255 characters. Example: `John Smith` |
| `date_of_birth` | string (date) or null | Optional date of birth filter in YYYY-MM-DD format. When provided, only officers whose date of birth matches the year and month will be 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: `1975-06-15` |
| `max_results` | integer [1..100] | Maximum number of results to return. Value must be between 1 and 100. Default: `50` Example: `50` |

**Sample request**

```json
{
    "name": "John Smith",
    "date_of_birth": "1975-06-15",
    "max_results": 50
}
```

## Responses

### 200 Successful response with search results.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `function` | string | The API function that handled the request. Example: `company_house_officer_search` |
| `api_reference` | string (uuid) | A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `records` | array of objects | Array of matching officer records. |
| `records[].officer_id` | string | The unique identifier for the officer. Use this ID when requesting an officer report. Example: `ABC123DEF456` |
| `records[].title` | string | The full name of the officer as it appears in the register. Example: `JOHN SMITH` |
| `records[].date_of_birth` | string | The officer's date of birth (month and year only for privacy), formatted as YYYY-MM. Example: `1975-06` |
| `records[].address` | object | The correspondence address of the officer. |
| `records[].address.address_line_1` | string | Example: `456 Oak Avenue` |
| `records[].address.locality` | string | Example: `Manchester` |
| `records[].address.postal_code` | string | Example: `M1 1AA` |
| `records[].address.country` | string | Example: `United Kingdom` |
| `records[].address_snippet` | string | A single-line summary of the officer's address. Example: `456 Oak Avenue, Manchester, M1 1AA` |
| `records[].appointment_count` | integer | Number of current company appointments. Example: `3` |
| `records[].description` | string | A description of the officer's roles. Example: `Total number of appointments 3` |
| `records_returned` | integer | The number of records returned in this response. Example: `5` |
| `more_results` | boolean | Indicates whether more results are available beyond the current page. Example: `true` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "company_house_officer_search",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "records": [
        {
            "officer_id": "ABC123DEF456",
            "title": "JOHN SMITH",
            "date_of_birth": "1975-06",
            "address": {
                "address_line_1": "456 Oak Avenue",
                "locality": "Manchester",
                "postal_code": "M1 1AA",
                "country": "United Kingdom"
            },
            "address_snippet": "456 Oak Avenue, Manchester, M1 1AA",
            "appointment_count": 3,
            "description": "Total number of appointments 3"
        }
    ],
    "records_returned": 5,
    "more_results": true
}
```

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