If your customer has already completed KYC with another Sumsub client, you don’t have to make them go through verification again. Dakota supports Sumsub’s Reusable KYC flow: the Sumsub client that originally verified the customer (the donor) generates a single-use share token, hands it to you, and you redeem it on Dakota to create a customer and individual application pre-filled with the customer’s identity data and documents. This guide explains how the flow works end-to-end, what data transfers (and what doesn’t), and how to redeem tokens on Dakota.

Sumsub references: This flow is built on Sumsub’s Reusable KYC feature. The token-generation endpoint used by the donor is documented at Generate share token.

Scope: Token sharing is currently supported for individual applicants only. Business onboarding is not in scope for this flow.

How It Works

The share token flow has three parties:

Donor — the Sumsub client that originally verified the customer. They generate the share token, scoped to Dakota’s Sumsub clientId (dakota.xyz_158913).
Dakota — the recipient. You redeem the token on Dakota’s side, which creates a fresh applicant on Dakota’s Sumsub account with the donor’s data copied over.
Sumsub — handles the transfer of identity data and documents between the donor’s account and Dakota’s account.

Tokens are single-use and have a default TTL of 1200 seconds (20 minutes). Once redeemed, the token is consumed and cannot be reused. Two things must be in place before a share token can be generated. The first is entirely on your side; the second is an exchange between you and Dakota, carried out in each party’s own Sumsub Dashboard. Sumsub’s share-token endpoint requires a specific dashboard permission:

“This method requires the Share applicants data dashboard permission. App tokens and team members must have a role that includes this permission; otherwise, the request fails with a permission error.” — Generate share token

If your token-generation call fails with a permission error, check the role attached to the app token you are signing the request with.

2. Add Dakota as a recipient using a partner token

Before any share token can be generated, you must add Dakota to your sharing partners in Sumsub. This requires a partner token, which is a different thing from the share tokens you will generate later — and it comes from Dakota, not from Sumsub.

Request the partner token from Dakota. Sumsub generates the partner token on the recipient’s side when we add you as a donor, and we then pass it to you. Contact your Dakota representative to request it — you cannot generate it yourself, and Sumsub support cannot issue it for you.

How the exchange works, per Sumsub’s Partner management documentation: On your side the steps are:

In the Sumsub Dashboard, open the Reusable identity section and go to the Partners page.
Select the Recipients tab and click Add recipient.
Paste the partner token Dakota gave you.
Confirm that you want to add Dakota as a recipient.

Match the environment, and mind the expiry. Sumsub notes: “When generating a partner token, make sure to use the token in the same environment where it was created.” Production tokens carry an lv prefix and Sandbox tokens an sbx prefix — a token from the wrong environment will not create the partnership. Partner tokens also expire 30 days after creation, so request a fresh one if yours has gone stale.

Once Dakota appears in your Recipients list, you can generate share tokens with forClientId: dakota.xyz_158913 as described in Step 1 below. Sumsub’s own references for this setup:

Partner management — adding donors and recipients, and the partner token exchange
Reusable KYC — overview of the feature and its prerequisites
Reusable KYC Share — the donor-recipient relationship and the full token lifecycle

forClientId is not the setup step. The forClientId parameter you pass when generating each token scopes that token to Dakota. It presumes the sharing relationship already exists — it does not create it. If you are being asked for a partner token or a recipient registration step that isn’t covered here, that is a Sumsub-side configuration item; take it to Sumsub with the clientId above.

Once Sumsub confirms the relationship is active, continue with Step 1 below. The donor generates a share token on their Sumsub account, scoped to Dakota’s Sumsub clientId. This is a Sumsub-side operation — Dakota is not involved at this stage. The full request and response schema is documented in Sumsub’s Generate share token reference. A typical request looks like:

cURL

curl -X POST 'https://api.sumsub.com/resources/accessTokens/shareToken' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Token: <DONOR_SUMSUB_APP_TOKEN>' \
  -H 'X-App-Access-Sig: <signature>' \
  -H 'X-App-Access-Ts: <timestamp>' \
  -d '{
    "applicantId": "<applicant_id_on_donor_side>",
    "forClientId": "dakota.xyz_158913",
    "ttlInSecs": 1200
  }'

The response contains a token field. The donor sends this token to you out-of-band — typically via secure email, your dashboard, or a private API call.

Dakota’s Sumsub clientId is dakota.xyz_158913. Pass this exact value as forClientId when generating the token — it scopes the token to Dakota, and Sumsub will reject the token if any other client tries to redeem it.

Relationship required first. This request only succeeds once the donor has added Dakota as a sharing partner in Sumsub — see Before You Start above.

Tokens expire fast. Sumsub share tokens default to a 1200-second (20-minute) TTL and are single-use — once redeemed they cannot be reused. The donor can extend the TTL up to Sumsub’s maximum via the ttlInSecs parameter, but the token will still expire. Plan to redeem tokens as soon as the donor hands them over; if a token expires before you import it, ask the donor to generate a new one. See the Sumsub share-token reference for the exact TTL bounds.

Step 2: Redeem the Tokens on Dakota

Hand the share tokens off to Dakota to create the customers and applications. Customer names are derived automatically from each token’s Sumsub data — you don’t supply them. There are two ways to redeem tokens. The dashboard is the recommended path for one-off migrations; the API exists for when you want to automate it.

From the dashboard (CSV upload)

In the Dakota dashboard, open the Customers page and click Add customer.
Switch the toggle from Manual to Sumsub Import.
Click Download template to get a starter CSV. The format is one column called token with one share token per row:
token _act-sbx-jwt-paste-first-token-here _act-sbx-jwt-paste-second-token-here
Paste the tokens generated by the donor into the CSV (one per line), then upload the file.
Click Import. The dashboard parses the CSV client-side and submits the tokens. Per-row results — success, customer / application IDs, or the error message — are shown when the request finishes.

The dashboard upload calls the same POST /customers/bulk-import-sumsub-tokens endpoint described below, so the limits and behavior are identical.

From the API

POST /customers/bulk-import-sumsub-tokens

cURL

curl -X POST 'https://api.platform.dakota.xyz/customers/bulk-import-sumsub-tokens' \
  -H 'X-API-Key: <YOUR_API_KEY>' \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
    "tokens": [
      "_act-sbx-jwt-eyJhbGciOiJub25lIn0...",
      "_act-sbx-jwt-eyKhbGciOiJub25lIn0..."
    ]
  }'

Limits: between 1 and 100 tokens per request. Response:

{
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "results": [
    {
      "name": "Sarah Williams",
      "success": true,
      "customer_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
      "application_id": "2hCjxJzUAW6JVRkZqaF9E0KpM3b"
    },
    {
      "name": "Unknown",
      "success": false,
      "error": "Share token expired"
    }
  ]
}

The bulk endpoint always returns 200. Check success on each result individually — failed tokens don’t roll back successful ones.

Step 3: Complete the Application

After import, the application is in a draft/pending state with most identity data filled in. Before it can be submitted, the admin or the customer needs to complete the Dakota-specific fields that aren’t part of any Sumsub verification. What’s typically still needed:

employment_status, purpose_of_account, and source_of_wealth (Dakota-specific — not part of any Sumsub verification)
SSN if the applicant is a US person and Sumsub’s TIN field didn’t carry a properly formatted SSN
Source-of-wealth documents (Dakota-specific — never transferred from Sumsub)
Attestations (terms of service, privacy policy, information accuracy)

These can be filled in through the standard application editing endpoints or through the dashboard. Once complete, submit the application as you would any other.

Address fallback: When Sumsub doesn’t return an address (rare, but possible for minimal verification levels), Dakota inserts a placeholder country code so the application stays loadable. The address will fail validation on submit, forcing the admin to enter the real one.

Error Handling

Token-level problems do not produce an HTTP error. The endpoint returns 200 and reports each token’s outcome in its own results[] entry, so one bad token never affects the others — check success per row rather than branching on the status code.

Per-token outcomes (HTTP `200`, reported in `results[].error`)

When Sumsub rejects a token, its own message is passed through verbatim as the row’s error — so the exact wording comes from Sumsub, not Dakota.

Scenario	`error` value
Invalid, expired, or already-redeemed token	Sumsub’s own message (e.g. `Share token expired`)
Incompatible data (Sumsub error `10513`)	Sumsub’s own message — the donor’s verification doesn’t satisfy Dakota’s level; no applicant is created
Sumsub rejected the token without a message	`Sumsub rejected this share token`
Sumsub unreachable	`Could not reach Sumsub — please retry`
Redemption failed for any other reason	`Could not redeem share token`
Nothing usable in the Sumsub payload	`No data could be mapped from Sumsub`
Applicant has no date of birth	`Cannot import applicant without a date of birth (required for sanctions screening)`
Customer record could not be created	`Failed to create customer: ...`
Applicant data could not be saved	`Failed to save: ...`

Request-level errors

Scenario	Status	Detail
Empty or missing `tokens` array	`400`	`Request must contain at least one token`
Caller lacks the required permission	`401`	Token import requires the `create_customers` permission
`X-Idempotency-Key` is not a valid UUID	`400`	`Invalid X-Idempotency-Key: must be a valid UUID`

If the redemption succeeds but the donor’s documents don’t fully satisfy Dakota’s verification level, the application is still created and the import is reported as a success. The gap surfaces when the application is reviewed or submitted, and the customer will need to upload the missing documents through the standard flow.

Things to Know

Tokens are scoped to Dakota. When the donor generates the token, they specify Dakota’s Sumsub clientId as forClientId. Tokens cannot be redirected to other recipients. Tokens are single-use and time-limited. Default TTL is 20 minutes. If a token expires, the donor must generate a new one — there’s no extension. Verification level matters. Dakota redeems tokens against its id-only verification level. If the donor’s level required strictly more (e.g. enhanced due diligence), the extra data is ignored. If it required strictly less, the customer may end up in documents_requested status until the gap is closed. Permission. Redeeming tokens requires the create_customers permission. Idempotency. The endpoint honors the X-Idempotency-Key header, and the value must be a valid UUID — anything else is rejected with a 400. Sending the same key twice with the same body returns the original result rather than redeeming the tokens a second time. Use a fresh key per logical operation. Sumsub applicant ID is recorded. The new applicant created on Dakota’s side is stored as provider_applicant_id on the individual applicant record, so you can correlate Dakota applications back to their Sumsub origin.

What’s Next

Review the Customer Onboarding guide for the standard onboarding flow that imported applications complete with.
See the API Reference for the full request/response schema of bulkImportFromSumsubTokens.
Subscribe to Webhooks to receive notifications when imported applications progress through review and approval.

Playground

Documentation

Agentic Payments

Authentication

Developer Tools

Sumsub Token Sharing

How It Works

2. Add Dakota as a recipient using a partner token

Step 2: Redeem the Tokens on Dakota

From the dashboard (CSV upload)

From the API

Step 3: Complete the Application

Error Handling

Per-token outcomes (HTTP `200`, reported in `results[].error`)

Request-level errors

Things to Know

What’s Next

​How It Works

​Before You Start: Establish the Sharing Relationship

​1. The “Share applicants data” permission

​2. Add Dakota as a recipient using a partner token

​Step 1: The Donor Generates the Share Token

​Step 2: Redeem the Tokens on Dakota

​From the dashboard (CSV upload)

​From the API

​Step 3: Complete the Application

​Error Handling

​Per-token outcomes (HTTP 200, reported in results[].error)

​Request-level errors

​Things to Know

​What’s Next

How It Works

Before You Start: Establish the Sharing Relationship

1. The “Share applicants data” permission

2. Add Dakota as a recipient using a partner token

Step 1: The Donor Generates the Share Token

Step 2: Redeem the Tokens on Dakota

From the dashboard (CSV upload)

From the API

Step 3: Complete the Application

Error Handling

Per-token outcomes (HTTP `200`, reported in `results[].error`)

Request-level errors

Things to Know

What’s Next