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 customerid, 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.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.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, yourexternalId, 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 bothdata 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 answer429 RATE_LIMIT_EXCEEDED with a Retry-After header. The 200 requests per minute of the API key apply as well.