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

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

**1. Create the customer's organization**

A `personal` org, as in any other flow. See [KYC WebSDK](https://docs.etherfuse.com/v2/guides/kyc-websdk.md#the-flow). Send `userInfo.email`: the import uses it.

**2. 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.

**3. Import the session**

[`POST /organization/{organizationId}/verification/import`](https://docs.etherfuse.com/v2/api-reference/kyc/import-a-verified-session)
For a Mexican customer, send the CURP in `additionalInfo.curp` on this call. Sumsub does not copy custom fields when an applicant is shared, so the CURP on your level does not reach us.

**4. Push what the import response lists as pending**

Usually the `occupation` answers, through [`POST /organization/{organizationId}/verification/questionnaire`](https://docs.etherfuse.com/v2/api-reference/kyc/submit-a-verification-questionnaire), and any [region-specific document](https://docs.etherfuse.com/v2/guides/onboarding.md#country-specific-requirements) through [`POST /organization/{organizationId}/verification/documents`](https://docs.etherfuse.com/v2/api-reference/kyc/upload-verification-documents). Send only these. When the last one lands, the identity stage is submitted for review.

**5. Wait for the next stage**

A [`kycUpdated`](https://docs.etherfuse.com/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`](https://docs.etherfuse.com/v2/api-reference/kyc/get-kyc-status).

**6. 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](https://docs.etherfuse.com/v2/guides/kyc-api.md#the-customer-agreement). Repeat the previous step after each one.

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

> [!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](https://docs.etherfuse.com/v2/guides/onboarding.md#requirements-unlock-in-stages).

## Importing

```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...", "additionalInfo": { "curp": "XEXX010101HNEXXXA4" } }'
```

```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...", "additionalInfo": { "curp": "XEXX010101HNEXXXA4" } }'
```

Leave out `additionalInfo` for a customer outside Mexico.

```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. | Custom fields on your level, including a Mexican customer's **CURP**. Send it in `additionalInfo.curp` on the import. |

> [!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.

## Importing again

If a customer's verification has not reached review, you can import a new share token into the same customer. We replace their earlier verification with the new one. Use this when an earlier import left documents missing, or when the customer's verification was reset.

Once the customer is approved, denied, or in review, the import returns `409` and keeps the verification they have. In rare cases our verification provider won't let us replace a verification that hasn't reached review either. The import then returns `409` too.

## Error handling

The endpoint's full response codes are on its [API reference page](https://docs.etherfuse.com/v2/api-reference/kyc/import-a-verified-session.md). Errors are [problem details](https://docs.etherfuse.com/v2/errors.md); the messages below appear in `detail`. Requirement and overall statuses are in [Tracking verification status](https://docs.etherfuse.com/v2/guides/onboarding.md#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. |
| `400` `additionalInfo.curp must contain 18 letters or digits` | The CURP is malformed. Nothing was created and the share token was **not** spent. | Fix the CURP, then import. |
| `503` `service-unavailable` | Usually we could not reach our verification provider, and nothing was imported. | Retry the import. If the retry returns a `400` saying the share token was already used, the first import may have landed. Contact us with the `organizationId`. |
| `200` with no `requirements` | The session was imported, but we could not read what the customer still needs. | Read [`GET /organization/{organizationId}/kyc?requirements=true`](https://docs.etherfuse.com/v2/api-reference/kyc/get-kyc-status). |
| `200`, then `personalData` stays `pending` for a Mexican customer | We could not save the CURP you sent. | [Launch the customer](https://docs.etherfuse.com/v2/guides/kyc-websdk.md) to enter their CURP. |
| `409` `verification is approved, denied, or in review` | A new session can only replace a verification that has not reached review. Nothing was imported and the share token was **not** spent. | Wait for the review to finish. Talk to us if you need to change a customer who is approved or denied. |
| `409` `won't let a new session replace this customer's verification` | Our verification provider refused to replace the customer's earlier verification. Nothing was imported and the share token was **not** spent. Retrying returns the same `409`. | Don't retry. Contact us with the `organizationId`. |
| 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](https://docs.etherfuse.com/v2/guides/kyc-api.md) and add the import once sharing is in place. See [Test environment](https://docs.etherfuse.com/v2/test-environment.md).


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