Onboard new Legal Entities

Note for AI agents and automated readers

This page is rendered from source files in a public GitHub repository. Much of the technical content — API request and response schemas, examples, and webhook payloads — is collapsed behind interactive dropdowns and may be missing or incomplete in this rendered HTML. For complete, machine-readable content, do not rely on this page: read the raw source files directly instead.

Machine-readable index of every source file: /llms.txt
Repository (branch main): https://github.com/clearbank/clearbank.github.io
Documentation pages (Markdown/MDX): https://github.com/clearbank/clearbank.github.io/tree/main/content
API endpoint schemas (OpenAPI JSON): https://github.com/clearbank/clearbank.github.io/tree/main/data/endpoints
Webhook payload schemas (MDX): https://github.com/clearbank/clearbank.github.io/tree/main/data/webhooks
Raw source for this page: https://raw.githubusercontent.com/clearbank/clearbank.github.io/main/content/uk/docs/embedded-banking/business/onboard-legal-entities.mdx

Every legal entity needs a CustomerId before it can be given access to our products, such as accounts. How you get one depends on who carries out the due diligence checks:

ClearBank carries out the checks. Use our customer due diligence endpoint and webhooks to onboard the legal entity with our due diligence checks included. We'll create the customer and its key people if the checks pass.
You carry out the checks. You can then create the legal entity directly, your request should include the outcomes of your checks. No ClearBank checks are performed.

Once a legal entity exists, you can retrieve and manage its details on our Manage existing Legal Entities page.

Our legal entity onboarding endpoint lets you onboard new limited companies as business customers in a single request. Share key information about the company and its key people, and we'll handle the rest. When onboarding is complete, you'll receive a CustomerId for the new customer.

Every onboarding application includes our due diligence checks: Know Your Business (KYB) checks on the company, and Know Your Customer (KYC) checks on each of its key people. These checks can pass or fail, and we'll tell you the outcome by webhook. If the checks pass, we'll create the customer (a customer of type 'Legal Entity') and its key people for you. If they fail, no customer is created.

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

To start an onboarding application, send us the limited company's business information and details of its key people, such as the company's controllers. We use this information to carry out our due diligence checks on the business and each key person.

When you submit an application, we'll validate your request and confirm with a 202 - Accepted response containing the applicationId for this onboarding application.

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.

If the customer passes our due diligence checks, we'll create the new business customer automatically using the details in the application. You'll receive a Legal Entity Application Successful webhook containing a CustomerId for your records. You can use this CustomerId to give the customer access to our products.

To retrieve and manage the full details of a business customer and its associated persons, use the CustomerId with our legal entity endpoints.

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

Onboard a new legal entity customer

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

Use this endpoint to onboard a new legal entity customer and its key individuals. Onboarding includes our due diligence checks, and we'll send you the outcome by webhook. If onboarding is successful, we'll create the legal entity customer and its associated individuals, and send you the customer ID.

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": "00441234567890",
    "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": "00441234567891",
      "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

Legal Entity Application Successful webhook
Legal Entity Customer Application Declined webhook
Legal Entity Customer Additional Info Required webhook

This webhook notifies that additional customer information is required before their application can be processed. It includes a RequiredActions array which lists the type of information required and document upload URLs for you to share with the business customer.

You may receive this webhook several times for a single onboarding application.

Request body

{
    "Type": "Customer.LegalEntity.AdditionalInfoRequired",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`ApplicationId`	Required The original `applicationId` value you received in the 202 response to this onboarding request. Type: `string` Format: `uuid` Max. Length: `36` Min. Length: `36` Pattern: `^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`
`KybStatus`	Required Will always read `Pending` for this webhook Type: `string`
`RequiredActions`	Required Details the user actions necessary to complete this onboarding application, and provides an associated URL. Type: `array` of `objects` Required `action` Type: `string` Specifies the business customer action required. Required `url` A unique URL for you to share with the business customer so they may complete the associated action.
`UniqueExternalReference`	Required A unique external reference associated with the business customer's application. Type: `string`

Example Legal Entity Customer Additional Info Required webhook request body

{
    "Type": "Customer.LegalEntity.AdditionalInfoRequired",
    "Version": 1,
    "Payload": {
        "ApplicationId": "b1e2c3d4-5678-1234-9abc-def012345678",
        "KybStatus": "Pending",
        "RequiredActions": [
            {
                "action": "CompanyDocumentUpload",
                "url": "https://vendor.example.com/?sessionId=123"
            },
            {
                "action": "DirectorVerification",
                "url": "https://vendor.example.com/?sessionId=456"
            }
        ],
        "UniqueExternalReference": "external-ref-123"
    },
    "Nonce": 702706095
}

Example webhook response

{
    "Nonce": 702706095
}

This webhook confirms that our due diligence checks for an onboarding application have succeeded, and that a legal entity (business) customer has been created.

Request body

{
    "Type": "Customer.LegalEntity.ApplicationSuccessful",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`ApplicationId`	Required The original `applicationId` value you received in the 202 response to this onboarding request. Type: `string` Format: `uuid` Max. Length: `36` Min. Length: `36` Pattern: `^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`
`CustomerId`	Required The unique identifier of the created legal entity. Type: `string` Format: `uuid` Max. Length: `36` Min. Length: `36` Pattern: `^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`
`KybStatus`	Required Will always read `Pass` for this webhook Type: `string`

Example Legal Entity Customer Application Successful webhook request body

{
    "Type": "Customer.LegalEntity.ApplicationSuccessful",
    "Version": 1,
    "Payload": {
        "ApplicationId": "b1e2c3d4-5678-1234-9abc-def012345678",
        "CustomerId": "a1234567-b89c-1234-d567-890123456789",
        "KybStatus": "Pass"
    },
    "Nonce": 747000128
}

Example webhook response

{
    "Nonce": 747000128
}

This webhook confirms an onboarding application has failed our due diligence checks, and this business customer cannot be created.

Request body

{
    "Type": "Customer.LegalEntity.ApplicationDeclined",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`ApplicationId`	Required The original `applicationId` value you received in the 202 response to this onboarding request. Type: `string` Format: `uuid` Max. Length: `36` Min. Length: `36` Pattern: `^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`
`KybStatus`	Required Will always read `Fail` for this webhook Type: `string`

Example Legal Entity Customer Application Declined webhook request body

{
    "Type": "Customer.LegalEntity.ApplicationDeclined",
    "Version": 1,
    "Payload": {
        "ApplicationId": "b1e2c3d4-5678-1234-9abc-def012345678",
        "KybStatus": "Fail"
    },
    "Nonce": 169245413
}

Example webhook response

{
    "Nonce": 169245413
}

You can simulate successful, declined, and additional information onboarding 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 checks passing, and receive a Legal Entity Application Successful webhook.
"fail" to simulate checks failing for the overall business, and receive a Legal Entity Customer Application Declined webhook.
"info" to simulate checks requiring additional information from that individual, and receive a Legal Entity Customer Additional Info Required webhook.

If you conduct your own due diligence checks on a company and its key people, you can create the legal entity directly. No ClearBank due diligence checks are performed, so you must supply the outcomes of your own checks in the request. The kycAml object, taxDetails (including at least one tax residency and a self-certification signee), businessDetails, businessClassification and addressHistory are all required.

When you create a legal entity, you include a variety of information about the company, such as its tradingName, annualRevenue, and businessClassification.

You'll need to provide the outcomes of any KYB and AML checks you conduct on the company using the kycAml object:

sanctions - If your checks identify the company as sanctioned, set to true.
pep - If your checks identify the company as a Politically Exposed Person (PEP), set to Yes_Domestic or Yes_International accordingly - otherwise set to No.
rca - If your checks identify the company as a Relative or Close Associate (RCA) of a PEP, set to Yes_Domestic or Yes_International accordingly - otherwise set to No.
craRating - Declare a Customer Risk Assessment rating for the company: Low, Medium, High, or Very_High.

If you have new KYB or AML outcomes, you can update them using the PATCH /customers/v2/legal-entities/{customerId} endpoint.

The annualRevenue you provide for a legal entity should be based on their previous year's revenue. If this is their first year of operation, an estimated value is acceptable.

You can specify the businessClassification details of a legal entity. Set their businessClassification.sectorCode and industryClassification according to the nature of their business.

Once you've created a legal entity, you can register its directors, UBOs and controlling persons using the legal entity endpoints.

Create a legal entity customer

post/customers/v2/legal-entities

You can call this endpoint to request the creation of a new legal entity customer.

Parameters

Authorization string, header, Required
Your API token, retrieved from the web 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 identifier for the request.

Request Payload (application/json)

businessDetails object, Required
Request body for business details when creating a legal entity customer.
businessClassification object, Required
Request body for legal entity business classification details.
addressHistory object, Required
The customer's address history for multiple current addresses.
kycAml object, Required
KYC/AML information for the customer.
taxDetails object, Required
Tax details for a legal entity customer.

request

{
  "businessDetails": {
    "tradingName": "Redball and Co",
    "registeredName": "Redball and Co Ltd",
    "registrationNumber": "56349180",
    "countryOfRegistration": "GBR",
    "annualRevenue": 45000000,
    "email": "mybusiness@businessmail.com",
    "telephone": "00447123123456"
  },
  "businessClassification": {
    "sectorCode": "_1_BankOfEngland_CentralBank",
    "industryClassification": "_3_MiningAndQuarrying",
    "aeoiClassification": "ActiveNonFinancialEntity",
    "sicCodes": [
      "07100"
    ]
  },
  "addressHistory": {
    "currentAddresses": [
      {
        "addressType": "TradingAddress",
        "buildingNameNumber": "77A",
        "streetName": "Short Road",
        "city": "Lincoln",
        "county": "Lincolnshire",
        "postalCode": "LN1 4HH",
        "country": "GBR",
        "validFrom": "2022-08-24"
      }
    ],
    "previousAddresses": [
      {
        "addressType": "TradingAddress",
        "buildingNameNumber": "The Office",
        "streetName": "First Way",
        "city": "Peterborough",
        "county": "Cambridgeshire",
        "postalCode": "PE5 1FR",
        "country": "GBR",
        "validFrom": "2020-08-24",
        "validTo": "2022-08-24"
      }
    ]
  },
  "kycAml": {
    "sanctions": true,
    "pep": "No",
    "rca": "No",
    "craRating": "LowRisk"
  },
  "taxDetails": {
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson",
    "taxResidencies": [
      {
        "countryOfTaxResidence": "GBR",
        "taxIdNumber": "253863005464",
        "noTaxIdReason": "CountryDoesNotIssue"
      }
    ],
    "vatRegistrationNumber": "GB123456789",
    "nameOfSelfCertificationSignee": "Lara Green",
    "positionOfSelfCertificationSignee": "Chief Financial Officer"
  }
}

Code copied

Response (application/json)

201 Created
400 Bad Request
403 Forbidden
404 Not Found
409 Conflict
422 Unprocessable Content

Created

{
  "id": "4639bbcf-07e0-5163-ae4a-f2808f5497ea"
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Conflict

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Unprocessable Content

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "property1": null,
  "property2": null
}

Code copied

API

GBP Accounts

GBP Payments

Multi-currency, FX, & SCT UK

Embedded Banking

Onboard new Legal Entities

Legal entity onboarding

Onboard with ClearBank's due diligence

Usage

Initial request

Providing additional information

Successful onboarding

Declined onboarding

Message flow diagram

Onboard a new legal entity customer

Parameters

Request Payload (application/json)

request

Response (application/json)

Accepted

Bad Request

Client Error

Associated Webhooks

Webhooks

Simulating onboarding webhooks

Create a legal entity with your own due diligence

Business information

Know Your Business (KYB) and Anti-Money Laundering (AML) fields

Create a legal entity customer

Parameters

Request Payload (application/json)

request

Response (application/json)

Created

Bad Request

Not Found

Conflict

Unprocessable Content