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

Direct API approach

For general integration notes and shared response semantics, see the 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

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.

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

{
    "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.

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

Name and address match values

Registration status values

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

{
    "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:

{
    "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):

{
    "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:

{
    "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.