---
title: "Onboard new Legal Entities"
metaTitle: "Onboard new Legal Entities"
order: 1
showPageMenu: true
---

import EndpointBlock from "src/components/endpoint-block";
import Callout from "src/components/callout";

import WebhookPlaceholder from 'src/components/webhook-placeholder';
import WebhookSummary from 'src/components/webhook-summary';

## Legal entity onboarding

<Callout colour="green">
<h2>Legal entity onboarding is coming soon</h2>
<p>All information on this page describes a solution that is <strong>not yet live in production and therefore could change</strong>. This includes any endpoint and webhook details. The information is being provided early to aid you in integrating with our API in our UK simulation environment.</p>
</Callout>

Every legal entity needs a `CustomerId` before it can be given access to our products, such as [accounts](/uk/docs/embedded-banking/business/manage-legal-entities#compatible-account-types). 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](#onboard-with-clearbanks-due-diligence). 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](#create-a-legal-entity-with-your-own-due-diligence), 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](/uk/docs/embedded-banking/business/manage-legal-entities) page.

## Onboard with ClearBank's due diligence

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.

<Callout colour="blue">
  We can only onboard businesses that:<br /><br />
  • Are limited companies (Ltd).<br />
  • Are registered in the UK.<br />
  • Have UK tax residency.
</Callout>

### Usage

#### Initial request

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.

<Callout colour="blue">
  You should retain the `applicationId` from our <strong>202 - Accepted</strong> response to identify the application in subsequent onboarding webhook events.
</Callout>

#### Providing additional information

As our checks progress, we'll request additional information about the customer from you via the [Legal Entity Additional Info Required](#legal-entity-customer-additional-info-required-webhook) 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.

<Callout colour="blue">
  You may receive more than one Legal Entity Additional Info Required webhook per application. For example, if a company director uploads a passport as proof of ID instead of a driving licence, we'll issue another webhook requesting their proof of address.
</Callout>

#### Successful onboarding

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](#legal-entity-application-successful-webhook) 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](/uk/docs/embedded-banking/business/manage-legal-entities).

#### Declined onboarding

If the customer does not pass our due diligence checks, you'll receive a [Legal Entity Application Declined](#legal-entity-customer-application-declined-webhook) webhook.  
The business customer will not be created, and the application will be terminated.

#### Message flow diagram

![A message flow diagram demonstrating a legal entity onboarding application that requires additional information before succeeding or failing. The client submits an application 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 its due diligence checks, 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. Due diligence checks then proceed, and an application declined or application successful webhook is sent - depending on the outcome of the checks.](/assets/images/diagrams/uk/onboarding/legal-entity-onboarding-flow.svg)

<Callout colour="blue">
  <strong>Note:</strong> We will sometimes require additional information from multiple people in the same application. You should expect to receive multiple 'Pending' webhooks (Customer.LegalEntity.AdditionalInfoRequired) for each person on the same onboarding application.
</Callout>

<EndpointBlock
  type="post"
  title="Onboard a new legal entity customer"
  endpoints={[
    {
      path: "/customer-due-diligence/v1/legal-entity/onboard",
      version: "1.0customer-onboarding",
      webhooks: [
        'kyb-application-successful-v1',
        'kyb-application-declined-v1',
        'kyb-application-pending-v1'
      ]
    }
  ]}
/>

### Webhooks

<WebhookPlaceholder render='kyb-application-pending-v1' />
<WebhookPlaceholder render='kyb-application-successful-v1' />
<WebhookPlaceholder render='kyb-application-declined-v1' />

### Simulating onboarding webhooks

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**](#onboard-a-new-legal-entity-customer) 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.

## Create a legal entity with your own due diligence

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.

#### Business information

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

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

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}**](/uk/docs/embedded-banking/business/manage-legal-entities#update-a-legal-entity-customer) 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](/uk/docs/embedded-banking/business/manage-legal-entities).

<EndpointBlock
  type="post"
  title="Create a legal entity customer"
  endpoints={[
    {
      path: "/customers/v2/legal-entities",
      version: "2.0-customers-legal-entity"
    }
  ]}
/>