ClearBank Customer Due Diligence (KYC) API
Know Your Customer / Customer Due Diligence checks for onboarding and verifying customers within embedded and agency banking propositions.
OpenAPI Specification
{
"openapi": "3.0.2",
"info": {
"title": "Customer Due Diligence API",
"version": "1.0know-your-customer"
},
"paths": {
"/customer-due-diligence/v1/retail/onboard": {
"post": {
"description": "Use this endpoint to conduct KYC checks for a new retail customer. If the checks pass, the provided details are then used to create a new retail customer.",
"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": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetailCustomerCheckRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RetailCustomerCheckRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RetailCustomerCheckRequest"
}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/RetailCustomerCheckResponse"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetailCustomerCheckResponse"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RetailCustomerCheckResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Address": {
"required": [
"countryCode",
"postalCode",
"streetName"
],
"anyOf": [
{
"required": [
"buildingName"
]
},
{
"required": [
"buildingNumber"
]
}
],
"type": "object",
"properties": {
"buildingName": {
"maxLength": 255,
"pattern": "^(?=.*[a-zA-Z0-9])[a-zA-Z0-9 ,.'()\\-]+$",
"type": "string",
"nullable": true,
"example": null,
"description": "The building's name at this address. You must provide either this and/or a buildingNumber."
},
"buildingNumber": {
"maxLength": 255,
"pattern": "^(?=.*[a-zA-Z0-9])[a-zA-Z0-9 ,.'()\\-]+$",
"type": "string",
"nullable": true,
"example": "270",
"description": "The building's number at this address. You must provide either this and/or a buildingName."
},
"subBuilding": {
"maxLength": 255,
"pattern": "^(?=.*[a-zA-Z0-9])[a-zA-Z0-9 ,.'()\\-]+$",
"type": "string",
"nullable": true,
"example": null,
"description": "Details of the sub-building at this address, such as an annexe, apartment, or flat."
},
"streetName": {
"maxLength": 50,
"minLength": 1,
"pattern": "^[a-zA-Z0-9\\-',.() ]+$",
"type": "string",
"example": "Long Road",
"description": "The street of the customer's address."
},
"city": {
"maxLength": 40,
"pattern": "^[a-zA-Z0-9\\-',.() ]+$",
"type": "string",
"nullable": true,
"example": "York",
"description": "The postal city of the customer's address."
},
"county": {
"maxLength": 40,
"pattern": "^[a-zA-Z0-9\\-',.() ]+$",
"type": "string",
"nullable": true,
"example": "Yorkshire",
"description": "The county of the customer's address."
},
"postalCode": {
"maxLength": 10,
"minLength": 2,
"pattern": "^([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9]?[A-Za-z])))) [0-9][A-Za-z]{2})$",
"type": "string",
"example": "YO31 7UH",
"description": "The postal code of the customer's address. This must be formatted as a UK postcode, including the appropriate use of whitespace."
},
"countryCode": {
"$ref": "#/components/schemas/CountryCode",
"description": "The country of the customer's address, represented as an ISO 3166 Alpha-3 country-code."
}
},
"additionalProperties": false
},
"CountryCode": {
"format": "ISO 3166 Alpha-3 country-code",
"type": "string",
"example": "GBR"
},
"CustomerData": {
"required": [
"currentAddress",
"dateOfBirth",
"email",
"name",
"nationalInsuranceNumber",
"nationality",
"taxResidency"
],
"type": "object",
"properties": {
"name": {
"$ref": "#/components/schemas/PersonName",
"description": "The customer's full name. Their first name and surname are required."
},
"dateOfBirth": {
"type": "string",
"format": "date",
"example": "1976-01-26",
"maxLength": 10,
"description": "The customer's date of birth, formatted: yyyy-MM-dd."
},
"nationality": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/CountryCode"
},
"description": "An array containing the customer's nationalities as ISO 3166 Alpha-3 country-codes. You can provide multiple values for customers with more than one nationality. Does not accept US nationals.",
"example": ["GBR", "IRL"]
},
"taxResidency": {
"minItems": 1,
"maxItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/CountryCode"
},
"description": "An array containing the country the customer resides in for tax purposes, represented as an ISO 3166 Alpha-3 country-code. Currently does not accept more than one country.",
"example": ["GBR"]
},
"nationalInsuranceNumber": {
"minLength": 9,
"maxLength": 9,
"pattern": "^[a-zA-Z]{2}\\d{6}[a-zA-Z]$",
"example": "AB112233C",
"type": "string",
"description": "The UK National Insurance (NI) number of the customer. Should not include whitespace."
},
"email": {
"type": "string",
"format": "email",
"example": "example@emailprovider.co.uk",
"description": "The customer's email address."
},
"mobile": {
"pattern": "^(?:[+][1-9])?\\d{11,14}$",
"type": "string",
"nullable": true,
"description": "The customer's international mobile number, including its country-code prefix. For example '+44' for UK numbers. The use of '+' is optional.",
"example": "+447725666777"
},
"currentAddress": {
"$ref": "#/components/schemas/Address",
"description": "The customer's current residential address."
},
"idvEmailsEnabled": {
"type": "boolean",
"default": true,
"description": "If set to false, you'll receive Additional Info Required webhooks."
}
},
"additionalProperties": false
},
"PersonName": {
"required": [
"firstName",
"surname"
],
"type": "object",
"properties": {
"firstName": {
"maxLength": 40,
"minLength": 1,
"pattern": "^[a-zA-Z.'\\- ]+$",
"type": "string",
"example": "Adrien"
},
"middleName": {
"maxLength": 100,
"pattern": "^[a-zA-Z.'\\- ]+$",
"type": "string",
"nullable": true,
"example": "Edin"
},
"surname": {
"maxLength": 40,
"minLength": 1,
"pattern": "^[a-zA-Z.'\\- ]+$",
"type": "string",
"example": "Reed-Myers"
}
},
"additionalProperties": false
},
"ProblemDetails": {
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "A URI reference [RFC3986] that identifies a problem type. When dereferenced, it provides a human-readable documentation for the problem type. When not present, default value is assumed to be 'about:blank'."
},
"title": {
"type": "string",
"nullable": true,
"description": "A short, human-readable summary of the problem type."
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true,
"description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem."
},
"detail": {
"type": "string",
"nullable": true,
"description": "A human-readable explanation of what went wrong. It can include specifics about the issue, missing parameters, or invalid data."
},
"instance": {
"type": "string",
"nullable": true,
"description": "A URL reference to a retrieve more information about the error, if available."
}
},
"additionalProperties": {}
},
"RetailCustomerCheckRequest": {
"required": [
"customerData"
],
"type": "object",
"properties": {
"customerData": {
"$ref": "#/components/schemas/CustomerData"
}
},
"additionalProperties": false
},
"RetailCustomerCheckResponse": {
"type": "object",
"properties": {
"applicationId": {
"type": "string",
"format": "uuid",
"example": "aac7c700-1ea6-5664-8804-ceeb066d3cf5",
"description": "A unique ID for each submitted application. Use this to identify which application a corresponding webhook pertains to."
}
},
"additionalProperties": false
},
"ValidationProblemDetails": {
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"nullable": true
}
},
"additionalProperties": { }
}
}
}
}