Required Parameters

The following guide includes the details that are required when creating a customer using the Create Customer v5 request, along with validation rules and sample requests.

Use this request to create customers to onboard in United Kingdom. The endpoint accepts both individual and corporate customer.

For a breakdown of the request and parameters, see Onboard Corporate Customer.

For onboarding steps, see UK Onboarding. For document requirements, see UK Required Documents.

Endpoint URL

POST /api/v5/client/{clientHashId}/customers

Path parameters

Parameter	Type	Required	Description
clientHashId	string	Yes	Unique client identifier, generated and shared before the API handshake.

Body parameters

Parameter	Type	Required	Accepted Values / Notes
type	string	Yes	individual or corporate.
kycType	string	Yes	minimum or full. Use full when onboarding for payouts.
region	string	Yes	Use UK.
externalId	string	Optional	Client-defined unique ID. Returned in webhooks and GET APIs.

Individual customers

Individual customers in the UK complete electronic KYC through the Pre-built KYC form.

Personal information

Field	Type	Required	Notes
firstName	string	Yes	Max 40.
middleName	string	Optional	Max 40.
lastName	string	Yes	Max 40.
email	string	Yes	Max 60; must match the valid email format.
nationality	enum	Yes	Category: countryName.
mobile	numeric/string	Yes	Without country code; max 15 digits.
mobileCountryCode	numeric/string	Yes	Max 6 digits.
dateOfBirth	date	Yes	YYYY-MM-DD; age must be 18 or older.
isPep	boolean	Yes	true if PEP.

Billing address

Field	Type	Required	Notes
addressLine1	string	Yes	Max 100.
addressLine2	string	Optional	Max 100.
city	string	Yes	Max 50.
state	enum/string	Conditional	Category: state. Optional if not applicable for the country.
postcode	string	Yes	Max 10.
country	enum	Yes	Category: countryName.

Expected account usage

Field	Required	Notes
credit.monthlyTransactionVolume	Yes	Category: monthlyTransactionVolume.
credit.topTransactionCountries	Yes	Category: countryName.
debit.monthlyTransactionVolume	Yes	Category: monthlyTransactionVolume.
debit.topTransactionCountries	Yes	Destination countries for payouts.
intendedUses	Yes	Category: intendedUseOfAccount.
intendedUsesDescription	Conditional	Required if Other is selected. Max 300 chars.

Bank account details

Use these details for refunds and returns.

Field	Type	Required	Notes
accountName	string	Yes	Registered bank account name; max 140.
accountNumber	string	Yes	Max 35.
bankCountry	string	Yes	ISO 3166-1 alpha-2.
bankAccountType	string	Conditional	For example, savings, checking, or current.
bankName	string	Conditional	Max 255.
currency	string	Yes	ISO 4217.
routingCodes.type	string	Yes	For example, SWIFT, SORT_CODE, or other supported value.
routingCodes.value	string	Yes	Must match the selected routing code type.

Corporate customers (Full KYC)

Business information

Field	Type	Required	Notes
businessType	enum	Yes	Category: businessType.
businessName	string	Yes	Max 80.
tradeName	string	Optional	If not available, use the registered business name.
businessRegistrationNumber	string	Yes	Max 30.
registeredDate	date	Yes	YYYY-MM-DD; must be a past date.
registeredCountry	enum	Yes	Category: countryName.
website	string	Optional	URL or verified social profile. If omitted, upload PROOF_OF_BUSINESS.
isMultiLayeredCompany	boolean	Yes	true or false. Upload CORPORATE_STRUCTURE when true.
searchId	string	Conditional	Include when using the Fetch Exhaustive Corporate Details request. If omitted, the application follows the manual KYB flow.

Applicant declaration

These fields are required before you submit the onboarding request.

Field	Type	Required	Notes
applicantDeclaration	boolean	Yes	Must be true after the applicant accepts the declaration.
applicantDeclarationTimestamp	timestamp	Yes	Format: YYYY-MM-DD HH:MM:SS.

Applicant details

Field	Type	Required	Notes
firstName	string	Yes	Max 40.
middleName	string	Optional	Max 40.
lastName	string	Yes	Max 40.
dateOfBirth	date	Yes	YYYY-MM-DD; age must be 18 or older.
email	string	Yes	Max 60; valid email.
mobile	string	Yes	Max 15 digits.
mobileCountryCode	string	Yes	Max 6 digits.
nationality	enum	Yes	Category: countryName.
isPep	boolean	Yes	true if PEP.
sharePercentage	numeric	Conditional	Required if the applicant is also a shareholder or UBO.
address	object	Yes	Full residential address.
positions	array	Yes	Include all applicable roles such as DIRECTOR, REPRESENTATIVE, UBO, PARTNER, or TRUSTEE.
documents	array	Conditional	Include POWER_OF_ATTORNEY if the applicant is not a director or otherwise not authorized by role. Include SOURCE_OF_WEALTH when isPep = true.

Registered and business addresses

Field	Type	Required	Notes
addresses.registeredAddress.addressLine1	string	Yes	Max 100.
addresses.registeredAddress.addressLine2	string	Optional	Max 100.
addresses.registeredAddress.city	string	Yes	Max 50.
addresses.registeredAddress.state	enum/string	Conditional	Category: state. Optional if not applicable.
addresses.registeredAddress.postcode	string	Yes	Max 10.
addresses.registeredAddress.country	enum	Yes	Category: countryName.
addresses.isBusinessAddressSameAsRegisteredAddress	boolean	Yes	true or false.
addresses.businessAddress	object	Conditional	Required when the business address is different from the registered address.

Stakeholders

Stakeholders can be individuals or corporates with roles such as UBO, Director, Partner, Trustee, Shareholder, or CONTROL_PRONG.

Individual stakeholders

Field	Required	Notes
firstName, lastName, dateOfBirth, nationality	Yes	Personal details.
email, mobile, mobileCountryCode	Yes	Contact details used for KYC.
isPep	Yes	true if PEP.
positions	Yes	Include all applicable roles.
sharePercentage	Conditional	Required when ownership is declared.
address	Yes	Full residential address.
documents	Conditional	Used for manual KYC or when additional supporting documents are required.

Corporate stakeholders

Field	Required	Notes
businessName	Yes	Registered business name.
businessRegistrationNumber	Yes	Max 30.
registeredCountry	Yes	Category: countryName.
positions.title	Yes	For example, UBO, Shareholder, or Trustee.
sharePercentage	Conditional	Required for ownership-based roles.

Nature of business

Field	Required	Notes
operatingCountries	Yes	All countries where the business operates.
industryCodes	Yes	Category: industrySector. Multiple values allowed.
industryDescription	Conditional	Required when Other is selected or when Compliance requests more detail.

Expected account usage (Corporate)

Field	Required	Notes
credit.monthlyTransactionVolume	Yes	Estimated total payins.
credit.monthlyTransactions	Yes	Estimated count of monthly payins.
credit.averageTransactionValue	Yes	Average payin value.
credit.topTransactionCountries	Yes	Origin countries.
credit.topRemitters	Yes	Up to 20 primary remitters.
debit.monthlyTransactionVolume	Yes	Estimated total payouts.
debit.monthlyTransactions	Yes	Estimated count of monthly payouts.
debit.averageTransactionValue	Yes	Average payout value.
debit.topTransactionCountries	Yes	Destination countries.
debit.topBeneficiaries	Yes	Up to 20 primary beneficiaries.
intendedUses	Yes	Category: intendedUseOfAccount.
intendedUsesDescription	Conditional	Required if Other is selected.

Size of business

Field	Required	Notes
totalEmployees	Yes	Category: totalEmployees.
annualTurnover	Yes	Category: annualTurnover. If the business is less than one year old, provide expected turnover.

Device details

Field	Type	Required	Notes
ipCountryCode	enum	Yes	Country of origin of the IP; category: countryName.
deviceInfo	string	Yes	OS or device information for the request.
ipAddress	string	Yes	Valid IPv4 or IPv6 address.
sessionId	string	Yes	Session identifier for the request.

Tags

Field	Type	Required	Notes
tags	array/object	Optional	Up to 15 client-defined key/value pairs.
tags.key	string	Optional	Max 128; keys must be unique.
tags.value	string	Optional	Max 255.

Examples

Corporate customer — request

{
  "type": "corporate",
  "kycType": "full",
  "region": "UK",
  "externalId": "corp-uk-001",
  "businessType": "corporation",
  "businessName": "Example UK Ltd",
  "tradeName": "Example UK",
  "businessRegistrationNumber": "12345678",
  "registeredDate": "2022-03-14",
  "registeredCountry": "GB",
  "website": "https://example.co.uk",
  "isMultiLayeredCompany": false,
  "searchId": "search_123456",
  "applicantDeclaration": true,
  "applicantDeclarationTimestamp": "2026-03-18 10:15:00",
  "addresses": {
    "isBusinessAddressSameAsRegisteredAddress": true,
    "registeredAddress": {
      "addressLine1": "10 Example Street",
      "addressLine2": "",
      "city": "London",
      "state": "",
      "postcode": "EC1A 1AA",
      "country": "GB"
    }
  },
  "applicant": {
    "firstName": "Alex",
    "lastName": "Taylor",
    "dateOfBirth": "1990-02-10",
    "email": "alex.taylor@example.co.uk",
    "mobile": "7123456789",
    "mobileCountryCode": "44",
    "nationality": "GB",
    "isPep": false,
    "address": {
      "addressLine1": "20 High Street",
      "addressLine2": "",
      "city": "London",
      "state": "",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    "positions": [
      {
        "title": "DIRECTOR",
        "startDate": "2022-03-14"
      },
      {
        "title": "REPRESENTATIVE",
        "startDate": "2022-03-14"
      }
    ]
  },
  "stakeholders": {
    "individual": [
      {
        "externalId": "stakeholder-001",
        "firstName": "Jordan",
        "lastName": "Reed",
        "dateOfBirth": "1988-11-01",
        "nationality": "GB",
        "email": "jordan.reed@example.co.uk",
        "mobile": "7987654321",
        "mobileCountryCode": "44",
        "isPep": false,
        "sharePercentage": 30,
        "address": {
          "addressLine1": "5 River Road",
          "addressLine2": "",
          "city": "Manchester",
          "state": "",
          "postcode": "M1 1AA",
          "country": "GB"
        },
        "positions": [
          {
            "title": "UBO",
            "startDate": "2022-03-14"
          }
        ]
      }
    ],
    "corporate": []
  },
  "natureOfBusiness": {
    "operatingCountries": [
      "GB"
    ],
    "industryCodes": [
      "IS001"
    ],
    "industryDescription": "Business software services."
  },
  "expectedAccountUsage": {
    "intendedUses": [
      "IU001"
    ],
    "intendedUsesDescription": "",
    "credit": {
      "monthlyTransactionVolume": "MVUK01",
      "monthlyTransactions": "ATC01",
      "averageTransactionValue": "ATVUK01",
      "topTransactionCountries": [
        "GB"
      ],
      "topRemitters": [
        "Primary UK merchants"
      ]
    },
    "debit": {
      "monthlyTransactionVolume": "MVUK01",
      "monthlyTransactions": "ATC01",
      "averageTransactionValue": "ATVUK01",
      "topTransactionCountries": [
        "GB"
      ],
      "topBeneficiaries": [
        "Main UK vendors"
      ]
    }
  },
  "sizeOfBusiness": {
    "totalEmployees": "EM005",
    "annualTurnover": "UK010"
  },
  "deviceDetails": {
    "ipCountryCode": "GB",
    "deviceInfo": "MAC",
    "ipAddress": "203.0.113.10",
    "sessionId": "session-uk-001"
  },
  "tags": [
    {
      "key": "segment",
      "value": "test"
    }
  ]
}

Individual customer — request

{
  "type": "individual",
  "kycType": "full",
  "region": "UK",
  "externalId": "ind-uk-001",
  "firstName": "Sam",
  "middleName": "",
  "lastName": "Patel",
  "email": "sam.patel@example.co.uk",
  "nationality": "GB",
  "isPep": false,
  "dateOfBirth": "1995-06-20",
  "mobile": "7012345678",
  "mobileCountryCode": "44",
  "deviceDetails": {
    "ipCountryCode": "GB",
    "deviceInfo": "iOS",
    "ipAddress": "203.0.113.11",
    "sessionId": "session-uk-002"
  },
  "expectedAccountUsage": {
    "intendedUses": [
      "IU001"
    ],
    "intendedUsesDescription": "",
    "credit": {
      "monthlyTransactionVolume": "MVUK01",
      "topTransactionCountries": [
        "GB"
      ]
    },
    "debit": {
      "monthlyTransactionVolume": "MVUK01",
      "topTransactionCountries": [
        "GB"
      ]
    }
  },
  "bankAccountDetails": {
    "accountName": "Sam Patel",
    "bankName": "Example Bank",
    "accountNumber": "12345678",
    "bankCountry": "GB",
    "currency": "GBP",
    "bankAccountType": "current",
    "routingCodes": [
      {
        "type": "SORT_CODE",
        "value": "112233"
      }
    ]
  },
  "billingAddress": {
    "addressLine1": "1 Market Street",
    "addressLine2": "",
    "city": "Bristol",
    "state": "",
    "postcode": "BS1 4DJ",
    "country": "GB"
  }
}

Error handling

Scenario	Error Code	HTTP Code	Description	Comments
Missing mandatory fields	missing_required_fields	400	One or more required fields are missing.	The response may include the relative field path.
External ID is duplicated for applicants or stakeholders	duplicate_externalId	400	externalId is duplicate.	The response may include the full field path, such as applicant.externalId or stakeholders.individual[0].externalId.
Field value is not accepted	invalid_input	400	A field contains an unsupported or invalid value.	The response may identify the exact field.
Customer already exists	customer_exists	400	A customer already exists for the given field value.	The additional field value may identify externalId, businessName, or another matching field.
Client setup is incomplete	incomplete_client_setup	422	Request cannot be accepted because the client-as-customer setup is incomplete.	Ensure the client customer record exists and compliance is complete before retrying.

Adding positions

Add all management directors as stakeholders.

Tag anyone owning 25% or more, directly or indirectly, as a UBO. If no individual owns 25% or more, declare the most senior director as the UBO.

The applicant is treated as a representative by default. Add other representatives or signatories if they are authorized to perform transactions or manage users.

Include partners, trustees, settlors, or other applicable roles based on the business entity type.

For multi-layered companies, include all corporate stakeholders owning 25% or more and upload a CORPORATE_STRUCTURE document. For more information, see UK Onboarding.