KYC via Sumsub Shared Token

This guide explains how to import KYC verification results from your own Sumsub account into our platform using a Sumsub share token. You run KYC under your Sumsub configuration, then transfer the verified individual to us.

info

To perform this flow for a Subaccount, pass the subAccountId field as a request parameter, as with every other KYC endpoint.

Prerequisites

1. Feature enablement — contact our team to set your user flag SumsubSharedClient. Until it is set, every call returns 401 Unauthorized.
2. Individual users only — the platform user must have account type INDIVIDUAL. Company accounts are rejected synchronously.
3. A valid, unused Sumsub share token, generated from your Sumsub account for an applicant with GREEN review status. See the Sumsub Reusable KYC documentation for how to generate share tokens.

Endpoint

POST /v2/kyc/import-token/?subAccountId={sub-account-id}

Note the trailing slash after import-token.

Request body

{
  "importToken": "your-sumsub-share-token"
}

Response (200 OK)

{
  "id": "kyc-attempt-uuid",
  "message": "token imported successfully: processing KYC"
}

The id is the KYC attempt id. A 200 here means the token was imported and an attempt was created — it does not mean the user was approved. Content validation runs asynchronously; the final result arrives via the KYC-COMPLETED webhook (see below).

How it works

Synchronous errors (returned by the endpoint)

These are returned immediately on the HTTP call:

HTTP	Message	Cause
401	(no body)	SumsubSharedClient flag not set for the user
400	importToken endpoint is only available for INDIVIDUAL users	Platform user is not INDIVIDUAL
400	importToken invalid field	Empty importToken
400	token is not valid or already used	Sumsub rejected the share token (400/401)
400	can only import one token per user	Token already consumed (Sumsub 409)
400	another token is currently being processed	A previous import workflow is still running for this user

Asynchronous rejections (delivered via KYC-COMPLETED)

Once the attempt is created, content validation runs in the background. On failure you receive KYC-COMPLETED with result: REJECTED and a resultMessage. Possible reasons:

resultMessage (or internal reason)	Cause
sumsub applicant is not approved (review=...)	Review answer is not GREEN (message includes labels/comments)
sumsub applicant type must be individual	Sumsub applicant is not an individual
missing applicant name / missing applicant date of birth / missing applicant country	Required field absent in both Info and FixedInfo
applicant requires one document of type ID_CARD, PASSPORT, DRIVERS or RESIDENCE_PERMIT	No accepted identity document
brazilian applicants must provide Tax ID (CPF)	BR user without TIN/CPF
applicant requires a document number	Non-BR user without TIN or document number
cannot repeat taxId across multiple users	Tax ID already used by another user
rejected due to compliance reasons	Fraud / DICT mark (Brazilian users, production only)

Required data

The system extracts each field from Info (data Sumsub read from documents) first, then falls back to FixedInfo (data the user typed).

Brazilian users

• CPF (Tax ID) is mandatory — must be present in the applicant's TIN field; it cannot be derived from a document number.
• One identity document: ID_CARD, PASSPORT, DRIVERS or RESIDENCE_PERMIT.
• Full name, date of birth, country of Tax ID = Brazil.
• Review answer GREEN.
• In production, additional Brazilian validations run: BDC name/DOB reconciliation and a fraud/DICT-mark check.

Non-Brazilian users

• Tax ID resolution priority: TIN → document number → document additionalNumber.
• One identity document: ID_CARD, PASSPORT, DRIVERS or RESIDENCE_PERMIT.
• Full name, date of birth, country of Tax ID.
• Review answer GREEN.

Optional (both)

Email, and address fields (city, postal code, street, state). State should be the ISO 3166-2 subdivision code (e.g. SP, CA). Look up the subdivision code for any country on the official ISO Online Browsing Platform (OBP).

Webhook events

The attempt id (id from the response) lets you track progress. Three events are emitted, all under the KYC subscription:

Order	Event	status	result
1	KYC-STARTED	PENDING	null
2	KYC-PROCESSING	PROCESSING	null
3	KYC-COMPLETED	COMPLETED	APPROVED | REJECTED

KYC-STARTED and KYC-PROCESSING are emitted right after the attempt is created; KYC-COMPLETED after validation finishes.

Attempt payload

{
  "type": "KYC-COMPLETED",
  "attempt": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userId": "user-uuid",
    "levelName": "sumsub-token-{your-client-id}",
    "submissionData": { },
    "status": "COMPLETED",
    "result": "REJECTED",
    "resultMessage": "brazilian applicants must provide Tax ID (CPF)",
    "rejectionLabels": [],
    "retryable": true,
    "createdAt": "2024-01-01T10:00:00Z",
    "updatedAt": "2024-01-01T10:00:05Z"
  }
}

levelName is always sumsub-token-{client-id}, where {client-id} is your configured SumsubSharedClient.

For the wrapper envelope and signature verification, see Webhook Events and Verifying Webhook Authenticity.

Best practices

• Treat 200 as "accepted for processing", not "approved" — wait for KYC-COMPLETED.
• Deduplicate webhooks by the envelope id; always reply 200.
• For Brazilian users, always set the CPF in the Sumsub TIN field.
• Ensure GREEN review and an accepted document type before generating the token.