ClearBank Retail Embedded Banking Customers API
Embedded Banking APIs to create and manage retail customers, hub and payment accounts, savings, and ISAs on ClearBank's banking infrastructure.
OpenAPI Specification
{
"openapi": "3.0.2",
"info": {
"title": "ClearBank Retail Customer V2 APIs",
"contact": {
"name": "API Support",
"url": "https://clear.bank",
"email": "fiapisupport@clear.bank"
},
"version": "2.0-customers-retail"
},
"paths": {
"/customers/v2/customers/{customerId}": {
"get": {
"tags": [
"Customer"
],
"summary": "Retrieves a customer by their customer ID.",
"operationId": "V2CustomerGet",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetailCustomerGetResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/customers/v2/customers/{customerId}/related-parties": {
"get": {
"tags": [
"Customer"
],
"summary": "Retrieves the related party data of a customer by their customer ID.",
"operationId": "V2RelatedPartiesGet",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the original customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value":{
"type": "array",
"items": {
"$ref": "#/components/schemas/RelatedPartyGetResponse"
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
},
"post": {
"tags": [
"Customer"
],
"summary": "Adds a new related party to an existing customer. Note that relationships must be unique: if a relationship already exists that links the same two customers with the same relationship type, your request will be rejected.",
"operationId": "V2RelatedPartyPost",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the original customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "Information required to add related party to customer.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateRelatedPartyRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatedRelatedPartyResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/customers/v2/customers/{customerId}/current-addresses": {
"post": {
"tags": [
"Customer"
],
"summary": "Updates a customer's current address while maintaining their previous addresses history.",
"operationId": "V2CustomersCurrentAddressPost",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "Information required to update the customer's address",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CurrentAddressRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerSubresourceCreatedResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/customers/v2/customers/{customerId}/related-parties/{relatedCustomerId}/{relatedPartyType}": {
"delete": {
"tags": [
"Customer"
],
"summary": "Removes a related party link between two customers.",
"operationId": "V2RelatedPartyDelete",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "relatedCustomerId",
"in": "path",
"description": "The ID of the related customer to unlink.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "relatedPartyType",
"in": "path",
"description": "The type of related party. Used to disambiguate where a party is related in more than one way.",
"required": true,
"schema": {
"$ref": "#/components/schemas/RelatedPartyType"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/customers/v2/customers/{customerId}/identity-documents/{idCountryOfIssue}-{idType}": {
"put": {
"tags": [
"Customer"
],
"summary": "Adds or updates a customer's identity document. Returns 200 OK when updating an existing ID, or 201 Created when adding a new ID.",
"operationId": "V2CustomerIdentityDocumentPut",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "idCountryOfIssue",
"in": "path",
"description": "Country of issue.",
"required": true,
"schema": {
"$ref": "#/components/schemas/CountryCode"
}
},
{
"name": "idType",
"in": "path",
"description": "Type of identity document.",
"required": true,
"schema": {
"$ref": "#/components/schemas/IdType"
}
}
],
"requestBody": {
"description": "The updated details of the identity document.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateIdentityDocumentRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerSubresourceCreatedResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
},
"delete": {
"tags": [
"Customer"
],
"summary": "Removes a customer's identity document.",
"operationId": "V2CustomerIdentityDocumentDelete",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "idCountryOfIssue",
"in": "path",
"description": "Country of issue.",
"required": true,
"schema": {
"$ref": "#/components/schemas/CountryCode"
}
},
{
"name": "idType",
"in": "path",
"description": "Type of identity document.",
"required": true,
"schema": {
"$ref": "#/components/schemas/IdType"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/customers/v2/customers/{customerId}/tax-residencies/{countryOfTaxResidence}": {
"put": {
"tags": [
"Customer"
],
"summary": "Adds or updates a customer's tax residency entry for the specified country. Returns 200 OK when updating an existing tax residency, or 201 Created when adding a new tax residency.",
"operationId": "V2CustomerTaxResidencyPut",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "countryOfTaxResidence",
"in": "path",
"description": "Country of tax residence.",
"required": true,
"schema": {
"$ref": "#/components/schemas/CountryCode"
}
}
],
"requestBody": {
"description": "Tax residency details (TIN or reason for no TIN).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTaxResidencyRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerSubresourceCreatedResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
},
"delete": {
"tags": [
"Customer"
],
"summary": "Removes a customer's tax residency entry for the specified country.",
"operationId": "V2CustomerTaxResidencyDelete",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "countryOfTaxResidence",
"in": "path",
"description": "Country of tax residence to remove.",
"required": true,
"schema": {
"$ref": "#/components/schemas/CountryCode"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/customers/v2/retail": {
"post": {
"tags": [
"Retail"
],
"summary": "Requests creation of retail customer. On a success, you will receive a customer ID which you can then use to create accounts for this customer.",
"operationId": "V2RetailPost",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Your API token, retrieved from the web portal.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "DigitalSignature",
"in": "header",
"description": "Signed hash of the body of the request. The hash is signed by your private key.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Request-Id",
"in": "header",
"description": "A unique identifier for the request.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Information required to create retail customer.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateRetailRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatedResourceResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
},
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clearbank/refs/heads/main/openapi/clearbank-customers_v2_retail.json