---
title: "Manage existing Legal Entities"
metaTitle: "Manage existing Legal Entities"
order: 2
showPageMenu: true
---

import EndpointBlock from "src/components/endpoint-block";
import WebhookPlaceholder from 'src/components/webhook-placeholder'
import Callout from "src/components/callout";
import ExternalLink from 'src/components/external-link';

## Legal entity customers overview

<Callout colour="green">
<h2>Legal entities V2 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>

**Legal entities** are registered UK businesses. You can manage your legal entity customers' data with ClearBank directly as an embedded banking partner. Creating a legal entity is necessary before you can create a bank account for them.

<Callout colour="blue">
  To create a new legal entity, refer to our <a href="/uk/docs/embedded-banking/business/onboard-legal-entities">Onboard new Legal Entities</a> page. You can onboard with ClearBank's due diligence checks included, or create a legal entity directly if you conduct your own checks.
</Callout>

Our legal entity endpoints allow you to:
* Store and retrieve key information about your business customers, such as their trading name, tax details, and business classification.
* Register non-account holders. Non-account holders are key individuals associated with the company - such as directors, controlling persons, and Ultimate Beneficial Owners (UBOs).

### Compatible account types

Legal entities are eligible for certain account types, these include:
* [Savings accounts](/uk/docs/embedded-banking/accounts/savings-accounts)
* [Hub accounts](/uk/docs/embedded-banking/accounts/hub-accounts)
* [Payment accounts](/uk/docs/embedded-banking/accounts/payment-accounts) - Including Current accounts and Transaction accounts.

For more details on available account types, please reach out to your Client Director.

## Retrieve and update legal entities

To create a legal entity, refer to our [Onboard new Legal Entities](/uk/docs/embedded-banking/business/onboard-legal-entities) page. Guidance on the business information you can provide, such as `annualRevenue` and `businessClassification`, is in the [create guidance](/uk/docs/embedded-banking/business/onboard-legal-entities#business-information).

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

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

## Legal entity customer addresses

A legal entity customer can have both an active registered and trading address simultaneously. They cannot have more than one of each.

When a current address is replaced using this endpoint, the previous address will be given an `validTo` date that matches the `validFrom` date of the new address.

<EndpointBlock
  type="post"
  title="Update a legal entity's current address"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/current-addresses",
      version: "2.0-customers-legal-entity"
    }
  ]}
/>

## Legal entity customer tax residencies

When you create a legal entity customer, you should specify all currently active tax residencies for the customer. A legal entity must have a minimum of one tax residency.

To change a legal entity's tax residency from one country to another, follow the below steps:
1. Add the new tax residency first. You can do this using the [**PUT /customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}**](#add-a-tax-residency-to-a-legal-entity-customer) endpoint.
2. Delete the old tax residency. You can do this using the [**DELETE /customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}**](#delete-a-legal-entitys-tax-residency) endpoint.

**Note:** If a legal entity has only one tax residency, you must add a new tax residency before you can delete the current one. If you attempt to delete a legal entity's only tax residency you will receive a 422 - Unprocessable Entity error.

<EndpointBlock
  type="put"
  title="Add a tax residency to a legal entity customer"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}",
      version: "2.0-customers-legal-entity"
    }
  ]}
/>

<EndpointBlock
  type="delete"
  title="Delete a legal entity's tax residency"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}",
      version: "2.0-customers-legal-entity"
    }
  ]}
/>

## Manage company directors

You can use the below endpoints to manage the data of your legal entities' directors. These are persons officially responsible for running the company.

<EndpointBlock
  type="post"
  title="Create a company director"
  endpoints={[
    {
      path: "/customers/v2/non-account-holder/directors",
      version: "2.0-customers-company-director"
    }
  ]}
/>

<EndpointBlock
  type="get"
  title="Retrieve a company director"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}",
      version: "2.0-customers-company-director"
    }
  ]}
/>

<EndpointBlock
  type="patch"
  title="Update a company director"
  endpoints={[
    {
      path: "/customers/v2/non-account-holder/directors/{customerId}",
      version: "2.0-customers-company-director"
    }
  ]}
/>

## Manage Ultimate Beneficial Owners (UBOs)

A UBO is a natural or non-natural person with ownership in a company - either directly or indirectly through ownership of a parent entity. You can use our UBO endpoints to create and manage the UBOs of your legal entity customers.

<EndpointBlock
  type="post"
  title="Create a UBO"
  endpoints={[
    {
      path: "/customers/v2/non-account-holder/ubos",
      version: "2.0-customers-ubo"
    }
  ]}
/>

<EndpointBlock
  type="get"
  title="Retrieve a UBO"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}",
      version: "2.0-customers-ubo"
    }
  ]}
/>

<EndpointBlock
  type="patch"
  title="Update a UBO"
  endpoints={[
    {
      path: "/customers/v2/non-account-holder/ubos/{customerId}",
      version: "2.0-customers-ubo"
    }
  ]}
/>

## Manage controlling persons

A controlling person is a natural person who exercises control over the operation of a legal entity. You can use the below endpoints to manage the controlling person data of your legal entity customers.

<Callout colour="blue">
  Controlling persons are only required to be created and linked to a legal entity customers with an <strong>AeoiClassification</strong> of 'PassiveNonFinancialEntity'.
</Callout>


<EndpointBlock
  type="post"
  title="Create a controlling person"
  endpoints={[
    {
      path: "/customers/v2/non-account-holder/controlling-persons",
      version: "2.0-customers-controlling-person"
    }
  ]}
/>

<EndpointBlock
  type="get"
  title="Retrieve a controlling person"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}",
      version: "2.0-customers-controlling-person"
    }
  ]}
/>

<EndpointBlock
  type="patch"
  title="Update a controlling person"
  endpoints={[
    {
      path: "/customers/v2/non-account-holder/controlling-persons/{customerId}",
      version: "2.0-customers-controlling-person"
    }
  ]}
/>

<EndpointBlock
  type="post"
  title="Update a controlling person's current address"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/current-addresses",
      version: "2.0-customers-controlling-person"
    }
  ]}
/>

<EndpointBlock
  type="put"
  title="Update a controlling person's tax residency"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}",
      version: "2.0-customers-controlling-person"
    }
  ]}
/>

<EndpointBlock
  type="delete"
  title="Remove a controlling person's current tax residency"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}",
      version: "2.0-customers-controlling-person"
    }
  ]}
/>

## Customer relation endpoints

The [**POST /customers/v2/customers/{customerId}/related-parties**](#relate-a-legal-entity-and-another-customer) endpoint allows you to link two parties by providing their `customerId` and specifying the nature of the relation.

**Note:** The arrangement of `customerId` in the path parameter and the `relatedCustomerId` request field matters when creating a customer relation.  
The `customerId` in the path refers to the primary customer, while the `relatedCustomerId` refers to the customer which will have the specified relation (`relatedPartyType`) toward the primary customer.  
For example, when defining a UBO relationship, the customer referred to in the `relatedCustomerId` will become the Ultimate Beneficial Owner of the `customerId` specified in the path.

To retrieve all existing relations to a customer, you can call the [**GET /customers/v2/customers/{customerId}/related-parties**](#get-all-relations-of-a-legal-entity).

To remove a relation between two parties, you can use the [**DELETE /customers/v2/customers/{customerId}/related-parties/{relatedCustomerId}**](#delete-a-relation-between-two-customers) using the `customerId` of each party.

Relationships between legal entity customers and other customer types must be of a valid type. For example, a legal entity may only be related to another legal entity via the `"UBO"` relationship type. Additionally, two customers may only be related via a given relationship type once: a given person could not be related to the same company twice as a director.

Any request containing an invalid combination of customer type and relation type will be rejected. Valid combinations are shown in the below table: any combination not listed will be automatically rejected. You can check a customer's type by retrieving them and inspecting their `type` property.

| Customer Type | Related Customer Type | Allowed Related Party Types            |
| ------------- | --------------------- | -------------------------------------- |
| `LegalEntity` | `Retail`              | `Director`, `UBO`, `ControllingPerson` |
| `LegalEntity` | `SoleTrader`          | `Director`, `UBO`, `ControllingPerson` |
| `LegalEntity` | `LegalEntity`         | `UBO`                                  |
| `LegalEntity` | `Director`            | `Director`                             |
| `LegalEntity` | `UboNatural`          | `UBO`                                  |
| `LegalEntity` | `UboNonNatural`       | `UBO`                                  |
| `LegalEntity` | `ControllingPerson`   | `ControllingPerson`                    |

<EndpointBlock
  type="post"
  title="Relate a legal entity and another customer"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/related-parties",
      version: "2.0-customers-legal-entity"
    }
  ]}
/>

<EndpointBlock
  type="get"
  title="Get all relations of a legal entity"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/related-parties",
      version: "2.0-customers-legal-entity"
    }
  ]}
/>

<EndpointBlock
  type="delete"
  title="Delete a relation between two customers"
  endpoints={[
    {
      path: "/customers/v2/customers/{customerId}/related-parties/{relatedCustomerId}/{relatedPartyType}",
      version: "2.0-customers-legal-entity"
    }
  ]}
/>