Skip to main content
POST
Creates a hosted verification link on verify.trusset.org for one customer. The customer opens it, pays the fee if you set one, connects a wallet, signs a message that proves it controls the wallet, and passes the identity check.
The fee is collected before the identity check opens, and no endpoint refunds it. A customer who fails the check, or whose link is revoked, has still paid.A link that names no wallet accepts the first wallet attached on the hosted page, and only from the holder of that wallet: the page asks the wallet to sign a message first, and the attach is refused with 401 WALLET_SIGNATURE_REQUIRED without it. From then on the identity check opens only for a visitor signed in with that wallet, so whoever attached a wallet can only verify their own identity onto it. Someone holding the URL can still attach their own wallet first and lock the customer out, so treat the URL as a credential, revoke a link the customer cannot open and send a new one. Set recipientWallet whenever you know the wallet.A link that names a wallet works the same way: the identity check, its token refresh and the completion open only for a visitor signed in with that wallet (401 WALLET_SIGNATURE_REQUIRED otherwise), so the customer opens the link with that wallet connected. Contract wallets sign in through ERC-1271. A link is completed only after its identity check was submitted to Sumsub; a completion without one is refused with 409 ID_CHECK_NOT_SUBMITTED and the link stays open. Once a link is used, only the holder of its wallet is told the outcome on the hosted page.
The link reads COMPLETED once the customer finishes the hosted flow or the identity check passes. It reads REJECTED when the check fails or the review does not meet the profile (see Review rules), which can happen after it read COMPLETED. COMPLETED alone is not a verdict. A check approved before any wallet is bound also reads COMPLETED, and the link then waits for a wallet: Get ID Link reports awaitingWallet: true. From then on only you can bind the wallet, with Bind Link Wallet. The hosted page refuses the customer with 409 ISSUER_BINDS_WALLET and asks them to contact you. Before the approval, the hosted page binds a wallet only to a link that is still open and unused. A passed check writes nothing on chain by itself. The wallet is queued in List Pending Verifications, and it stays unregistered until your instance’s registered wallet signs the transaction. When the profile has an eligibility register, the wallet’s admission to it is queued as well. See Eligibility registers. EXPIRED means the link was revoked. A link that runs past expiresAt without being revoked still reads PENDING, although the hosted page refuses it.

​
Review rules

Sumsub reports each review to Trusset. A green review is accepted only when all of these hold:
  • It comes from the Sumsub level the link was created with. Otherwise it is refused with KYC_LEVEL_MISMATCH, or with KYC_LEVEL_UNKNOWN when Sumsub reports no level.
  • The applicant is of the kind the profile admits: a company applicant for a COMPANY profile, an individual for an INDIVIDUAL one. Otherwise KYC_ENTITY_MISMATCH.
  • No country reported for the applicant is on the profile’s blocked list, and neither is the link’s own country. The reported countries are the document country, the declared country, the nationality and, for a company, its country. Otherwise COUNTRY_BLOCKED.
The level is fixed when the link is created. The applicant kind and the blocked countries are read from the profile when the review arrives. A refused review turns the link REJECTED and the customer record, when there is one, rejected, and the customer’s audit log records KYC_REFUSED_LEVEL, KYC_REFUSED_ENTITY or KYC_REFUSED_COUNTRY. A final red review turns it REJECTED too. A customer record already verified under another profile keeps its status. A refusal or a rejection also queues the removal of the link’s wallet from the eligibility register of the link’s profile, and cancels its admission there when it is still waiting. A red review that asks the customer to resubmit documents (reviewRejectType: RETRY) keeps a link whose review has not settled open, so the customer can finish on the same link. A link the hosted page had already completed is reopened as PENDING.

​
A review settles once

The first approval, refusal or final rejection applied to a link settles it. A review that arrives after that is ignored, repeats and replays of the same review included, with one exception: a final red review still turns an approved link REJECTED, unless Sumsub dated it no later than the moment Trusset applied the approval. A revoked link ignores every review. Sumsub delivers each review by webhook, and an event Sumsub dated more than 7 days before it arrives is ignored whatever it says. An ignored review changes nothing: the link, the customer record, the queues and the customer webhook stay as they were, and the audit log records KYC_REVIEW_IGNORED. Recheck Link Review applies the same rules. It does not ask Sumsub about a settled link at all, unless the link is approved and still waiting for a wallet.
A final rejection that turns an approved link REJECTED dismisses the link’s registration while it still waits in the pending queue, so it can no longer be signed. An identity you already registered stays on your instance register until you revoke it with Revoke Identity.Archiving a customer with Archive Customer closes its open links, including one whose review has not come back yet, so a later review registers nothing. It also dismisses the customer’s rows in the pending queue.
A customer webhook set up in the Issuer Portal reports each review Trusset applies as customer.kyc_reviewed, with outcome APPROVED, REFUSED, REJECTED or RETRY. UNCONFIRMED means Sumsub approved but the applicant could not be read to apply the rules above, so the link is unchanged until a later review or Recheck Link Review applies the approval. An ignored review is not reported. A registration waiting for your signature is reported as customer.registration_pending, and a completed registration as customer.registered.

​
Run the check in your own app

Your app can run the identity check itself with the Sumsub SDK instead of sending the customer to the hosted page. The link stays the record of the onboarding either way, and the review is held to the same rules.
1

Create the link

Create it as described on this page, without feeCents, because a fee is collected only on the hosted page. Omit sendVia so nothing is delivered, and name the wallet with recipientWallet when you already know it.
2

Run the check

Issue Sumsub Token returns an access token for the link’s applicant and level. Pass it to the Sumsub WebSDK or MobileSDK in your app.
3

Bind the wallet

Bind Link Wallet attaches the customer’s wallet, before or after the review. A review approved without a wallet waits for one, and the registration is queued once the wallet is bound. After the approval this call is the only way to bind it.
4

Follow the outcome

Get ID Link reads the review, the registration and the eligibility admissions. Recheck Link Review asks Sumsub again when a review did not arrive or could not be applied.
When the link carries recipientEmail or recipientPhone, Trusset still tells the recipient of a rejection, a resubmission request or a verification that needed no registration. A resubmission message points to the hosted link. The registration on your instance register and any eligibility admission are signed by your own wallet, as for a hosted link. Every identity check runs on Trusset’s Sumsub account, whether the customer completes it on the hosted page or in your app.

​
Body Parameters

Send at least one recipient: recipientEmail, recipientWallet or recipientPhone. A linked customer can supply the wallet or the email instead.
​
string
Where the link is emailed when sendVia includes email. It also pre-fills the identity check. The address is not validated here.
​
string
Binds the link to this wallet, so the hosted page accepts no other and opens the identity check only after the customer signs in with it. The customer opens the link with this wallet connected and signs a message (not a transaction, no gas); anyone else can open the page but never sees its result. Stored and returned checksummed.
​
string
Where the link is texted when sendVia includes sms. Send it in E.164 form. The SMS sender strips spaces, hyphens, brackets and dots, reads a leading 00 as +, and reads a single leading 0 as a German number (+49). A number that still is not E.164 fails in delivery.sms, not here.
​
string
The customer record this link completes. Completion then updates that record instead of creating a second customer. Archived customers are not matched.
​
string
Names the customer by reference key instead. Used only when customerId is absent.
​
string
Names the customer by external ID instead. Used only when customerId and referenceKey are absent.
When a customer is named, each identifier must be a string of 1 to 128 characters. A customer who already holds a wallet binds the link to it, and a different recipientWallet is refused. When the request sends no recipient at all, the customer’s first email contact becomes recipientEmail. The customer’s country and investor type fill country and investorType when those are omitted.
​
string
default:"RETAIL"
The key of an enabled verification profile, matched exactly. The presets are RETAIL, PROFESSIONAL and ELIGIBLE_COUNTERPARTY. Custom keys are lowercase. The profile sets the check level, the documents requested and the blocked countries. Defaults to the linked customer’s investor type, then RETAIL.The link keeps the Sumsub level, the applicant type (individual or company) and the on-chain investor type the profile had when the link was created, so a later change to the profile does not reach a link already sent. The blocked countries are read when the investor uses the link.
​
string
The customer’s country as an ISO 3166-1 code: alpha-2 (DE), alpha-3 (DEU) or numeric. It is stored and returned as alpha-3. A country the profile blocks is refused here. The country the identity check reports is tested against the same list at review.
​
object
For a profile whose entityType is COMPANY, which runs the check for a company applicant. name and registrationNumber, both strings, pre-fill that applicant together with country. Ignored for an INDIVIDUAL profile.
​
integer
default:"30"
Days until the link expires, from 1 to 365. Paying the fee extends a link with less than 24 hours left to 24 hours after payment.
​
integer
A verification fee in the smallest currency unit, from 50 to 1000000. The customer pays it through a Stripe checkout on the hosted page before the check opens. Omit it for a free link.
​
string
eur or usd, in any case. Required with feeCents and ignored without it.
​
string | string[]
email, sms, or both. Omit it to deliver the link yourself. A channel without a matching recipient is skipped, and other values are ignored.
​
string
Shown as a note in the email and returned to the hosted page.
​
string
Replaces the default text of the email and the SMS, and is returned to the hosted page.
​
string
Stored with the link, but nothing reads it back. No endpoint returns it and the hosted page does not redirect to it.

​
Response Fields

​
object

​
Error Codes