> ## Documentation Index
> Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC Sumsub Shared Token

> Reuse a verification your customer already passed on your own Sumsub level: import it with a share token so the customer repeats neither document capture nor liveness.

If you already verified a customer on your own Sumsub level, hand that verification to Etherfuse instead of putting the customer through it again. You create a share token, we import the session, and the customer's identity data, documents **and liveness** come with it. The customer only completes requirements that the shared session or your API submissions did not satisfy.

<Note>
  This page names the underlying verification provider because the shared-token
  flow cannot be described without it: you create the share token in your own account
  with that provider. Elsewhere the docs keep the provider abstract.
</Note>

## Prerequisites

Reusable KYC is off by default on both sides. Before any of this works:

1. You verify customers on your own Sumsub level.
2. A one-time **data-sharing agreement** is signed with Sumsub, by both parties.
3. **Etherfuse is added as a sharing partner** in your Sumsub dashboard, and you in ours.
4. The account creating share tokens holds the **"Share applicants data"** permission.

Talk to your Etherfuse contact to start this. Neither side can enable it unilaterally.

## The flow

<Steps>
  <Step title="Create the customer's organization">
    A `personal` org, as in any other flow. See [KYC WebSDK](/v2/guides/kyc-websdk#the-flow). Send `userInfo.email`: the import uses it.
  </Step>

  <Step title="Create a share token in your Sumsub account">
    For the applicant you already verified, targeting Etherfuse's client id. Share tokens are short-lived and single-use.
  </Step>

  <Step title="Import the session">
    [`POST /organization/{organizationId}/verification/import`](/v2/api-reference/kyc/import-a-verified-session)
  </Step>

  <Step title="Push what the import response lists as pending">
    Usually the `occupation` answers, through [`POST /organization/{organizationId}/verification/questionnaire`](/v2/api-reference/kyc/submit-a-verification-questionnaire), and any [region-specific document](/v2/guides/onboarding#country-specific-requirements) through [`POST /organization/{organizationId}/verification/documents`](/v2/api-reference/kyc/upload-verification-documents). Send only these. When the last one lands, the identity stage is submitted for review.
  </Step>

  <Step title="Wait for the next stage">
    A [`kycUpdated`](/v2/api-reference/webhooks/kycupdated) webhook arrives when the stage is submitted, and again when the review clears and the next stage arrives (`status` back to `inProgress`). Then read [`GET /organization/{organizationId}/kyc?requirements=true`](/v2/api-reference/kyc/get-kyc-status).
  </Step>

  <Step title="Push the later stages as they appear">
    `proofOfAddress` appears only if the identity document carried no address and the shared session did not include one. `customerAgreement` appears last; send it only if you are [forwarding the customer's acceptance](/v2/guides/kyc-api#the-customer-agreement). Repeat the previous step after each one.
  </Step>

  <Step title="Launch the customer for what remains">
    Any questionnaire you did not answer over the API, plus liveness if the shared session did not cover it. The customer also accepts the customer agreement in `/idv` unless you forwarded it.
  </Step>
</Steps>

<Warning>
  **Do not send everything at once after the import.** The import response lists only the stage the customer is on. The customer agreement belongs to a later stage, and it is not in the list yet. An agreement sent together with the occupation answers is accepted with a `202`, then refused in the background. See [Requirements unlock in stages](/v2/guides/onboarding#requirements-unlock-in-stages).
</Warning>

## Importing

<CodeGroup>
  ```bash Sandbox theme={null}
  curl -X POST https://api.sand.etherfuse.com/organization/<organization_uuid>/verification/import \
    -H "Authorization: <api_key>" \
    -H "Content-Type: application/json" \
    -d '{ "shareToken": "_act-sbx-jwt-eyJhbGciOi..." }'
  ```

  ```bash Production theme={null}
  curl -X POST https://api.etherfuse.com/organization/<organization_uuid>/verification/import \
    -H "Authorization: <api_key>" \
    -H "Content-Type: application/json" \
    -d '{ "shareToken": "_act-jwt-eyJhbGciOi..." }'
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "inProgress",
  "requirements": [
    { "type": "personalData",     "status": "awaitingReview", "requiresLaunch": false },
    { "type": "identityDocument", "status": "awaitingReview", "requiresLaunch": false },
    { "type": "occupation",       "status": "pending",        "requiresLaunch": false },
    { "type": "selfie",           "status": "awaitingReview", "requiresLaunch": true  }
  ]
}
```

This response describes the identity stage only. `proofOfAddress` and `customerAgreement` are not listed yet, even when the customer will need them.

## What carries across

| Carries across | Does not carry across |
| - | - |
| Personal data (name, date of birth, tax id, address, country) | The **occupation questionnaire** |
| **Identity documents** | Any **region-specific documents** |
| The **selfie / liveness** check | The **customer agreement** |
| A **proof of address**, if your applicant has one. It must still meet ours, including the three-month issue date. | |

<Warning>
  **Nothing is trusted wholesale.** Everything imported is re-checked against Etherfuse's own requirements. A session approved in your account is *not* automatically approved in ours.
</Warning>

## Error handling

The endpoint's full response codes are on its [API reference page](/v2/api-reference/kyc/import-a-verified-session). Errors are [problem details](/v2/errors); the messages below appear in `detail`. Requirement and overall statuses are in [Tracking verification status](/v2/guides/onboarding#tracking-verification-status).

| What you see | Meaning | What to do |
| - | - | - |
| `400`, message from the provider | The share token is expired, already spent, created for someone else, or shares nothing our requirements need. | Create a new share token. A spent one cannot be reused. |
| `400` `This customer's country is not supported for verification` | Nothing was created and the share token was **not** spent. | |
| `400` `This customer has no email on file` | The customer was created without `userInfo.email`. | Supply it, then import. |
| `409` `verification has already started` | A session can only be imported before verification begins. | Import into a fresh customer. Talk to us if you need to move one that has already started. |
| Everything reads `awaitingReview` | Expected. Nothing is reviewed until the stage is submitted, so freshly imported documents carry no verdict. | Nothing. Don't re-send. |
| `202` for the agreement, then a `kycUpdated` with `needsWork: true` | The agreement was sent before the customer reached its stage, so it was refused in the background. | Wait until `customerAgreement` appears in the requirements list, then send it again. |

## Sandbox

Testing this end to end needs a **second sandbox account acting as the donor**, with the same sharing configuration as production. Without one, build the rest of your integration against [KYC API](/v2/guides/kyc-api) and add the import once sharing is in place. See [Test environment](/v2/test-environment).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.