Once the sharing relationship with Dakota is in place, you can start moving customers across. This page covers the three steps: the donor generates a share token, you redeem it, and the application is completed.

New to this flow? Start with Sumsub Token Sharing — it covers how Reusable KYC works, what data transfers, and the one-time setup.

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.

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 Onboarding

The import fills in everything the share token carried. The application is created in a pending state and cannot be submitted until the remaining fields are supplied. Typically still missing:

Employment status, purpose of account, source of wealth
Attestations
SSN, if Sumsub’s TIN field didn’t carry a properly formatted one

You can send the customer the application link and let them finish on Dakota, or supply the data over the API and keep them inside your own app.

Completing an Imported Application

Both routes, step by step — getting an application token, sending the remaining fields, and submitting. The same flow whether the application came from Sumsub or Persona.

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

Import Share Tokens

Agentic Payments

Authentication

Developer Tools

Importing Sumsub Tokens

Step 2: Redeem the Tokens on Dakota

From the dashboard (CSV upload)

From the API

Step 3: Complete the Onboarding

Completing an Imported Application

Error Handling

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

Request-level errors

Things to Know

What’s Next

​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 Onboarding

Completing an Imported Application

​Error Handling

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

​Request-level errors

​Things to Know

​What’s Next

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 Onboarding

Error Handling

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

Request-level errors

Things to Know

What’s Next