KYC WebSDK

The default flow. You create the customer and launch them; the customer does everything else in the widget at /idv.

The flow

Create the customer's organization

Create a personal organization with POST /organization. You generate the id. This UUID is the customer’s organization id, the organizationId you use everywhere else.

curl -X POST https://api.sand.etherfuse.com/organization \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<customer_uuid>",
    "displayName": "Ana Ejemplo",
    "accountType": "personal",
    "userInfo": {
      "email": "[email protected]",
      "displayName": "Ana Ejemplo"
    }
  }'

curl -X POST https://api.etherfuse.com/organization \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<customer_uuid>",
    "displayName": "Ana Ejemplo",
    "accountType": "personal",
    "userInfo": {
      "email": "[email protected]",
      "displayName": "Ana Ejemplo"
    }
  }'

Send userInfo.email. An email address is required for the customer’s verification record and status notifications. A customer with no email on file cannot start verification.

Launch the customer into /idv

An Identity verification launch, using JWT User Authentication.

<form method="POST" action="https://sandbox.etherfuse.com/auth/launch">
  <input type="hidden" name="grant_type" value="urn:ietf:params:oauth:grant-type:jwt-bearer" />
  <input type="hidden" name="assertion" value="<verification_scoped_jwt>" />
  <input type="hidden" name="target" value="/idv" />
</form>

The JWT sub MUST equal the org id from step 1. Any other sub registers a brand-new person instead, and the verification won’t attach to your customer.

Append &lang=es to the target (/idv?lang=es) for Spanish. Pass an optional return_url on the launch to send the customer back to your app when they finish.

The customer completes the steps in the widget

Everything in the Requirements List, plus any country-specific requirement, in one authenticated session. The widget takes them through the stages in order, so you send nothing. The customer can leave and come back; progress is kept.

Watch for the result

A kycUpdated webhook arrives with kyc.approved: true, and the customer can now get quotes and create orders. Subscribe with POST /webhook_subscription and eventType: "kycUpdated"; see Webhooks. See Tracking verification status.

Error handling

Failures specific to launching. Verification outcomes (denied, needs-work) are in Tracking verification status; a rejected customer is resubmitted by launching them again.

What you see	Meaning	What to do
The launch never reaches `/idv`	The JWT was rejected: wrong scope, expired, bad signature, or an unrecognized `target`.	See Authentication errors.
The customer lands in `/idv` as a new person	The JWT `sub` wasn’t the org `id`.	Sign a new JWT with `sub` = the org `id`. Don’t reuse the old session.
The liveness scan never starts in an iframe	Camera permission. The bare `allow="camera"` grants only the iframe’s own origin, but the scan runs from a nested frame.	Set `allow="camera ; microphone "` on the iframe. A top-level tab or popup needs nothing extra.

Sandbox

The document checks don’t run, so any document images and any selfie will pass. Mexico’s RFC check does run: a Mexican customer must enter first name CARLOS, last name RAMIREZ LOPEZ and RFC HEGL900101AB6, plus any CURP in the right format. Every sandbox customer is also asked for a proof of address, because sandbox reads identity documents as test data with no address; any image passes. See Country-specific requirements and Test environment.

Get Started

Migration

Concepts

User Authentication

Integration Guides

KYC

KYB

Blockchains

Resources

The flow

Error handling

Sandbox

When to reach for something else

KYC API

Sumsub shared token

​The flow

​Error handling

​Sandbox

​When to reach for something else

KYC API

Sumsub shared token

The flow

Error handling

Sandbox

When to reach for something else