Onboard new Sole Traders

Note for AI agents and automated readers

This page is rendered from source files in a public GitHub repository. Much of the technical content — API request and response schemas, examples, and webhook payloads — is collapsed behind interactive dropdowns and may be missing or incomplete in this rendered HTML. For complete, machine-readable content, do not rely on this page: read the raw source files directly instead.

Machine-readable index of every source file: /llms.txt
Repository (branch main): https://github.com/clearbank/clearbank.github.io
Documentation pages (Markdown/MDX): https://github.com/clearbank/clearbank.github.io/tree/main/content
API endpoint schemas (OpenAPI JSON): https://github.com/clearbank/clearbank.github.io/tree/main/data/endpoints
Webhook payload schemas (MDX): https://github.com/clearbank/clearbank.github.io/tree/main/data/webhooks
Raw source for this page: https://raw.githubusercontent.com/clearbank/clearbank.github.io/main/content/uk/docs/embedded-banking/business/onboard-sole-traders.mdx

Every sole trader needs a CustomerId before they can be given access to our products, such as accounts. How you get one depends on who carries out the due diligence checks:

ClearBank carries out the checks. Use our customer due diligence endpoint and webhooks to onboard the sole trader with our due diligence checks included. We'll create the customer if the checks pass.
You carry out the checks. You can then create the sole trader directly, your request should include the outcomes of your checks. No ClearBank checks are performed.

To retrieve and manage a sole trader's details once they exist, use their CustomerId with our sole trader endpoints.

Our sole trader onboarding endpoint lets you onboard new sole traders as business customers in a single request. Share information about the sole trader and their business, and we'll handle the rest. When onboarding is complete, you'll receive a CustomerId for the new customer.

Every onboarding application includes our Know Your Business (KYB) due diligence checks. These checks can pass or fail, and we'll tell you the outcome by webhook. If the checks pass, we'll create the sole trader customer for you. If they fail, no customer is created. We may also need more information from the sole trader before we can complete our checks.

If you'd like to use this product, please speak with your Client Director.

Onboard a new sole trader customer

post/customer-due-diligence/v1/sole-trader/onboard

Use this endpoint to onboard a new sole trader customer. Onboarding includes our due diligence checks, and we'll send you the outcome by webhook. If onboarding is successful, we'll create the sole trader customer and send you their customer ID.

Parameters

Authorization string, header, Required
Your API token, retrieved from the ClearBank 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; valid for 24 hours, max length 83.

Request Payload (application/json)

soleTraderData object, Required

request

{
  "soleTraderData": {
    "businessName": {
      "tradingName": "Smith Consulting"
    },
    "address": {
      "residentialAddress": {
        "buildingNameNumber": "42",
        "streetName": "Baker Street",
        "city": "London",
        "county": "Greater London",
        "postalCode": "NW1 6XE",
        "countryCode": "GBR"
      },
      "tradingAddress": {
        "buildingNameNumber": "42",
        "streetName": "Baker Street",
        "city": "London",
        "county": "Greater London",
        "postalCode": "NW1 6XE",
        "countryCode": "GBR"
      }
    },
    "sicCode": [
      "62020"
    ],
    "industryClassification": "_6E_OtherConstructionActivities",
    "incorporationDate": "2019-06-01",
    "annualRevenue": 120000,
    "sourceOfFunds": "Business Revenue",
    "tax": {
      "validSelfCertification": true,
      "vatRegistrationNumber": "GB987654321",
      "taxResidency": [
        "GBR"
      ]
    },
    "name": {
      "firstName": "John",
      "middleName": "William",
      "surname": "Smith"
    },
    "dateOfBirth": "1985-06-20",
    "nationalities": [
      "GBR"
    ],
    "countryOfOperations": "GBR",
    "nationalInsuranceNumber": "AB123456C",
    "email": "john.smith@smithconsulting.co.uk",
    "mobile": "00447700900123"
  }
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request

Accepted

{
  "applicationId": "2d185f64-5717-4562-b3fc-2c963e23afa6"
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Sole Trader Application Successful webhook
Sole Trader Application Declined webhook
Sole Trader Additional Info Required webhook

This webhook confirms that our due diligence checks for an onboarding application have succeeded, and that a sole trader customer has been created.

Request body

{
    "Type": "Customer.SoleTrader.ApplicationSuccessful",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload fields

Field	Type	Format	Required	Min-Max length	Pattern	Description
`ApplicationId`	string	uuid	Yes	36-36	`^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`	A randomly generated GUID that uniquely identifies the sole trader application request and its associated webhook response.
`CustomerId`	string	uuid	Yes	36-36	`^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`	The unique identifier of the created customer. Always present.
`KybStatus`	string	-	Yes	-	-	Always `Pass`. Indicates the outcome of our due diligence checks.

Example Sole Trader Application Successful webhook request body

{
    "Type": "Customer.SoleTrader.ApplicationSuccessful",
    "Version": 1,
    "Payload": {
        "ApplicationId": "aac7c700-1ea6-5664-8804-ceeb066d3cf5",
        "CustomerId": "a1e22390-9049-53f4-a598-de39856bdb50",
        "KybStatus": "Pass"
    },
    "Nonce": 747000128
}

Example webhook response

{
    "Nonce": 747000128
}

This webhook notifies that additional information is required before the sole trader's application can be processed. It includes a RequiredActions array which lists the type of information required and the URLs at which each action can be completed.

Request body

{
    "Type": "Customer.SoleTrader.AdditionalInfoRequired",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload fields

Field	Type	Format	Required	Min-Max length	Pattern	Description
`ApplicationId`	string	uuid	Yes	36-36	`^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`	A randomly generated GUID that uniquely identifies the sole trader application request and its associated webhook response.
`KybStatus`	string	-	Yes	-	-	Always `Pending`. Indicates the outcome of our due diligence checks.
`RequiredActions`	array	-	Yes	-	-	List of actions that must be completed to progress the onboarding application. See `RequiredAction`.

RequiredAction (RequiredActions)

Field	Type	Format	Required	Description
`action`	string	-	Yes	The specific action required, for example, upload identification documents.
`url`	string	uri	Yes	The URL where the required action can be performed.

Example Sole Trader Additional Info Required webhook request body

{
    "Type": "Customer.SoleTrader.AdditionalInfoRequired",
    "Version": 1,
    "Payload": {
        "ApplicationId": "aac7c700-1ea6-5664-8804-ceeb066d3cf5",
        "KybStatus": "Pending",
        "RequiredActions": [
            {"action": "CustomerIdentificationDocumentUpload", "url": "https://kybchecker.com/?sessionId=123"}
        ]
    },
    "Nonce": 332172156
}

Example webhook response

{
    "Nonce": 332172156
}

This webhook confirms an onboarding application has failed our due diligence checks, and this sole trader customer cannot be created.

Request body

{
    "Type": "Customer.SoleTrader.ApplicationDeclined",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload fields

Field	Type	Format	Required	Min-Max length	Pattern	Description
`ApplicationId`	string	uuid	Yes	36-36	`^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`	A randomly generated GUID that uniquely identifies the sole trader application request and its associated webhook response.
`KybStatus`	string	-	Yes	-	-	Always `Fail`. Indicates the outcome of our due diligence checks.

Example Sole Trader Application Declined webhook request body

{
    "Type": "Customer.SoleTrader.ApplicationDeclined",
    "Version": 1,
    "Payload": {
        "ApplicationId": "aac7c700-1ea6-5664-8804-ceeb066d3cf5",
        "KybStatus": "Fail"
    },
    "Nonce": 333372156
}

Example webhook response

{
    "Nonce": 333372156
}

You can simulate successful, declined and additional information onboarding webhooks in our simulation environment.
To do this, call the POST /customer-due-diligence/v1/sole-trader/onboard endpoint with the soleTraderData.name.surname property set to:

"pass" to simulate checks passing, and receive a Sole Trader Application Successful webhook.
"fail" to simulate checks failing, and receive a Sole Trader Application Declined webhook.
"info" to simulate checks requiring additional information, and receive a Sole Trader Additional Info Required webhook.

If you conduct your own due diligence checks on a sole trader, you can create them directly. No ClearBank due diligence checks are performed, so you must supply the outcomes of your own checks in the request. The kycAml object, taxDetails (including at least one tax residency), personalDetails, businessDetails, businessClassification and addressHistory are all required. The data required to register a sole trader is a combination of fields associated with both legal entities (incorporated businesses) and retail customers. This is because a sole trader is simultaneously an individual and a business. For example: a sole trader has both an individual's personal details - such as a firstName, and details of their business such as a tradingName.

In addition to a sole trader's personal details, you can provide information about their business. This includes their tradingName, annualRevenue, and businessClassification.

A sole trader can use their personal name as their tradingName, or instead pick a business name. Guidance on acceptable business names for sole traders can be found on the gov.uk website.

The annualRevenue you provide for a sole trader 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 sole trader. Their businessClassification.sectorCode should always be _8b_UnincorporatedBusinessesOtherThanLLPs, while their industryClassification should be the option that most closely fits their business.

When you create a sole trader, you'll need to provide the outcomes of any KYC and AML checks you conduct on them. You can record these outcomes using the kycAml object. Guidance for each of the object's properties are listed below:

sanctions - If your KYC checks identify the customer as sanctioned, set to true.
pep - If your checks identify the customer as a Politically Exposed Person (PEP), set to Yes_Domestic or Yes_International accordingly - otherwise set to No.
rca - If your checks identify the customer as a Relative or Close Associate (RCA) of a PEP, set to Yes_Domestic or Yes_International accordingly - otherwise set to No.
craRating - Use this field to declare a Customer Risk Assessment rating for the customer. There are four tiers of risk: Low, Medium, High, and Very_High.

If you have new KYC or AML outcomes for a customer, you can update these using the PATCH /customers/v2/sole-traders/{customerId} endpoint.

When you create a sole trader, you'll also need to provide their current residential and/or trading address in the addressHistory.currentAddresses array. You can optionally record their previous address history using the addressHistory.previousAddresses array.

Create a sole trader

post/customers/v2/sole-traders

You can use this endpoint to create a new sole trader 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)

addressHistory object, Required
The customer's address history where they have multiple current addresses. For example, a trading address and a residential address.
personalDetails object, Required
Personal details for the customer.
identityDocuments array
The customer's identity documents.
businessDetails object, Required
Request to create business details.
businessClassification object, Required
Request to create a business classification.
kycAml object, Required
KYC/AML information for the customer.
taxDetails object, Required
Tax details for a sole trader customer.
specialStatuses array
The customer's special statuses, if any. Possible values include: 'Vulnerability_Health_VisualImpairmentBraille', 'Vulnerability_Health_VisualImpairmentLargeText', 'Vulnerability_Health_AudioImpairment', 'Vulnerability_Health_Other', 'Vulnerability_LifeEvents', 'Vulnerability_Resilience', and 'Vulnerability_Capability'

request

{
  "addressHistory": {
    "currentAddresses": [
      {
        "addressType": "TradingAddress",
        "buildingName": "Grayston House",
        "buildingNumber": "21",
        "subBuilding": "Flat 9",
        "streetName": "Long Road",
        "city": "Cyan City",
        "county": "Greenshire",
        "postalCode": "PG15 8AB",
        "country": "GBR",
        "validFrom": "2022-05-15"
      }
    ],
    "previousAddresses": [
      {
        "addressType": "TradingAddress",
        "buildingName": "Grayston House",
        "buildingNumber": "21",
        "subBuilding": "Flat 9",
        "streetName": "Short Road",
        "city": "Blue City",
        "county": "Redshire",
        "postalCode": "BC2 6YM",
        "country": "GBR",
        "validFrom": "2016-06-22",
        "validTo": "2022-05-15"
      }
    ]
  },
  "personalDetails": {
    "firstName": "Karol",
    "middleName": "Henryk",
    "surname": "Agrowicz",
    "email": "krl@workaholicmail.com",
    "telephone": "00447653589772",
    "countryOfResidence": "GBR",
    "dateOfBirth": "1988-05-21",
    "nationalIdentificationNumber": "PC112233D"
  },
  "identityDocuments": [
    {
      "idCountryOfIssue": "GBR",
      "idType": "Passport",
      "idNumber": "178087840846",
      "idExpiryDate": "2030-05-21"
    }
  ],
  "businessDetails": {
    "tradingName": "Build It Solutions",
    "annualRevenue": 37000
  },
  "businessClassification": {
    "sectorCode": "_8b_UnincorporatedBusinessesOtherThanLLPs",
    "industryClassification": "_6C_ConstructionOfDomesticBuildings"
  },
  "kycAml": {
    "sanctions": true,
    "pep": "No",
    "rca": "No",
    "craRating": "LowRisk"
  },
  "taxDetails": {
    "validSelfCertification": true,
    "usPerson": "NotAUSPerson",
    "taxResidencies": [
      {
        "countryOfTaxResidence": "GBR",
        "taxIdNumber": "PC556498D",
        "noTaxIdReason": "CountryDoesNotIssue"
      }
    ],
    "vatRegistrationNumber": "GB123456789"
  },
  "specialStatuses": [
    "Vulnerability_LifeEvents"
  ]
}

Code copied

Response (application/json)

201 Created
400 Bad Request
403 Forbidden
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

Unprocessable Content

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

Code copied

API

GBP Accounts

GBP Payments

Multi-currency, FX, & SCT UK

Embedded Banking

Onboard new Sole Traders

Sole trader onboarding

Onboard with ClearBank's due diligence

Message flow diagrams

Onboard a new sole trader customer

Parameters

Request Payload (application/json)

request

Response (application/json)

Accepted

Bad Request

Associated Webhooks

Webhooks

Simulating onboarding webhooks

Create a sole trader with your own due diligence

Business information

Know Your Customer (KYC) and Anti-Money Laundering (AML) fields

Addresses

Create a sole trader

Parameters

Request Payload (application/json)

request

Response (application/json)

Created

Bad Request

Unprocessable Content