KYC Overview

Every customer must clear identity verification before they can transact.

Choosing a flow

Flow	You submit	Customer submits
KYC WebSDK (the default)	Nothing	Everything
KYC API	Personal data, identity document, questionnaire answers, and any region-specific documents	Liveness selfie, and any questionnaire you do not answer over the API
Sumsub shared token	A share token, then questionnaire answers and any region-specific documents	Any questionnaire you do not answer over the API, plus liveness if the shared session did not cover it

Requirements List

Requirement	What satisfies it	How it can be submitted
`personalData`	Name, date of birth, tax id, country, and residential address.	WebSDK · API · Shared token
`identityDocument`	A government-issued photo ID. Any valid one works.	WebSDK · API · Shared token
`proofOfAddress`	A utility bill, bank statement, tax bill, employment certificate, property deed, or invoice, issued within the last three months. Requested only when the identity document carried no address.	WebSDK · API · Shared token
`occupation`	Job title and an occupation category.	WebSDK · API
`selfie`	A live face capture.	WebSDK · Shared token
`customerAgreement`	The customer accepting Etherfuse’s agreements.	WebSDK · API

Some countries add specific additional requirements. See Country-specific requirements. Supply userInfo.email when creating the customer. Read the overall status with GET /organization/{organizationId}/kyc.

Requirements unlock in stages

A customer does not owe every requirement at once. Verification runs in stages, and each stage asks for its own requirements. Today a customer moves through these stages in this order:

Routing. The country in their personal data decides which requirements apply. Nothing else can be sent until this lands.
Identity. personalData, identityDocument, selfie, occupation, and any country-specific requirement.
Proof of address. Only when the identity document carried no address.
Agreement. customerAgreement.

Drive your integration from the requirements breakdown, not from this list. We add and reorder stages, and some countries may gain stages of their own. The rules:

The breakdown lists only the current stage, plus requirements already satisfied. A requirement from a later stage is not in the list at all until the customer reaches that stage.
Send a requirement only once it is in the list as pending or actionRequired. If you send it earlier, the request is accepted with a 202, then refused in the background. A kycUpdated webhook arrives with needsWork: true, and nothing retries it.
A stage moves on by itself. When everything the current stage asks for has landed, it is submitted for review and the overall status becomes submitted. When the review clears, the next stage’s requirements appear in the list and status returns to inProgress. Both moves send kycUpdated. Review is usually a few seconds; a manual review takes longer.
Proof of address is the one exception. You may send it before its stage, as long as the identity stage has not been submitted yet. Send it in the same request as the identity document. It is used only if the proof of address stage is reached.

So the loop for anything you submit over the API is:

Read the breakdown

GET /organization/{organizationId}/kyc?requirements=true

Send what is pending

Everything in the list with status: "pending" or "actionRequired" and requiresLaunch: false.

Wait for the next kycUpdated

It arrives when the stage is submitted, and again when the next stage arrives. Without a kycUpdated subscription, read the breakdown again after a few seconds.

Repeat until only launch rows are left

When everything outstanding reads requiresLaunch: true, launch the customer. When nothing is outstanding, wait for status: "approved".

Tracking verification status

The overall status

curl -H "Authorization: <api_key>" \
  https://api.sand.etherfuse.com/organization/<organization_uuid>/kyc

curl -H "Authorization: <api_key>" \
  https://api.etherfuse.com/organization/<organization_uuid>/kyc

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "submitted",
  "currentRejectionReason": null,
  "selfies": [],
  "documents": [],
  "approvedAt": null,
  "needsWork": false,
  "userMessage": null
}

Status	Description
`notStarted`	No verification started
`inProgress`	Started, but not everything is submitted. Detail in `needsWork` and `userMessage`
`submitted`	Submitted, awaiting review (manual or automated)
`approved`	Cleared; the customer can transact
`denied`	A rejected verdict, or a previously-approved customer whose approval was revoked. Reason in `currentRejectionReason`

The per-requirement breakdown

Add ?requirements=true for a step-by-step account of what the customer still needs. It is opt-in: without it the response leaves requirements out.

curl "https://api.sand.etherfuse.com/organization/<organization_uuid>/kyc?requirements=true" \
  -H "Authorization: <api_key>"

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "inProgress",
  "currentRejectionReason": null,
  "selfies": [],
  "documents": [],
  "approvedAt": null,
  "needsWork": false,
  "userMessage": null,
  "requirements": [
    { "type": "personalData",      "status": "satisfied", "requiresLaunch": false },
    { "type": "identityDocument",  "status": "satisfied", "requiresLaunch": false },
    { "type": "occupation",        "status": "pending",   "requiresLaunch": false },
    { "type": "selfie",            "status": "pending",   "requiresLaunch": true  }
  ]
}

This customer is on the identity stage. customerAgreement is not in the list yet, so it cannot be sent yet. Once the identity stage clears, the same call returns:

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "inProgress",
  "currentRejectionReason": null,
  "selfies": [],
  "documents": [],
  "approvedAt": null,
  "needsWork": false,
  "userMessage": null,
  "requirements": [
    { "type": "personalData",      "status": "satisfied", "requiresLaunch": false },
    { "type": "identityDocument",  "status": "satisfied", "requiresLaunch": false },
    { "type": "occupation",        "status": "satisfied", "requiresLaunch": false },
    { "type": "selfie",            "status": "satisfied", "requiresLaunch": true  },
    { "type": "customerAgreement", "status": "pending",   "requiresLaunch": false }
  ]
}

Each type matches a requirement in the Requirements List or a country-specific one. requiresLaunch: true marks the rows only the WebSDK can satisfy.

requirements is absent until the customer has been routed to their country’s requirements, so it is missing immediately after their personal data is submitted. Read it again a moment later. After that it grows as the customer moves through the stages: proofOfAddress and customerAgreement appear only when their stage is reached. Re-read it after every kycUpdated; no single response is the full list.

We reserve the right to add new requirements, and will update these docs when we do. Some countries may also gain requirements of their own.

Requirement statuses

`status`	Meaning	What to do
`satisfied`	Accepted.	Nothing.
`pending`	The current stage asks for this, and nothing has been provided yet.	Supply it.
`awaitingReview`	Provided, not yet reviewed.	Wait.
`actionRequired`	Reviewed and rejected.	Send it again, corrected.

Country-specific requirements

🇲🇽 Mexico

Requirement	What satisfies it	How it can be submitted
`taxDocument`	The Constancia de Situación Fiscal, the tax-status document issued by SAT.	WebSDK · API

It must be legible and belong to the customer being verified. Submit it as the tax_document part of POST /organization/{organizationId}/verification/documents, or let the customer upload it in the widget.

In sandbox, the constancia is the one document that has to look real. Any real constancia with any data in it works. Use this example constancia.In sandbox, the customer’s name must be LETICIA HERNANDEZ GONZALEZ. The RFC registry check still runs, and the sandbox registry returns only this test person. Any other name is rejected.

Reference

Show Payment accounts

After verification is approved, register bank accounts and wallets as payment accounts with POST /organization/{organizationId}/payment_account. Payment accounts belong to the organization in the route. Use your own organization’s id from GET /me, or a customer organization’s id from POST /organization or GET /organizations. See Organizations in the route. A bank account route needs account holder details under registrationInfo, such as accountHolderName and taxId. We fill each field from that organization’s verified identity when we hold it, so you do not send KYC data again. To register a customer’s bank account, pass the customer’s organization id.To learn which fields you still need before you register, call GET /organization/{organizationId}/payment_account/requirements with the same organization id, kind, country, currency and accountDetails.kind you plan to register:

curl -H "Authorization: <api_key>" \
  "https://api.sand.etherfuse.com/organization/$ORGANIZATION_ID/payment_account/requirements?kind=bank&country=MX&currency=MXN&accountDetailsKind=clabe"

{
  "accountDetails": {
    "kind": "clabe",
    "required": ["#/accountDetails/clabe"]
  },
  "registrationInfo": {
    "required": ["#/registrationInfo/accountHolderName", "#/registrationInfo/taxId"],
    "missing": ["#/registrationInfo/taxId"]
  }
}

required lists every field the route needs. missing lists the ones we hold no verified value for. Ask the customer only for the missing fields and send them under registrationInfo. If you already collect more fields, you can send them all; we ignore the ones this route does not use.If you register without a field we need, we return 422 registration-info-required with the same required and missing lists. Add the missing fields and send the request again. A taxId you send must match the verified one, or we return 422 holder-tax-id-mismatch.A new account reports its readiness per rail and direction in rails. You can quote a direction once its status is ready. Read the account with GET /organization/{organizationId}/payment_account/{id}, or subscribe to paymentAccountUpdated to receive the account when it changes. See Overview for the full flow.

Show Webhooks

Subscribe to kycUpdated events with POST /webhook_subscription to receive status updates. See Webhooks for setup and signature verification, and kycUpdated for the payload.Approved:

{
  "event": "kycUpdated",
  "eventId": "0d6f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "occurredAt": "2026-09-29T19:00:00Z",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "kyc": { "status": "approved", "approved": true, "needsWork": false, "userMessage": null }
}

Needs work:

{
  "event": "kycUpdated",
  "eventId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
  "occurredAt": "2026-09-29T19:05:00Z",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "kyc": {
    "status": "inProgress",
    "approved": false,
    "needsWork": true,
    "userMessage": "Please upload a current government-issued ID."
  }
}

Business customers get kybUpdated instead, with kyb: { status, approvedAt }. See kybUpdated.

Show Data isolation

Partners can only access KYC data they submitted:

Accessor	Data Visibility
Partner (via API key)	Only data where `source_organization_id` matches their org
Wallet Owner	All data for their wallet
Admin	All data

This prevents partners from accessing PII submitted by other partners or directly by users.

Get Started

Migration

Concepts

User Authentication

Integration Guides

KYC

KYB

Blockchains

Resources

Choosing a flow

Requirements List

Requirements unlock in stages

Tracking verification status

The overall status

The per-requirement breakdown

Requirement statuses

Country-specific requirements

Reference

​Choosing a flow

​Requirements List

​Requirements unlock in stages

​Tracking verification status

​The overall status

​The per-requirement breakdown

​Requirement statuses

​Country-specific requirements

​Reference

Choosing a flow

Requirements List

Requirements unlock in stages

Tracking verification status

The overall status

The per-requirement breakdown

Requirement statuses

Country-specific requirements

Reference