Skip to main content
POST
Starts the onboarding of a customer, or returns the one that is already running. Call it from your backend when the customer begins verification in your app. The same call is safe to repeat: it never opens a second identity check for a customer whose check is still open. For the TRUSSET provider the answer carries sdk.token, which your app passes to the Sumsub WebSDK or MobileSDK. For a KYC_SOURCE it names the source the record is expected from. See Onboarding for the whole path.

Who the customer is

Name the customer with one of customerId, referenceKey, externalId or walletAddress. They are tried in that order. An externalId or a wallet that matches no customer creates the customer record, with the profile, the country and the wallet you send. A customerId or referenceKey that matches nothing is refused with 404 CUSTOMER_NOT_FOUND. The record is written only once the profile, the country and the provider are accepted, so a start refused for one of them leaves nothing behind. A wallet held by an archived customer record of your instance, as its primary or as a linked wallet, is refused with 409 WALLET_IN_USE, as on Bind Wallet: restore that record, or bind another wallet. The start does not restore the archived record. A new customer whose wallet your instance already verified on its register starts as verified, and the onboarding answers COMPLETED without a check.

Body Parameters

string
The id of an existing customer.
string
The reference key of an existing customer, ref_....
string
Your own ID for the customer: a string of 1 to 128 characters with no leading or trailing spaces and no control or invisible characters, such as a zero-width space or a line break. Created when it is new. It must not look like a wallet address (0x followed by 40 hex characters) or start with ref_, because the /:customer routes read such an identifier as a wallet or a reference key, and a new one must not be the ID of a customer record of your instance, because those routes try an identifier as a record ID first. Each is refused with 400 INVALID_INPUT and error.details.field: "externalId". A 40-character hex value without 0x is not a wallet address and is accepted. Create Customer applies the same rule.
string
The customer’s wallet. It is bound at the start when the customer has none, under the rules of Bind Wallet. A customer who already holds another wallet is refused with 409 CUSTOMER_WALLET_MISMATCH, and a wallet held by an archived customer record with 409 WALLET_IN_USE.
string
The key of an enabled verification profile, matched exactly. investorType is accepted as another name for it. Defaults to the profile of the running onboarding, then to the customer’s investor type, then to RETAIL.
string
ISO 3166-1 alpha-2, alpha-3 or numeric. A country the profile blocks is refused with 403 COUNTRY_BLOCKED before anything is created. Defaults to the customer’s country.
string
TRUSSET or KYC_SOURCE. Without it, a running onboarding keeps its provider, a profile with an active KYC source uses that source, and every other profile uses TRUSSET.
string
The KYC source to go through. It implies provider: KYC_SOURCE. Required when several active sources verify for the profile (400 SOURCE_REQUIRED, with the sources in error.details.sources).
object
For a profile whose entityType is COMPANY: name and registrationNumber, both strings. They pre-fill the company applicant, and name names a customer record created by this call.
boolean
default:"false"
Replaces a running onboarding that can still be replaced, or runs a new check for a customer who is COMPLETED or REJECTED. See What a start replaces.
integer
default:"30"
Days the identity check stays open, from 1 to 365. Used by the TRUSSET provider only.

Response Fields

The call answers 201 when it started something and 200 when it returned an onboarding as it was. Every answer carries Cache-Control: no-store, because it can carry an applicant access token.
object

Error Codes