ClearBank

API

GBP Accounts

GBP Payments

Multi-currency, FX, & SCT UK

Embedded Banking

Know Your Business (KYB)

Business customer KYB

Overview

Our Know Your Business (KYB) endpoint makes it easy to meet your due diligence requirements when onboarding new Limited Companies. By sharing key company information, you can conduct Know Your Business checks on limited companies and receive the results via webhook.

For convenience, we'll also use the information provided in the KYB check to register the customer as a new Limited Company (a customer of type 'Legal Entity') and its key people if the checks succeed.

If you'd like to use this product, please contact your Client Director.

Usage

Initial request

Our KYB endpoint consumes Limited Companies' business information and details of key business personnel, such as the company's controllers. We use this information to perform KYB checks on the business and Know Your Customer (KYC) checks on each key person.

When you request a check using our KYB endpoint, we'll validate your request and confirm with a 202 - Accepted response containing the applicationId for this KYB application.

Providing additional information

As our checks progress, we'll request additional information about the customer from you via the Legal Entity Additional Info Required webhook. This webhook contains an array of URLs (RequiredActions[].url) for you to share with the customer, who can then provide this information. For clarity, the type of additional information requested in each URL is specified in the RequiredActions[].action property.

Additional information we may request includes:

  • Proof of ID and proof of address for key personnel, such as directors.
  • Certain company documents.

Successful KYB check

If the customer passes our KYB checks, we'll create the new business customer automatically using the provided application details. You'll receive a Legal Entity Application Successful webhook containing a CustomerId for your records.

To retrieve and manage the full details of a business customer and its associated persons, please refer to our Legal Entity endpoints where you can retrieve these using the CustomerId provided by this service.

Declined KYB check

If the customer does not pass our KYB checks, you'll receive a Legal Entity Application Declined webhook.
The business customer will not be created, and the application will be terminated.

Message flow diagram

A message flow diagram demonstrating a KYB requiring additional information before succeeding or failing. The client requests a check using the POST /customer-due-diligence/v1/legal-entity/onboard endpoint, which is acknowledged with a 202 Accepted response. ClearBank identifies further information is required to complete this check, and emits a Legal Entity Additional Info Required webhook containing the information required from the customer and URLs to provide it. The business customer uploads the information, which is received by ClearBank. KYB checks then proceed, and an application declined or application successful webhook is sent - depending on the outcome of the checks.

Endpoint

KYB check and create a new business customer endpoint

post/customer-due-diligence/v1/legal-entity/onboard

Use this endpoint to conduct KYB checks for a new business customer and KYC checks on its key individuals. If the checks pass, the provided details are then used to create a new legal entity customer and its associated individuals.

Parameters

  • Authorization string, header, Required

    Your API token, obtained from the ClearBank Portal.

  • DigitalSignature string, header, Required

    Signed hash of the body of the request. The hash is signed by your private key.

  • X-Request-Id string, header, Required

    A unique identifer for the request; valid for 24 hours, max length 83..

Request Payload (application/json)

  • business object, Required

    The details of this business, including their address, tax information, and registration details.

  • individuals array, Required

    The individuals associated with this business, such as its directors, UBOs, controllers, signatories, and account opening authorities. One individual may hold multiple roles. Must include at least one 'Ubo' (maximum 10), at least one 'Controller', and at least one 'Director'. Each uniqueExternalReference must be unique across all individuals (case-insensitive).

request

{
  "business": {
    "businessType": "Ltd",
    "businessName": {
      "registeredName": "Your Company Ltd",
      "tradingName": "Your Company"
    },
    "email": "contact@yourcompany.co.uk",
    "phone": "+441234567890",
    "address": {
      "registeredAddress": {
        "buildingName": null,
        "buildingNumber": "270",
        "subBuilding": null,
        "streetName": "Long Road",
        "city": "Manchester",
        "county": "Greater Manchester",
        "postalCode": "M1 1AF",
        "countryCode": "GBR"
      },
      "tradingAddress": {
        "buildingName": null,
        "buildingNumber": "270",
        "subBuilding": null,
        "streetName": "Long Road",
        "city": "Manchester",
        "county": "Greater Manchester",
        "postalCode": "M1 1AF",
        "countryCode": "GBR"
      }
    },
    "sicCode": [
      "07100"
    ],
    "incorporationDate": "2005-05-22",
    "companyRegistrationNumber": "55TORXBS",
    "annualRevenue": 1000000.12,
    "sourceOfFunds": "Director's loan",
    "countryOfOperations": "GBR",
    "tax": {
      "validSelfCertification": true,
      "nameOfSelfCertificationSignee": "John Smith",
      "positionOfSelfCertificationSignee": "Financial Executive",
      "vatRegistrationNumber": "GB123456789",
      "taxResidency": "GBR"
    },
    "notProhibitedIndustry": true,
    "numberOfEmployees": 25,
    "organisationalLayers": 1,
    "noTradingName": false,
    "noTradingAddress": false
  },
  "individuals": [
    {
      "association": [
        "Director",
        "Ubo",
        "Controller"
      ],
      "name": {
        "firstName": "Miles",
        "middleName": "Middle",
        "surname": "Gilligan"
      },
      "dateOfBirth": "1975-05-22",
      "nationality": "GBR",
      "email": "my.email@example.com",
      "mobile": "01234567891",
      "address": {
        "buildingName": null,
        "buildingNumber": "270",
        "subBuilding": null,
        "streetName": "Long Road",
        "city": "Manchester",
        "county": "Greater Manchester",
        "postalCode": "M1 1AF",
        "countryCode": "GBR"
      },
      "uniqueExternalReference": "ASSOCIATE-000123",
      "taxResidency": "GBR",
      "uboType": "Natural",
      "ownershipPercentage": 100,
      "tax": {
        "validSelfCertification": true
      },
      "nationalInsuranceNumber": "PD224466D"
    }
  ]
}
Code copied

Response (application/json)

  • 202 Accepted
  • 400 Bad Request
  • 405 Request method is not supported for requested resource.
  • 415 Content type is not supported by the server.
  • 499 Client Error
  • 503 Service Unavailable

Accepted

{
  "applicationId": "47ca0728-7db3-577f-94f2-80668239f430"
}
Code copied

Bad Request

{
  "type": "https://httpstatuses.io/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Descriptive error detail.",
  "instance": "",
  "property1": null,
  "property2": null
}
Code copied

Client Error

{
  "type": "https://httpstatuses.io/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Descriptive error detail.",
  "instance": "",
  "property1": null,
  "property2": null
}
Code copied

Associated Webhooks

Webhooks

Simulating KYB webhooks

You can simulate successful, declined, and additional information KYB webhooks in our simulation environment.
To do this, call the POST /customer-due-diligence/v1/legal-entity/onboard endpoint with one of the businessData.individuals[].name.surname properties set to:

  • "pass" to simulate a successful KYB webhook.
  • "fail" to simulate a declined KYB webhook for the overall business.
  • "info" to simulate an additional information required KYB webhook for that individual.