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 /organization/{organizationId}/verification/import 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.

Push what the import response lists as pending

Usually the occupation answers, through POST /organization/{organizationId}/verification/questionnaire, and any region-specific document through POST /organization/{organizationId}/verification/documents. Send only these. When the last one lands, the identity stage is submitted for review.

Wait for the next stage

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

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. Repeat the previous step after each one.

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.

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.

Importing

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" } }'

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.

200 OK

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

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. Errors are problem details; the messages below appear in detail. 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.
`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`.
`200`, then `personalData` stays `pending` for a Mexican customer	We could not save the CURP you sent.	Launch the customer 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 and add the import once sharing is in place. See Test environment.

Get Started

Migration

Concepts

User Authentication

Integration Guides

KYC

KYB

Blockchains

Resources

Prerequisites

The flow

Importing

What carries across

Importing again

Error handling

Sandbox

​Prerequisites

​The flow

​Importing

​What carries across

​Importing again

​Error handling

​Sandbox

Prerequisites

The flow

Importing

What carries across

Importing again

Error handling

Sandbox