> ## 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.

# Sumsub Token Sharing

> Reuse a customer's existing Sumsub verification to onboard them to Dakota without re-collecting identity data or documents.

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.

<Info>
  **Sumsub references:** This flow is built on Sumsub's [Reusable KYC](https://docs.sumsub.com/docs/reusable-kyc) feature. The token-generation endpoint used by the donor is documented at [Generate share token](https://docs.sumsub.com/reference/generate-share-token).
</Info>

<Info>
  **Scope:** Token sharing is currently supported for **individual applicants only**. Business onboarding is not in scope for this flow.
</Info>

# 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.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Donor
    participant Dakota
    participant Sumsub

    Donor->>Sumsub: Generate share token<br/>(applicantId, forClientId=Dakota)
    Sumsub-->>Donor: token (single-use, 20min TTL)
    Donor->>Dakota: Hand off token (out-of-band)
    Dakota->>Sumsub: Redeem token<br/>(POST /reusableIdentity/reuse)
    Sumsub-->>Dakota: New applicant + copied data & documents
    Dakota->>Dakota: Map Sumsub data → individual application,<br/>download documents to GCS
```

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](https://docs.sumsub.com/reference/generate-share-token) reference.

A typical request looks like:

```bash cURL theme={null}
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.

<Info>
  **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.
</Info>

<Info>
  **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](https://docs.sumsub.com/docs/reusable-kyc) for the prerequisites on the donor side.
</Info>

<Warning>
  **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](https://docs.sumsub.com/reference/generate-share-token) for the exact TTL bounds.
</Warning>

# 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:

   ```csv theme={null}
   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

```http theme={null}
POST /customers/bulk-import-sumsub-tokens
```

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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.

<Info>
  **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.
</Info>

# Error Handling

| Scenario                                 | Status | Detail                                                                                             |
| ---------------------------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| Invalid or expired token                 | `400`  | `Failed to redeem share token: ...`                                                                |
| Token already redeemed                   | `400`  | Tokens are single-use                                                                              |
| Incompatible data (Sumsub error `10513`) | `400`  | The donor's verification data isn't compatible with Dakota's requirements; no applicant is created |
| Caller lacks admin permissions           | `401`  | Token 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](/documentation/customer-onboarding) guide for the standard onboarding flow that imported applications complete with.
* See the [API Reference](/api-reference/introduction) for the full request/response schema of `bulkImportFromSumsubTokens`.
* Subscribe to [Webhooks](/documentation/webhooks) to receive notifications when imported applications progress through review and approval.