Skip to main content
An onboarding takes one customer from “unknown” to “may act on your markets” through a single path. Your backend starts it, your app runs the identity check or waits for your verifier, and your wallet signs what has to go on chain. Every answer names the status and the next step, so your integration follows one object instead of links, queues and records.
Every request authenticates with an instance API key in the X-API-Key header and needs the identity service.

One customer, one onboarding

An onboarding belongs to a customer record. Address it in the path by the customer id, your own externalId, the reference key (ref_...) or the wallet address. A path value shaped like a wallet address is read as a wallet, and one starting with ref_ as a reference key, so an externalId of either shape is refused. Start Onboarding creates the customer record when your externalId or wallet is new, so one call is enough to begin. Starting again for the same customer returns the onboarding that is already running. It does not open a second identity check.

Two providers

The provider follows your configuration. When a start names no provider, a profile with an active KYC source onboards through that source, and every other profile through TRUSSET. Onboarding Options lists the profiles of your instance with the provider each one defaults to. Name provider to decide per customer.

Status and next step

status says where the onboarding stands. nextAction says who acts next and which call that is. AWAITING_SIGNATURE carries nextAction.kind, which names what your wallet signs:

The identity check in your app

1

Start

Start Onboarding with your externalId and the profile. The answer carries sdk.token.
2

Run the check

Pass the token to the Sumsub WebSDK or MobileSDK. When it expires, Issue SDK Token returns a new one for the same applicant.
3

Bind the wallet

Bind Wallet when the customer connects one, before or after the review. Send it with the start when you already know it.
4

Sign

When the status reads AWAITING_SIGNATURE, Build Transactions returns unsigned transactions. A wallet of your instance signs them, and Confirm Transactions records the result.
The review is held to the review rules of ID links: the profile’s level, its applicant type and its blocked countries. An ID link stays the record behind the check, and identityCheck.linkId names it.

Through your KYC source

1

Start

Start Onboarding for a profile your source verifies for, with the customer’s wallet. The status reads AWAITING_RECORD.
2

The source delivers

Your verifier checks the customer and delivers the sealed record for that wallet through its KYC inbox. The status turns RECORD_RECEIVED.
3

Open and decide

trusset-kyc open opens the record on your machine. The status turns AWAITING_DECISION, and Decide Record approves or rejects it.
4

Sign

An approved record whose source is bound to whitelists reads AWAITING_SIGNATURE. Build, sign and confirm as above. Without bound whitelists the onboarding is COMPLETED with the approval.
An onboarding through a KYC source admits the wallet to whitelists. It does not register the wallet on your identity register, and the customer record keeps its status.

What a start replaces

A running onboarding is never replaced silently. Replacing an open identity check revokes it, so a review that arrives later registers nothing.

Events

A customer webhook set up in the Issuer Portal reports each step: customer.kyc_reviewed, customer.registration_pending and customer.registered for the identity check, and the customer.kyc_record_* events for a KYC source. Read the onboarding again when one arrives. Get Onboarding never calls Sumsub, so polling it costs one request and nothing else.

What Trusset holds

The onboarding takes no name, email address or phone number. It stores the customer’s wallet, country and profile, your externalId, and the provider it runs through. The company name of a COMPANY profile is the one exception: it names the customer record and pre-fills the company applicant. Nothing is signed on your behalf. Every transaction is returned unsigned, and a wallet of your instance signs and broadcasts it.

Response envelope

Every route sends both data and error, with the unused one null. A refusal can carry error.details, for example the status an onboarding is in. Every answer carries Cache-Control: no-store, because an answer can carry an applicant access token.

Rate limits

Reads share 240 requests per minute per instance, and every other call shares 120. Both answer 429 RATE_LIMIT_EXCEEDED with a Retry-After header. The 200 requests per minute of the API key apply as well.