# UK Business Check

`POST /uk_business_check`

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

Performs a synchronous check of a single UK company by its Companies House company number. This is the UK equivalent of the Australian `/business_check` endpoint: one request, one JSON reply, no polling.

The response combines the Companies House company profile, officers and filing history into a single flat `match` object.

## 12 month window

Officers and filings are limited to the last 12 months so the response reflects recent activity rather than the full company record:

- `officers` contains officers who were **appointed or resigned** within the last 12 months. Long-standing officers with no change in that period are omitted, so this is a list of officer changes, not the current board. Use `/company_house_report` for the full officer list.
- `filing_history` contains filings dated within the last 12 months, newest first.

Note that the sandbox fixture companies carry fixed appointment and filing dates, so their `officers` and `filing_history` may be empty once those dates fall outside the window.

## Company numbers

UK company numbers are always 8 characters. Most are numeric with leading zeros (e.g. `01234567`); Scottish, Northern Irish, LLP and other registrations use a two letter prefix (e.g. `SC123456`, `NI012345`, `OC301234`). The number is case-insensitive; it is uppercased before lookup.

## Not found

If the company number is well-formed but Companies House has no record of it, the call succeeds with `"match": []`. This is still a billable attempt.

## Sandbox Environment

The sandbox dataset is deterministic and does not use live data. Any other company number returns an empty `match`.

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

## Request body

The company number to check.

| Field | Type | Description |
|-------|------|-------------|
| `number` | string | **Required.** The 8-character UK Companies House company number. Pattern: `^[A-Za-z0-9]{8}$` Example: `01234567` |

**Sample request**

```json
{
    "number": "01234567"
}
```

## Responses

### 200 Check complete.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` on success. Example: `Ok` |
| `api_reference` | string (uuid) | Audit reference for this call. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `match` | one of 2 shapes | One of: UK Business Check match; Empty array. The matched company. An empty array `[]` when the company number is not known to Companies House. Empty array: Returned in place of an empty object for backward compatibility. When the associated object has no data, the API returns an empty array `[]` instead of an empty object `{}`. Clients should treat `[]` as equivalent to `{}` for these fields. This shape exists for backward compatibility and will not be removed. (array [max 0 items]) |
| `match (UK Business Check match).company_number` | string | Example: `01234567` |
| `match (UK Business Check match).company_name` | string | Example: `ACME TRADING LIMITED` |
| `match (UK Business Check match).company_status` | string | Companies House status, e.g. `active`, `dissolved`, `liquidation`, `dormant`. Example: `active` |
| `match (UK Business Check match).company_status_detail` | string or null |  |
| `match (UK Business Check match).type` | string | Companies House company type, e.g. `ltd`, `plc`, `llp`. Example: `ltd` |
| `match (UK Business Check match).jurisdiction` | string or null | Example: `england-wales` |
| `match (UK Business Check match).date_of_creation` | string (date) or null | Example: `2001-03-14` |
| `match (UK Business Check match).date_of_cessation` | string (date) or null |  |
| `match (UK Business Check match).registered_office_address` | object |  |
| `match (UK Business Check match).registered_office_address.address_line_1` | string or null | Example: `1 High St` |
| `match (UK Business Check match).registered_office_address.address_line_2` | string or null |  |
| `match (UK Business Check match).registered_office_address.locality` | string or null | Example: `London` |
| `match (UK Business Check match).registered_office_address.region` | string or null |  |
| `match (UK Business Check match).registered_office_address.postal_code` | string or null | Example: `SW1A 1AA` |
| `match (UK Business Check match).registered_office_address.country` | string or null | Example: `England` |
| `match (UK Business Check match).previous_company_names` | array of objects |  |
| `match (UK Business Check match).previous_company_names[].name` | string | Example: `ACME LIMITED` |
| `match (UK Business Check match).previous_company_names[].effective_from` | string (date) or null | Example: `1998-01-01` |
| `match (UK Business Check match).previous_company_names[].ceased_on` | string (date) or null | Example: `2001-03-14` |
| `match (UK Business Check match).sic_codes` | array of strings | SIC codes as plain strings. |
| `match (UK Business Check match).officers` | array of objects | Officers appointed or resigned within the last 12 months. Long-standing officers with no change in that period are omitted. Active officers are listed first. |
| `match (UK Business Check match).officers[].officer_id` | string or null | Companies House officer appointment identifier. Can be passed to `/company_house_officer_report`. Example: `abc123` |
| `match (UK Business Check match).officers[].name` | string | Example: `SMITH, John` |
| `match (UK Business Check match).officers[].officer_role` | string | Example: `director` |
| `match (UK Business Check match).officers[].appointed_on` | string (date) or null | Example: `2020-05-01` |
| `match (UK Business Check match).officers[].resigned_on` | string (date) or null |  |
| `match (UK Business Check match).filing_history` | array of objects | Filings made within the last 12 months, newest first (from the 100 most recent filings on record). |
| `match (UK Business Check match).filing_history[].transaction_id` | string | Example: `MzQ1NjAwMQ` |
| `match (UK Business Check match).filing_history[].document_id` | string or null | Identifier for `/company_house_document/{documentId}`; null when no document is available. Example: `8j9Kx2` |
| `match (UK Business Check match).filing_history[].date` | string (date) | Example: `2026-06-30` |
| `match (UK Business Check match).filing_history[].type` | string | Companies House form type, e.g. `AA`, `CS01`, `AP01`. Example: `AA` |
| `match (UK Business Check match).filing_history[].category` | string | Example: `accounts` |
| `match (UK Business Check match).filing_history[].description` | string | Example: `accounts-with-accounts-type-micro-entity` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "match": {
        "company_number": "01234567",
        "company_name": "ACME TRADING LIMITED",
        "company_status": "active",
        "company_status_detail": null,
        "type": "ltd",
        "jurisdiction": "england-wales",
        "date_of_creation": "2001-03-14",
        "date_of_cessation": null,
        "registered_office_address": {
            "address_line_1": "1 High St",
            "address_line_2": null,
            "locality": "London",
            "region": null,
            "postal_code": "SW1A 1AA",
            "country": "England"
        },
        "previous_company_names": [
            {
                "name": "ACME LIMITED",
                "effective_from": "1998-01-01",
                "ceased_on": "2001-03-14"
            }
        ],
        "sic_codes": [
            "62012",
            "62020"
        ],
        "officers": [
            {
                "officer_id": "abc123",
                "name": "SMITH, John",
                "officer_role": "director",
                "appointed_on": "2020-05-01",
                "resigned_on": null
            }
        ],
        "filing_history": [
            {
                "transaction_id": "MzQ1NjAwMQ",
                "document_id": "8j9Kx2",
                "date": "2026-06-30",
                "type": "AA",
                "category": "accounts",
                "description": "accounts-with-accounts-type-micro-entity"
            }
        ]
    }
}
```

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