KYC API

Push identity data and documents you already hold over the API, so the customer isn’t asked for them twice. They are still launched into /idv, but arrive with most of the work done. Three requirements always remain the customer’s: confirming their email, the liveness selfie, and accepting the customer agreement. There is no API for those. For a flow where the customer only signs the agreement, see Sumsub shared token.

The order matters

Personal data comes first. A customer’s requirements are assigned from the country you send, and that assignment is asynchronous, so documents and answers sent before it lands are refused with a 409. The kyc_updated webhook fires when it lands; send once step 2 returns a requirements list.

Submit personal data

POST /ramp/customer/{customer_id}/verification

Read what is being asked for

GET /ramp/customer/{customer_id}/kyc?requirements=true

Upload the documents being asked for

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

Submit the questionnaire answers

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

Launch the customer for the rest

Email confirmation, the liveness selfie, and the customer agreement.

These endpoints answer 202 Accepted, not 200 OK. A 202 means “accepted and being applied”, not “done”. Never treat it as proof that a requirement is satisfied: learn that from the kyc_updated webhook or the requirements breakdown.

1. Submit personal data

curl -X POST https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/verification \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ana",
    "lastName": "Ejemplo",
    "dateOfBirth": "1990-01-01",
    "taxId": "XAXX010101000",
    "country": "MEX",
    "address": {
      "street": "Av. Reforma 100",
      "city": "Ciudad de Mexico",
      "region": "CDMX",
      "postalCode": "06600",
      "country": "MEX"
    }
  }'

curl -X POST https://api.etherfuse.com/ramp/customer/<customer_uuid>/verification \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ana",
    "lastName": "Ejemplo",
    "dateOfBirth": "1990-01-01",
    "taxId": "XAXX010101000",
    "country": "MEX",
    "address": {
      "street": "Av. Reforma 100",
      "city": "Ciudad de Mexico",
      "region": "CDMX",
      "postalCode": "06600",
      "country": "MEX"
    }
  }'

202 Accepted

{
  "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "in_progress"
}

Every field, its format, and whether it is required: POST /ramp/customer/{customer_id}/verification.

Send only an address that matches the identity document you upload. The two are cross-checked. An address, date of birth, or name that contradicts the document holds the customer up for review instead of approving them.

Re-submitting overwrites what you sent before and is safe. It never moves the customer’s review status on its own.

2. Read what is being asked for

Triggered by the kyc_updated webhook rather than a timer, where you can: it fires when the customer is routed and the requirement list becomes available.

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

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

requiresLaunch: false is yours to send; true can only be done by the customer. When everything outstanding reads true, you have nothing left to send. Full vocabulary: Tracking verification status.

3. Upload documents

multipart/form-data, with files sent as files. Nothing is base64-wrapped into JSON.

curl -X POST https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/verification/documents \
  -H "Authorization: <api_key>" \
  -F id_type=ID_CARD \
  -F [email protected] \
  -F [email protected]

curl -X POST https://api.etherfuse.com/ramp/customer/<customer_uuid>/verification/documents \
  -H "Authorization: <api_key>" \
  -F id_type=ID_CARD \
  -F [email protected] \
  -F [email protected]

Send tax_document here too, where the customer’s country requires one. See Country-specific requirements. Every part, the accepted document types, and the file limits: POST /ramp/customer/{customer_id}/verification/documents.

4. Submit the questionnaire answers

Questions only. Documents, including a region’s tax document, go through step 3. Each submission names the questionnaire it answers in type:

`type`	Answers	Applies to
`occupation`	`jobTitle`, `industry`	Every customer

curl -X POST https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/verification/questionnaire \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "occupation",
    "jobTitle": "Software Engineer",
    "industry": "4430200"
  }'

curl -X POST https://api.etherfuse.com/ramp/customer/<customer_uuid>/verification/questionnaire \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "occupation",
    "jobTitle": "Software Engineer",
    "industry": "4430200"
  }'

Send type even though there is one value. More questionnaires may be added, and a request naming one that doesn’t exist is rejected listing the ones that do, rather than being applied to the wrong questionnaire. The customer agreement is a questionnaire too and will never appear here: consent is collected from the customer in /idv.

industry is a code you have to look up. GET /ramp/verification/occupations returns every accepted value as { code, label }. Submit the code: the label is display copy, can be reworded, and is not accepted. An unrecognized code is refused with a 400 naming it, so a typo fails at the request rather than leaving the requirement quietly outstanding.

{
  "occupations": [
    { "code": "1000000", "label": "NOT APPLICABLE" },
    { "code": "4430200", "label": "INFORMATION TECHNOLOGY - IT PROGRAMMING ENGINEERS OR TECHNICIANS" }
  ]
}

5. Launch the customer

Launch into /idv exactly as in the hosted flow. The customer is shown only what’s left: email confirmation, the liveness selfie, and the customer agreement.

Error handling

Each endpoint’s full response codes are on its API reference page. Requirement and overall statuses are in Tracking verification status. What follows is what actually bites in this flow.

What you see	Meaning	What to do
`409` `Submit this customer's personal data first`	Step 1’s `202` returns before the customer has a verification profile, so a document or questionnaire call in that window has no stage to land on.	Wait for the requirements breakdown to appear, normally well under a second, then send.
`409` `has not been routed to their country's requirements yet`	Step 1 landed, but the stages that hold documents and questions are assigned from the country you sent, and that assignment is asynchronous.	Wait for the `kyc_updated` webhook (`not_started` to `in_progress`), then re-read step 2 and send. With no webhook registered, read step 2 until the requirements list appears.
`202`, but the requirement stays `pending`	Steps 1, 3 and 4 validate your request, answer `202`, then apply it in the background, and that background work failed. The usual cause is a document sent before its stage was reached.	A `kyc_updated` webhook arrives with `needsWork: true` and a `userMessage` naming what to send again, and `status` unchanged. Nothing retries on our side, so send it again. For documents send every part in the same request: one side of a two-sided document is refused on its own. That webhook is the only place the message appears, so without one registered, re-read the requirements list and re-send what is still outstanding.
`202`, then the customer stalls in review	The personal data contradicts the document it was cross-checked against.	Re-submit personal data matching the document, or upload the document that matches.
`409` `already approved` / `already denied`	Concluded verifications can’t be written to.	A denied customer resubmits by being launched into `/idv`.

Sandbox

The verification checks don’t run, so document content isn’t scrutinised and registry checks are skipped: a placeholder image is accepted where production would reject it. Everything else is identical, including the submission order and the conditional proof-of-address stage. See Test environment.

Get Started

Concepts

User Authentication

Integration Guides

KYC

Blockchains

Resources

The order matters

1. Submit personal data

2. Read what is being asked for

3. Upload documents

4. Submit the questionnaire answers

5. Launch the customer

Error handling

Sandbox

​The order matters

​1. Submit personal data

​2. Read what is being asked for

​3. Upload documents

​4. Submit the questionnaire answers

​5. Launch the customer

​Error handling

​Sandbox

The order matters

1. Submit personal data

2. Read what is being asked for

3. Upload documents

4. Submit the questionnaire answers

5. Launch the customer

Error handling

Sandbox