Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Step 1: The Donor Generates the Share Token

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.
Tri-party agreement: Sumsub requires donors and recipients to have a Reusable KYC agreement in place before tokens can be exchanged. See Sumsub’s Reusable KYC docs for the prerequisites on the donor side.
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)

  1. In the Dakota dashboard, open the Customers page and click Add customer.
  2. Switch the toggle from Manual to Sumsub Import.
  3. 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
  4. Paste the tokens generated by the donor into the CSV (one per line), then upload the file.
  5. 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": "Failed to redeem token: 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

ScenarioStatusDetail
Invalid or expired token400Failed to redeem share token: ...
Token already redeemed400Tokens are single-use
Incompatible data (Sumsub error 10513)400The donor’s verification data isn’t compatible with Dakota’s requirements; no applicant is created
Caller lacks admin permissions401Token import requires manage_compliance_applications
If the redemption succeeds but Sumsub returns documents_requested, the application is still created — sumsub_review_status will indicate this 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. Idempotency. The endpoint honors the X-Idempotency-Key header. 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.