---
title: "United Kingdom"
url: "https://developer.incode.com/general-reference/united-kingdom/"
section: "general-reference"
group: "eKYB Reference / eKYB Prefill Coverage"
version: "v1.1"
status: "live"
---
# United Kingdom

eKYB Prefill in the United Kingdom leverages the UK's source of truth to automatically retrieve and populate business information based on a company's Registration Number or VAT Number, including the business name, registered address, entity type, registration status, directors, shareholders, and additional financial and corporate data, without requiring manual input from the user.

## Source

| Country | Source | Description |
| --- | --- | --- |
| United Kingdom | `GB_KYB_PREFILL` | Returns matching UK business details from the UK's source of truth for pre-fill. |

## Direct API approach

For general integration notes and shared response semantics, see the [eKYB Prefill API Reference](/general-reference/ekyb-prefill-api-reference/).

All module configurations and user data can be forwarded directly in the request for performing a Prefill lookup. This overrides existing configuration and data collected about the user.

### Endpoint

`POST /omni/externalVerification/ekyb-prefill`

### Request parameters

| Parameter | Required | Description |
| --- | --- | --- |
| plugins | Mandatory | String array. Must be `["ekyb-prefill"]`. Specifies the Prefill flow. |
| source | Mandatory | String. Must be `GB_KYB_PREFILL`. Identifies the Prefill source. |
| country | Mandatory | String. Two-letter Alpha-2 country code. Must be `GB`. |
| taxId | Mandatory | String. UK Registration Number or VAT Number. See Tax ID formats for details. |
| businessName | Optional | String. Registered name of the business. When provided, adds `nameMatch` to the response. |
| address | Optional | String. Business address as a freeform string. When provided, adds `addressMatch` to the response. |

### Tax ID formats

The `taxId` field accepts two UK business identifier types. Routing between them is determined automatically by the length of the submitted value after stripping any `GB` prefix.

| ID Type | Format | Example |
| --- | --- | --- |
| **Registration Number** | 7 or 8 numeric digits | `01616165` |
| **VAT Number** | 9 numeric digits, or `GB` + 9 numeric digits | `GB374927709` or `374927709` |

Registration Number (8 digits) and VAT Number (9 digits) never overlap in length, so routing is unambiguous. Inputs of any other length return a 400 error.

### Sample request

```json
{
    "plugins": ["ekyb-prefill"],
    "source": "GB_KYB_PREFILL",
    "country": "GB",
    "taxId": "01234567",
    "businessName": "Northbridge Footwear Ltd",
    "address": "2 Example Street, London, EC1A 1BB"
}
```

### Sample response

The Prefill response returns business data retrieved directly from the source of truth. Fields are returned as-is from the source. `nameMatch` and `addressMatch` are only present when `businessName` or `address` were submitted in the request.

```json
{
  "kyb-prefill": [
    {
      "tin": "01234567",
      "vatNo": "GB123456789",
      "name": "Northbridge Footwear Ltd",
      "nameMatch": "Verified",
      "address": "2 Example Street, London, EC1A 1BB",
      "city": "London",
      "postalCode": "EC1A 1BB",
      "entityType": "Private limited with Share Capital",
      "registrationStatus": "Active",
      "registrationDate": "2012-06-18T00:00:00Z",
      "creditRating": "A",
      "creditRatingDescription": "Very Low Risk",
      "industry": "Unknown",
      "industryDesc": "Manufacture of footwear",
      "turnover": { "currency": "GBP", "value": 1026089739 },
      "employeeCount": 789,
      "activityDesc": "The manufacture and distributes sports and leisure footwear and accessories to customers across Europe and is part of one of the major players in the global sports footwear industry.",
      "otherAddresses": [
        { "type": "Main Trading Address", "otherAddress": "18 Harbour Way, Manchester, M1 2AB" },
        { "type": "Trading Address", "otherAddress": "75 Meadow Park, Birmingham, B1 1AA" }
      ],
      "shareholders": [
        { "name": "Summit Athletics Holdings Inc.", "percentSharesHeld": 100 }
      ],
      "ultimateParent": { "name": "Summit Global Industries Inc.", "country": "US" },
      "immediateParent": { "name": "Summit Athletics Holdings Inc.", "country": "US" },
      "beneficialOwners": [
        {
          "name": "Mr Ethan Caldwell",
          "dateOfBirth": "1944-06-01T00:00:00Z",
          "nationality": "American",
          "natureOfControl": "ownership-of-shares-75-to-100-percent,voting-rights-75-to-100-percent,right-to-appoint-and-remove-directors"
        }
      ],
      "websites": ["www.newbalance.co.uk"],
      "directors": [
        { "name": "Mrs Maya Reynolds", "positionName": "Director" },
        { "name": "Mr Lucas Bennett", "positionName": "Director" },
        { "name": "Mrs Sofia Mitchell", "positionName": "Director" },
        { "name": "Mrs Amelia Brooks", "positionName": "Company Secretary" },
        { "name": "Mr Daniel Foster", "positionName": "Director" }
      ]
    }
  ]
}
```
### Response fields

| Key | Value | Description |
| --- | --- | --- |
| tin | Registration Number | The company Registration Number as confirmed by the source of truth. Returned when `taxId` is submitted as a Registration Number. |
| vatNo | VAT Number | The VAT registration number as returned from the source of truth, including `GB` prefix (for example, `GB374927709`). |
| name | Business name | The registered legal name of the business as returned from the source of truth. |
| nameMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `businessName` against the name on file. Only present when `businessName` was submitted in the request. See Name and address match values for details. |
| address | Registered address | The primary registered address of the business as returned from the source of truth. |
| addressMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `address` against the registered address on file. Only present when `address` was submitted in the request. See Name and address match values for details. |
| city | City | The city of the registered address as returned from the source of truth. |
| postalCode | Postal code | The postal code of the registered address as returned from the source of truth. |
| entityType | Entity type | The legal form of the business as returned from the source of truth (for example, `Private limited with Share Capital`). |
| registrationStatus | Registration status | The current company status as returned from the source of truth (for example, `Active`). See Registration status values for details. |
| registrationDate | Date | The date the company was registered, as returned from the source of truth. |
| creditRating | Credit rating value | The standardized credit rating value (for example, `A`). |
| creditRatingDescription | Credit rating description | A human-readable description of the credit rating (for example, `Very Low Risk`). |
| industry | Industry sector | The industry sector of the business. Returns `Unknown` for UK, as this field is not available from the source of truth. |
| industryDesc | Industry description | The primary activity description as returned from the source of truth (for example, `Manufacture of footwear`). |
| turnover | `{currency, value}` | The latest turnover figure as returned from the source of truth. May not be present for all companies. |
| employeeCount | Number | The latest employee count as returned from the source of truth. May not be present for all companies. |
| activityDesc | Activity description | A free-text description of the business's principal activity as returned from the source of truth. |
| otherAddresses | Array of `{type, otherAddress}` | Additional addresses on file (for example, trading addresses), other than the primary registered address. |
| shareholders | Array of `{name, percentSharesHeld}` | Shareholders associated with the business as returned from the source of truth. |
| ultimateParent | `{name, country, registrationNumber}` | Ultimate parent company, if available. Absent when the entity is not a subsidiary. |
| immediateParent | `{name, country, registrationNumber}` | Immediate parent company, if available. Absent when the entity is not a subsidiary. |
| beneficialOwners | Array of `{name, dateOfBirth, nationality, natureOfControl}` | Beneficial owners as returned from the source of truth. UK-specific field — not present in other country responses. |
| websites | Array of strings | Website URLs associated with the business as returned from the source of truth. |
| directors | Array of `{name, positionName}` | Current directors and officers as returned from the source of truth. `positionName` reflects the primary position title on file. |

### Name and address match values

| Status | Description |
| --- | --- |
| Verified | Exact match found against registry data. |
| Approximate Match | Similar match found; may reflect minor differences in naming or address formatting. |
| Unverified | No match found in registry data. |

### Registration status values

| Status | Description |
| --- | --- |
| Active | The company is currently active and registered. |
| Inactive | The company registration is dissolved, struck off, or no longer active. |
| Unknown | The registration status could not be determined. |

## Error responses

For standard HTTP response codes, see the API Error Response page. UK Prefill returns the following country-specific 400 errors.

`taxId` is missing, empty, or not a valid Registration Number (7–8 digits) or VAT Number (9 digits or `GB` + 9 digits):

```json
{
    "timestamp": 1782851408892,
    "status": 400,
    "error": "Bad Request",
    "message": "taxId must be a valid UK Registration Number (7-8 digits) or VAT Number (9 digits, optionally prefixed with GB)",
    "path": "/omni/externalVerification/ekyb-prefill"
}
```

Any mandatory field (`plugins`, `source`, `country`, or `taxId`) is missing:

```json
{
    "timestamp": 1782851468367,
    "status": 400,
    "error": "Bad Request",
    "message": "must not be blank",
    "path": "/omni/externalVerification/ekyb-prefill"
}
```

Wrong country code is provided (any value other than `GB`):

```json
{
    "timestamp": 1782851583695,
    "status": 400,
    "error": "Bad Request",
    "message": "IllegalArgumentException: No enum constant com.incodesmile.onboarding.integration.external.government.ekyb.domain.entity.model.EkybCountry.GB",
    "path": "/omni/externalVerification/ekyb-prefill"
}
```

No business match is found for the submitted `taxId`:

```json
{
    "timestamp": 1782851583695,
    "status": 200,
    "message": "No business found matching the provided tax ID.",
    "path": "/omni/externalVerification/ekyb-prefill"
}
```

## Single Session Dashboard results

Prefill results are available on the Business tab in [single Session view](/dashboard-platform-administration/single-session-view/).