# Company House Search

`POST /company_house_search`

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

Searches the UK Companies House register for companies matching the provided search term and returns a list of results.

## Search Behaviour

The search is intelligent and will detect if the search term matches a company number format:

- **Company number search**: If the search term matches the 8-character company number format (e.g., `12345678` or `SC123456`), a direct lookup is performed.
- **Name search**: Otherwise, a fuzzy name search is performed against registered company names.

## Company Number Formats

| Prefix | Jurisdiction | Example |
|--------|--------------|---------|
| (none) | England & Wales | 12345678 |
| SC | Scotland | SC123456 |
| NI | Northern Ireland | NI012345 |
| FC | Foreign Company | FC012345 |
| OC | LLP (England & Wales) | OC123456 |

## Sandbox Environment

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

| Company Name | Company Number | Status | Type |
|:-------------|:---------------|:-------|:-----|
| TEST COMPANY LTD | 12345678 | Active | ltd |
| SAMPLE HOLDINGS PLC | 87654321 | Active | plc |
| DORMANT SERVICES LTD | 11223344 | Dormant | ltd |
| DISSOLVED EXAMPLE LTD | 99887766 | Dissolved | ltd |
| SCOTTISH ENTERPRISE SC | SC654321 | Active | ltd |
| DELAYED REPORT LTD | 55667788 | Active | ltd |

You can search by company name (e.g., `TEST COMPANY`) or by company number (e.g., `12345678`).

## Request body

The search criteria for finding companies.

| Field | Type | Description |
|-------|------|-------------|
| `company` | string [max 255 characters] | **Required.** The company name or company number to search for. Maximum 255 characters. Example: `Test Company` |
| `is_operational` | boolean | When `true`, filters results to only include companies with an active/operational status. Default: `false` Example: `false` |
| `max_results` | integer [1..200] | Maximum number of results to return. Value must be between 1 and 200. Default: `200` Example: `50` |

**Sample request**

```json
{
    "company": "Test Company",
    "is_operational": false,
    "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_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 company records. |
| `records[].company_number` | string | The unique 8-character company number. Example: `12345678` |
| `records[].company_name` | string | The registered name of the company. Example: `TEST COMPANY LTD` |
| `records[].company_status` | string | The current status of the company (e.g., active, dissolved, liquidation). Example: `active` |
| `records[].company_type` | string | The type of company (e.g., ltd, plc, llp). Example: `ltd` |
| `records[].date_of_creation` | string (date) | The date the company was incorporated. Example: `2020-01-15` |
| `records[].registered_office_address` | object | The registered office address of the company. |
| `records[].registered_office_address.address_line_1` | string | Example: `123 High Street` |
| `records[].registered_office_address.address_line_2` | string | Example: `Floor 2` |
| `records[].registered_office_address.locality` | string | Example: `London` |
| `records[].registered_office_address.region` | string | Example: `Greater London` |
| `records[].registered_office_address.postal_code` | string | Example: `SW1A 1AA` |
| `records[].registered_office_address.country` | string | Example: `United Kingdom` |
| `records_returned` | integer | The number of records returned in this response. Example: `5` |
| `total_records_available` | integer | The total number of matching records available. Example: `150` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "company_house_search",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "records": [
        {
            "company_number": "12345678",
            "company_name": "TEST COMPANY LTD",
            "company_status": "active",
            "company_type": "ltd",
            "date_of_creation": "2020-01-15",
            "registered_office_address": {
                "address_line_1": "123 High Street",
                "address_line_2": "Floor 2",
                "locality": "London",
                "region": "Greater London",
                "postal_code": "SW1A 1AA",
                "country": "United Kingdom"
            }
        }
    ],
    "records_returned": 5,
    "total_records_available": 150
}
```

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