ClearBank

API

GBP Accounts

GBP Payments

Multi-currency, FX, & SCT UK

Embedded Banking

Legal entity customers

Legal entity customers overview

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.

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:

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

Create, retrieve and update legal entities

When you create a legal entity, you include a variety of information about the company. This includes their KYC/AML data, tradingName, annualRevenue, and businessClassification.

The annualRevenue you provide for a legal entities 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.

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": "07123123456"
  },
  "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": "LN14HH",
        "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

Retrieve a legal entity customer

get/customers/v2/customers/{customerId}

You can call this endpoint to retrieve the details of a legal entity customer by their customer ID.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The customer ID of the legal entity.

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

OK

{
  "id": "4639bbcf-07e0-5163-ae4a-f2808f5497ea",
  "institutionId": "bf9c0a8f-2533-5890-bf2a-b0fc1303a110",
  "status": "Active",
  "type": "LegalEntity",
  "kycAml": {
    "sanctions": false,
    "pep": "No",
    "rca": "No",
    "craRating": "LowRisk"
  },
  "taxDetails": {
    "taxResidencies": [
      {
        "countryOfTaxResidence": "GBR",
        "taxIdNumber": "253863005464",
        "noTaxIdReason": "CountryDoesNotIssue"
      }
    ],
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson",
    "vatRegistrationNumber": "GB123456789",
    "nameOfSelfCertificationSignee": "Lara Green",
    "positionOfSelfCertificationSignee": "Chief Financial Officer"
  },
  "businessDetails": {
    "tradingName": "Redball and Co",
    "registeredName": "Redball and Co Ltd",
    "registrationNumber": "56349180",
    "countryOfRegistration": "GBR",
    "annualRevenue": 45000000,
    "email": "mybusiness@businessmail.com",
    "telephone": "07123123456"
  },
  "businessClassification": {
    "sectorCode": "_1_BankOfEngland_CentralBank",
    "industryClassification": "_3_MiningAndQuarrying",
    "aeoiClassification": "ActiveNonFinancialEntity",
    "sicCodes": [
      "07100"
    ]
  },
  "addresses": {
    "currentAddresses": [
      {
        "addressType": "TradingAddress",
        "buildingNameNumber": "77A",
        "streetName": "Short Road",
        "city": "Lincoln",
        "county": "Lincolnshire",
        "postalCode": "LN14HH",
        "country": "GBR",
        "validFrom": "2022-05-15",
        "validTo": "2023-02-18",
        "isCurrentAddress": false
      }
    ],
    "previousAddresses": [
      {
        "addressType": "TradingAddress",
        "buildingNameNumber": "77A",
        "streetName": "Short Road",
        "city": "Lincoln",
        "county": "Lincolnshire",
        "postalCode": "LN14HH",
        "country": "GBR",
        "validFrom": "2022-05-15",
        "validTo": "2023-02-18",
        "isCurrentAddress": false
      }
    ]
  }
}
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

Update a legal entity customer

patch/customers/v2/legal-entities/{customerId}

You can call this endpoint to update the details of a legal entity customer. To update a legal entity's current registered or trading address, refer to the dedicated address endpoint.

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.

  • customerId string, path, Required

    The customer ID of the legal entity.

Request Payload (application/json)

  • businessDetails object

    Object containing the business details of this legal entity.

  • businessClassification object

    Request body specific for Legal Entity business classification details.

  • kycAml object

    KYC AML update request. Null values are ignored.

  • taxDetails object

    Tax details for a legal entity customer.

request

{
  "businessDetails": {
    "tradingName": "Bluebox and Co",
    "registeredName": "Bluebox and Co Ltd",
    "registrationNumber": "75620653",
    "countryOfRegistration": "GBR",
    "annualRevenue": 50000,
    "email": "mymail@yourbusiness.net",
    "telephone": "01111444777"
  },
  "businessClassification": {
    "sectorCode": "_1_BankOfEngland_CentralBank",
    "industryClassification": "_3_MiningAndQuarrying",
    "aeoiClassification": "ActiveNonFinancialEntity",
    "sicCodes": [
      "07100"
    ]
  },
  "kycAml": {
    "sanctions": false,
    "pep": "No",
    "rca": "No",
    "craRating": "LowRisk"
  },
  "taxDetails": {
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson",
    "vatRegistrationNumber": "GB123456789",
    "nameOfSelfCertificationSignee": "Lara Green",
    "positionOfSelfCertificationSignee": "Chief Financial Officer"
  }
}
Code copied

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

OK

{
  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  "businessDetails": {
    "tradingName": "Bluebox and Co",
    "registeredName": "Bluebox and Co Ltd",
    "registrationNumber": "75620653",
    "countryOfRegistration": "GBR",
    "annualRevenue": 50000,
    "email": "mymail@yourbusiness.net",
    "telephone": "01111444777"
  },
  "businessClassification": {
    "industryClassification": "_3_MiningAndQuarrying",
    "sectorCode": "_1_BankOfEngland_CentralBank",
    "aeoiClassification": "ActiveNonFinancialEntity",
    "sicCodes": [
      "07100"
    ]
  },
  "kycAml": {
    "sanctions": false,
    "pep": "No",
    "rca": "No",
    "craRating": "LowRisk"
  },
  "taxDetails": {
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson",
    "vatRegistrationNumber": "GB123456789",
    "nameOfSelfCertificationSignee": "Lara Green",
    "positionOfSelfCertificationSignee": "Chief Financial Officer"
  }
}
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

Unprocessable Content

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

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.

Update a legal entity's current address

post/customers/v2/customers/{customerId}/current-addresses

You can call this endpoint to updates a legal entity's current address. The old address is retained as a previous address.

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.

  • customerId string, path, Required

    The customer ID of the legal entity.

Request Payload (application/json)

  • addressType string, Required

    Represents the type of the address.

    Enum array
    TradingAddress, RegisteredAddress
  • buildingNameNumber string, Required

    The building name or number of this address.

    Minimum length
    1
  • streetName string, Required

    The street name of this address.

    Minimum length
    1
  • city string, Required

    The name of the city at this address.

    Minimum length
    1
  • county string

    The name of the county at this address.

    Minimum length
    1
  • postalCode string, Required

    The post code of this address.

    Minimum length
    1
  • country string, Required

    3-letter country code, as defined in ISO 3166-1.

    Enum array
    AFG, ALB, ATA, DZA, ASM, AND, AGO, ATG, AZE, ARG, AUS, AUT, BHS, BHR, BGD, ARM, BRB, BEL, BMU, BTN, BOL, BIH, BWA, BVT, BRA, BLZ, IOT, SLB, VGB, BRN, BGR, MMR, BDI, BLR, KHM, CMR, CAN, CPV, CYM, CAF, LKA, TCD, CHL, CHN, TWN, CXR, CCK, COL, COM, MYT, COG, COD, COK, CRI, HRV, CUB, CYP, CZE, BEN, DNK, DMA, DOM, ECU, SLV, GNQ, ETH, ERI, EST, FRO, FLK, SGS, FJI, FIN, ALA, FRA, GUF, PYF, ATF, DJI, GAB, GEO, GMB, PSE, DEU, GHA, GIB, KIR, GRC, GRL, GRD, GLP, GUM, GTM, GIN, GUY, HTI, HMD, VAT, HND, HKG, HUN, ISL, IND, IDN, IRN, IRQ, IRL, ISR, ITA, CIV, JAM, JPN, KAZ, JOR, KEN, PRK, KOR, KWT, KGZ, LAO, LBN, LSO, LVA, LBR, LBY, LIE, LTU, LUX, MAC, MDG, MWI, MYS, MDV, MLI, MLT, MTQ, MRT, MUS, MEX, MCO, MNG, MDA, MNE, MSR, MAR, MOZ, OMN, NAM, NRU, NPL, NLD, CUW, ABW, SXM, BES, NCL, VUT, NZL, NIC, NER, NGA, NIU, NFK, NOR, MNP, UMI, FSM, MHL, PLW, PAK, PAN, PNG, PRY, PER, PHL, PCN, POL, PRT, GNB, TLS, PRI, QAT, REU, ROU, RUS, RWA, BLM, SHN, KNA, AIA, LCA, MAF, SPM, VCT, SMR, STP, SAU, SEN, SRB, SYC, SLE, SGP, SVK, VNM, SVN, SOM, ZAF, ZWE, ESP, SSD, SDN, ESH, SUR, SJM, SWZ, SWE, CHE, SYR, TJK, THA, TGO, TKL, TON, TTO, ARE, TUN, TUR, TKM, TCA, TUV, UGA, UKR, MKD, EGY, GBR, GGY, JEY, IMN, TZA, USA, VIR, BFA, URY, UZB, VEN, WLF, WSM, YEM, ZMB
  • validFrom string

    The date from which this address is valid. Defaults to today's date if unspecified.

request

{
  "addressType": "TradingAddress",
  "buildingNameNumber": "77A",
  "streetName": "Short Road",
  "city": "Lincoln",
  "county": "Lincolnshire",
  "postalCode": "LN14HH",
  "country": "GBR",
  "validFrom": "2022-08-24"
}
Code copied

Response (application/json)

  • 201 Created
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

Created

{
  "customerId": "2484c7e0-5d18-5830-826f-dce27da82bce"
}
Code copied

Not Found

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

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} endpoint.
  2. Delete the old tax residency. You can do this using the DELETE /customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence} 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.

Add a tax residency to a legal entity customer

put/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}

You can use this endpoint to add or update a legal entity's tax residency entry for the specified country.

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.

  • customerId string, path, Required

    The customer ID of this legal entity.

  • countryOfTaxResidence string, path, Required

    Country of tax residence, given as an ISO 3166-1 three letter country-code.

Request Payload (application/json)

  • taxIdNumber string

    The updated tax identification number for this tax residency.

    Minimum length
    1
  • noTaxIdReason string

    Supported reasons for not having a tax ID. Only required if no tax ID number is provided.

    Enum array
    CountryDoesNotIssue, UnableToObtain, NotRequired

request

{
  "taxIdNumber": "253579115462",
  "noTaxIdReason": "CountryDoesNotIssue"
}
Code copied

Response (application/json)

  • 200 OK
  • 201 Created
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

Created

{
  "customerId": "2484c7e0-5d18-5830-826f-dce27da82bce"
}
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

Unprocessable Content

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

Delete a legal entity's tax residency

delete/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}

You can use this endpoint to remove a legal entity's tax residency entry for the specified country.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The customer ID of this legal entity.

  • countryOfTaxResidence string, path, Required

    Country of tax residence to remove, given as an ISO 3166-1 three letter country-code.

Response (application/json)

  • 204 No Content
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

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

Unprocessable Content

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

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.

Create a company director

post/customers/v2/non-account-holder/directors

You can call this endpoint to create a director and associate it with a legal entity.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

Request Payload (application/json)

  • customerId string, Required

    The ID of the legal entity to link this director to.

  • personalDetails object, Required

    Name and country details for a customer.

request

{
  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  "personalDetails": {
    "firstName": "Nigel",
    "middleName": "Johnson",
    "surname": "Smitty",
    "countryOfResidence": "GBR"
  }
}
Code copied

Response (application/json)

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

Created

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
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

Retrieve a company director

get/customers/v2/customers/{customerId}

You can call this endpoint to retrieve the details of a company director by their customer ID.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The ID of the company director.

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

OK

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49",
  "status": "Active",
  "type": "Director",
  "personalDetails": {
    "firstName": "Nigel",
    "middleName": "Johnson",
    "surname": "Smitty",
    "countryOfResidence": "GBR"
  }
}
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

Update a company director

patch/customers/v2/non-account-holder/directors/{customerId}

You can call this endpoint to update the details of a company director.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The Id of the company director.

Request Payload (application/json)

  • personalDetails object

    Update request for a non-account-holder's personal details limited to name components and country of residence. Null values are ignored.

request

{
  "personalDetails": {
    "firstName": "Reginald",
    "middleName": "John",
    "surname": "Potton",
    "countryOfResidence": "GBR"
  }
}
Code copied

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

OK

{
  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  "personalDetails": {
    "firstName": "Reginald",
    "middleName": "John",
    "surname": "Potton",
    "countryOfResidence": "GBR"
  }
}
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

Unprocessable Content

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

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.

Create a UBO

post/customers/v2/non-account-holder/ubos

You can call this endpoint to add an Ultimate Beneficial Owner (UBO) as a related non-account-holder to an existing legal entity.

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)

  • customerId string, Required

    The ID of the legal entity to link this new UBO to.

  • ownershipPercentage integer, Required

    The ownership percentage the UBO has of the associated legal entity.

  • uboType string, Required

    Used to specify whether you are creating a natural or non-natural UBO.

    Enum array
    NaturalPerson, NonNaturalPerson
  • personalDetails object

    Personal details for a natural person UBO. Must only be provided if the uboType is 'NaturalPerson'.

  • businessDetails object

    Business details for a company UBO. Must only be provided if the uboType is 'NonNaturalPerson'.

request

{
  "customerId": "a52e831a-5203-579f-bd54-fc77842a4d51",
  "ownershipPercentage": 100,
  "uboType": "NaturalPerson",
  "personalDetails": {
    "firstName": "Linn",
    "middleName": "Hernan",
    "surname": "Sanches",
    "countryOfResidence": "GBR",
    "dateOfBirth": "1978-05-22"
  },
  "businessDetails": {
    "registeredName": "Smitty and Co",
    "countryOfRegistration": "GBR"
  }
}
Code copied

Response (application/json)

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

Created

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
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

Retrieve a UBO

get/customers/v2/customers/{customerId}

You can call this endpoint to retrieve a UBO by their customer ID.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The ID of the UBO

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

OK

{
  "type": "UboNatural",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49",
  "status": "Active",
  "personalDetails": {
    "firstName": "Linn",
    "middleName": "Hernan",
    "surname": "Sanches",
    "countryOfResidence": "GBR",
    "dateOfBirth": "1978-05-22"
  },
  "businessDetails": {
    "registeredName": "Smitty and Co",
    "countryOfRegistration": "GBR"
  }
}
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

Update a UBO

patch/customers/v2/non-account-holder/ubos/{customerId}

You can call this endpoint to update an existing Ultimate Beneficial Owner (UBO) of a legal entity.

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.

  • customerId string, path, Required

    The Id of the UBO.

Request Payload (application/json)

  • uboType string, Required

    UBO type enumeration for UBO update.

    Enum array
    NaturalPerson, NonNaturalPerson
  • personalDetails object

    May only be provided if the UBO you are updating is a natural person.

  • businessDetails object

    Business details for a non-natural UBO. Can only be provided if the UBO you are updating is non-natural.

request

{
  "uboType": "NaturalPerson",
  "personalDetails": {
    "firstName": "Lynne",
    "middleName": "Hernandez",
    "surname": "Sanchez",
    "countryOfResidence": "GBR",
    "dateOfBirth": "1978-05-21"
  },
  "businessDetails": {
    "registeredName": "Smitti and Co",
    "countryOfRegistration": "GBR"
  }
}
Code copied

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

OK

{
  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  "personalDetails": {
    "firstName": "Lynne",
    "middleName": "Hernandez",
    "surname": "Sanchez",
    "countryOfResidence": "GBR",
    "dateOfBirth": "1978-05-21"
  },
  "businessDetails": {
    "registeredName": "Smitti and Co",
    "countryOfRegistration": "GBR"
  }
}
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

Unprocessable Content

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

Manage controlling persons

A controlling person is an 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.

Create a controlling person

post/customers/v2/non-account-holder/controlling-persons

You can call this endpoint to create a controlling person to associate with a legal entity.

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)

  • customerId string

    The ID of the legal entity to link the controlling person to.

  • controllingPersonType string, Required

    Types of controlling persons for legal persons and legal arrangements.

    Enum array
    LegalPerson_Ownership, LegalPerson_OtherMeans, LegalPerson_SeniorManagingOfficial, LegalArrangement_Trust_Settlor, LegalArrangement_Trust_Trustee, LegalArrangement_Trust_Protector, LegalArrangement_Trust_Beneficiary, LegalArrangement_Trust_Other, LegalArrangement_Other_SettlorEquivalent, LegalArrangement_Other_TrusteeEquivalent, LegalArrangement_Other_ProtectorEquivalent, LegalArrangement_Other_BeneficiaryEquivalent, LegalArrangement_Other_OtherEquivalent
  • personalDetails object, Required

    Name and date of birth details for a customer.

  • currentAddress object, Required

    The controlling person's current address.

  • taxDetails object, Required

    Tax details for a controlling person.

request

{
  "customerId": "8eb512c1-8327-5565-8ea6-615b5840e851",
  "controllingPersonType": "LegalPerson_Ownership",
  "personalDetails": {
    "firstName": "Po",
    "middleName": "Irvine",
    "surname": "Lemington",
    "dateOfBirth": "1977-04-24"
  },
  "currentAddress": {
    "addressType": "ResidentialAddress",
    "buildingNameNumber": "67A",
    "streetName": "Teal Road",
    "city": "Oldham",
    "county": "Greater Manchester",
    "postalCode": "OL127JQ",
    "country": "GBR",
    "validFrom": "2026-02-13"
  },
  "taxDetails": {
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson",
    "taxResidencies": [
      {
        "countryOfTaxResidence": "GBR",
        "taxIdNumber": "DC775544D",
        "noTaxIdReason": "CountryDoesNotIssue"
      }
    ]
  }
}
Code copied

Response (application/json)

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

Created

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
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

Retrieve a controlling person

get/customers/v2/customers/{customerId}

You can call this endpoint to retrieve a controlling person by their customer ID.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The ID of the controlling person

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

OK

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49",
  "status": "Active",
  "type": "ControllingPerson",
  "taxDetails": {
    "taxResidencies": [
      {
        "countryOfTaxResidence": "GBR",
        "taxIdNumber": "AB224466C",
        "noTaxIdReason": "CountryDoesNotIssue"
      }
    ],
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson"
  },
  "controllingPersonDetails": {
    "controllingPersonType": "LegalPerson_Ownership"
  },
  "personalDetails": {
    "firstName": "Po",
    "middleName": "Irvine",
    "surname": "Lemington",
    "dateOfBirth": "1977-04-24"
  },
  "addresses": {
    "currentAddress": {
      "addressType": "ResidentialAddress",
      "buildingNameNumber": "67A",
      "streetName": "Teal Road",
      "county": "Greater Manchester",
      "city": "Oldham",
      "postalCode": "OL127JQ",
      "country": "GBR",
      "validFrom": "2026-01-22",
      "isCurrentAddress": true
    },
    "previousAddresses": [
      {
        "addressType": "ResidentialAddress",
        "buildingNameNumber": "50",
        "streetName": "Lime Road",
        "county": "Greater Manchester",
        "city": "Oldham",
        "postalCode": "OL127HR",
        "country": "GBR",
        "validFrom": "2020-01-27",
        "validTo": "2026-01-22",
        "isCurrentAddress": false
      }
    ]
  }
}
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

Update a controlling person

patch/customers/v2/non-account-holder/controlling-persons/{customerId}

You can call this endpoint to update the details of a controlling person of a legal entity.

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.

  • customerId string, path, Required

    The Id of the controlling person

Request Payload (application/json)

  • controllingPersonType string

    Types of controlling persons for legal persons and legal arrangements.

    Enum array
    LegalPerson_Ownership, LegalPerson_OtherMeans, LegalPerson_SeniorManagingOfficial, LegalArrangement_Trust_Settlor, LegalArrangement_Trust_Trustee, LegalArrangement_Trust_Protector, LegalArrangement_Trust_Beneficiary, LegalArrangement_Trust_Other, LegalArrangement_Other_SettlorEquivalent, LegalArrangement_Other_TrusteeEquivalent, LegalArrangement_Other_ProtectorEquivalent, LegalArrangement_Other_BeneficiaryEquivalent, LegalArrangement_Other_OtherEquivalent
  • personalDetails object

    Name and date of birth details for a customer update request. Null values are ignored.

  • taxDetails object

    Tax details for the customer.

request

{
  "controllingPersonType": "LegalPerson_Ownership",
  "personalDetails": {
    "firstName": "Poh",
    "middleName": "Irwin",
    "surname": "Stein",
    "dateOfBirth": "1977-04-24"
  },
  "taxDetails": {
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson"
  }
}
Code copied

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

OK

{
  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  "controllingPersonType": "LegalPerson_Ownership",
  "personalDetails": {
    "firstName": "Poh",
    "middleName": "Irwin",
    "surname": "Stein",
    "dateOfBirth": "1977-04-25"
  },
  "taxDetails": {
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson"
  }
}
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

Unprocessable Content

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

Update a controlling person's current address

post/customers/v2/customers/{customerId}/current-addresses

You can call this endpoint to updates a controlling person's current residential address. The previous address is maintained as address history.

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.

  • customerId string, path, Required

    The ID of the controlling person

Request Payload (application/json)

  • addressType string, Required

    Represents the type of address. This will always be 'ResidentialAddress'.

    Enum array
    ResidentialAddress
  • buildingNameNumber string, Required

    The building name/number at this address.

    Minimum length
    1
  • streetName string, Required

    The street name at this address.

    Minimum length
    1
  • city string, Required

    The city at this address.

    Minimum length
    1
  • county string

    The county at this address.

    Minimum length
    1
  • postalCode string, Required

    The postcode at this address.

    Minimum length
    1
  • country string, Required

    3-letter country codes as defined in ISO 3166-1

    Enum array
    AFG, ALB, ATA, DZA, ASM, AND, AGO, ATG, AZE, ARG, AUS, AUT, BHS, BHR, BGD, ARM, BRB, BEL, BMU, BTN, BOL, BIH, BWA, BVT, BRA, BLZ, IOT, SLB, VGB, BRN, BGR, MMR, BDI, BLR, KHM, CMR, CAN, CPV, CYM, CAF, LKA, TCD, CHL, CHN, TWN, CXR, CCK, COL, COM, MYT, COG, COD, COK, CRI, HRV, CUB, CYP, CZE, BEN, DNK, DMA, DOM, ECU, SLV, GNQ, ETH, ERI, EST, FRO, FLK, SGS, FJI, FIN, ALA, FRA, GUF, PYF, ATF, DJI, GAB, GEO, GMB, PSE, DEU, GHA, GIB, KIR, GRC, GRL, GRD, GLP, GUM, GTM, GIN, GUY, HTI, HMD, VAT, HND, HKG, HUN, ISL, IND, IDN, IRN, IRQ, IRL, ISR, ITA, CIV, JAM, JPN, KAZ, JOR, KEN, PRK, KOR, KWT, KGZ, LAO, LBN, LSO, LVA, LBR, LBY, LIE, LTU, LUX, MAC, MDG, MWI, MYS, MDV, MLI, MLT, MTQ, MRT, MUS, MEX, MCO, MNG, MDA, MNE, MSR, MAR, MOZ, OMN, NAM, NRU, NPL, NLD, CUW, ABW, SXM, BES, NCL, VUT, NZL, NIC, NER, NGA, NIU, NFK, NOR, MNP, UMI, FSM, MHL, PLW, PAK, PAN, PNG, PRY, PER, PHL, PCN, POL, PRT, GNB, TLS, PRI, QAT, REU, ROU, RUS, RWA, BLM, SHN, KNA, AIA, LCA, MAF, SPM, VCT, SMR, STP, SAU, SEN, SRB, SYC, SLE, SGP, SVK, VNM, SVN, SOM, ZAF, ZWE, ESP, SSD, SDN, ESH, SUR, SJM, SWZ, SWE, CHE, SYR, TJK, THA, TGO, TKL, TON, TTO, ARE, TUN, TUR, TKM, TCA, TUV, UGA, UKR, MKD, EGY, GBR, GGY, JEY, IMN, TZA, USA, VIR, BFA, URY, UZB, VEN, WLF, WSM, YEM, ZMB
  • validFrom string

    Date from which the address is valid, formatted yyyy-MM-dd. Defaults to today if unspecified.

request

{
  "addressType": "ResidentialAddress",
  "buildingNameNumber": "67A",
  "streetName": "Teal Road",
  "city": "Oldham",
  "county": "Greater Manchester",
  "postalCode": "OL127JQ",
  "country": "GBR",
  "validFrom": "2026-02-13"
}
Code copied

Response (application/json)

  • 201 Created
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

Created

{
  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac"
}
Code copied

Not Found

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

Update a controlling person's tax residency

put/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}

You can call this endpoint to adds or update a controlling person's tax residency entry for the specified country.

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.

  • customerId string, path, Required

    The ID of the controlling person.

  • countryOfTaxResidence string, path, Required

    Country of tax residence, given as an ISO 3166-1 three letter country-code.

Request Payload (application/json)

  • taxIdNumber string

    Tax identification number.

    Minimum length
    1
  • noTaxIdReason string

    The reason no tax ID number could be provided. Only required if taxIdNumber field is not provided.

    Enum array
    CountryDoesNotIssue, UnableToObtain, NotRequired

request

{
  "taxIdNumber": "AB632233A",
  "noTaxIdReason": "CountryDoesNotIssue"
}
Code copied

Response (application/json)

  • 200 OK
  • 201 Created
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

Created

{
  "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac"
}
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

Unprocessable Content

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

Remove a controlling person's current tax residency

delete/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}

You can call this endpoint to removes a controlling person's tax residency entry for the specified country.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The ID of the controlling person.

  • countryOfTaxResidence string, path, Required

    Country of tax residence to remove, given as an ISO 3166-1 three letter country-code.

Response (application/json)

  • 204 No Content
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Content

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

Unprocessable Content

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

Customer relation endpoints

The POST /customers/v2/customers/{customerId}/related-parties 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.

To remove a relation between two parties, you can use the DELETE /customers/v2/customers/{customerId}/related-parties/{relatedCustomerId} using the customerId of each party.

Relate a legal entity and another customer

post/customers/v2/customers/{customerId}/related-parties

You can call this endpoint to add a relation between an existing party and a legal entity.

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.

  • customerId string, path, Required

    The ID of the customer

Request Payload (application/json)

  • relatedCustomerId string, Required

    The ID of the customer to be linked to the customer in the path as a related party.

  • relatedPartyType string, Required

    Possible related party types.

    Enum array
    Director, UBO, ControllingPerson
  • ownershipPercentage integer

    The ownership percentage of the related party. Optional: applies only to certain related party types.

request

{
  "relatedCustomerId": "c4bac97f-a6d3-5d53-97e6-26fda428f79e",
  "relatedPartyType": "UBO",
  "ownershipPercentage": 100
}
Code copied

Response (application/json)

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

Created

{
  "customerId": "4639bbcf-07e0-5163-ae4a-f2808f5497ea",
  "relatedCustomerId": "c4bac97f-a6d3-5d53-97e6-26fda428f79e"
}
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

Get all relations of a legal entity

get/customers/v2/customers/{customerId}/related-parties

You can call this endpoint to retrieve details of any related parties to a customer by their customer ID.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The customer ID of the legal entity

Response (application/json)

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

OK

{
  "value": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "UBO",
      "ownershipPercentage": 100
    }
  ]
}
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

Delete a relation between two customers

delete/customers/v2/customers/{customerId}/related-parties/{relatedCustomerId}/{relatedPartyType}

You can call this endpoint to removes a related party link between two customers.

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.

  • X-Request-Time string, header, Required

    The current UNIX timestamp in seconds. This value will be rejected if it is more than 60 seconds late.

  • customerId string, path, Required

    The ID of the original customer.

  • relatedCustomerId string, path, Required

    The ID of the related customer to unlink. This is the customer that holds the relation type. For example, 'UBO'.

  • relatedPartyType string, path, Required

    The type of related party. Used to disambiguate where a party is related in more than one way.

Response (application/json)

  • 204 No Content
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 422 Unprocessable Content

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