KYC Sumsub Shared Token

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 mint a share token, we import the session, and the customer’s identity data, documents and liveness come with it. In practice the customer is launched once and signs only the customer agreement.

This page names the underlying verification provider because the shared-token flow cannot be described without it: you mint the 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:

You verify customers on your own Sumsub level.
A one-time data-sharing agreement is signed with Sumsub, by both parties.
Etherfuse is added as a sharing partner in your Sumsub dashboard, and you in ours.
The account minting tokens holds the “Share applicants data” permission.

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

The flow

Create the customer's organization

A personal org, as in any other flow. See KYC WebSDK. Send userInfo.email: the import uses it.

Mint a share token in your Sumsub account

For the applicant you already verified, targeting Etherfuse’s client id. Tokens are short-lived and single-use.

Import the session

POST /ramp/customer/{customer_id}/verification/import

Push what the shared session didn't carry

The questionnaire answers through POST /ramp/customer/{customer_id}/verification/questionnaire, and any region-specific document through POST /ramp/customer/{customer_id}/verification/documents.

Launch the customer for what remains

The customer agreement, plus email confirmation or liveness if the shared session didn’t cover them.

Importing

curl -X POST https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/verification/import \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "shareToken": "_act-sbx-jwt-eyJhbGciOi..." }'

curl -X POST https://api.etherfuse.com/ramp/customer/<customer_uuid>/verification/import \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "shareToken": "_act-jwt-eyJhbGciOi..." }'

200 OK

{
  "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "in_progress",
  "requirements": [
    { "type": "personal_data",      "status": "awaiting_review", "requiresLaunch": false },
    { "type": "identity_document",  "status": "awaiting_review", "requiresLaunch": false },
    { "type": "occupation",         "status": "pending",         "requiresLaunch": false },
    { "type": "email_confirmation", "status": "satisfied",       "requiresLaunch": true  },
    { "type": "selfie",             "status": "awaiting_review", "requiresLaunch": true  }
  ]
}

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
Email verification, when your level collected it

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.

Error handling

The endpoint’s full response codes are on its API reference page. Requirement and overall statuses are in Tracking verification status.

What you see	Meaning	What to do
`400`, message from the provider	The token is expired, already spent, minted for someone else, or shares nothing our requirements need.	Mint a fresh token. A spent one can’t be reused.
`400` `This customer's country is not supported for verification`	Nothing was created and the 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 `awaiting_review`	Expected. Nothing is reviewed until the stage is submitted, so freshly imported documents carry no verdict.	Nothing. Don’t re-send.

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 and add the import once sharing is in place. See Test environment.

Get Started

Concepts

User Authentication

Integration Guides

KYC

Blockchains

Resources

Prerequisites

The flow

Importing

What carries across

Error handling

Sandbox

​Prerequisites

​The flow

​Importing

​What carries across

​Error handling

​Sandbox

Prerequisites

The flow

Importing

What carries across

Error handling

Sandbox