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

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:

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

Create the customer's organization

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

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.

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

Any questionnaire you did not answer over the API, plus email confirmation or liveness if the shared session did not 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 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 `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

KYB

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