/idv, but arrive with most of the work done.
Normally, the customer must complete the liveness selfie, which cannot be submitted directly over the API. If you already verified the customer on your own Sumsub level, import that session and they skip the selfie too: see Sumsub shared token.
The customer normally accepts the customer agreement themselves. If your own terms incorporate ours, you can forward their acceptance to us over the API: see the customer agreement.
The order matters
Verification runs in stages, and you can only send what the current stage asks for.- 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. ThekycUpdatedwebhook fires when it lands; send once step 2 returns arequirementslist. - After that, send only what the requirements list shows as
pending. A later stage’s requirements, such ascustomerAgreement, are not in the list until the customer reaches that stage. If you send one early, it is accepted with a202and then dropped. - The one exception is a proof of address. If you hold one, send it with the identity document, before the identity stage is submitted.
1
Submit personal data
2
Read what is being asked for
GET /organization/{organizationId}/kyc?requirements=true, after the kycUpdated webhook.3
Upload the documents being asked for
POST /organization/{organizationId}/verification/documents. Include a proof of address here if you hold one.4
Submit the questionnaire answers being asked for
5
Launch the customer for the rest
The liveness selfie, and anything else you did not send. The customer finishes the identity stage in
/idv.6
Send later stages as they appear
After each
kycUpdated, read the requirements list again. Send proofOfAddress if it appears and you did not send one, and customerAgreement if you are forwarding the customer’s acceptance.1. Submit personal data
SupplyuserInfo.email when creating the customer. An email address is required for the verification record and status notifications.
202 Accepted
POST /organization/{organizationId}/verification.
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
Read this when thekycUpdated webhook arrives. It arrives when the customer is routed and the requirement list becomes available. Without a kycUpdated subscription, poll this endpoint.
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 for this stage. Full vocabulary: Tracking verification status.
The list holds the current stage, plus anything already satisfied. customerAgreement and, when needed, proofOfAddress appear only once the identity stage clears. Read the list again after each kycUpdated.
3. Upload documents
multipart/form-data, with files sent as files. Nothing is base64-wrapped into JSON.
tax_document here too, where the customer’s country requires one. See Country-specific requirements.
A proof of address can go in the same request, even though it has its own later stage. We hold it for that stage, and it is used only if the identity document turns out to carry no address. This works only until the identity stage is submitted. After that, wait for proofOfAddress to appear in the requirements list, then send it on its own.
Every part, the accepted document types, and the file limits: POST /organization/{organizationId}/verification/documents.
4. Submit the questionnaire answers (optional)
Questions only. Documents, including a region’s tax document, go through step 3. Answer them here if you already hold the answers. Anything you leave out, the customer answers in/idv.
Each submission names the questionnaire it answers in type:
Occupation
Send
type. If it names a questionnaire that doesn’t exist, the request is rejected and the error tells you which names are valid.industry is a code you have to look up. GET /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 and does not leave the requirement outstanding.
The customer agreement
Your customer has to accept the Etherfuse customer agreement before they can transact. By default they accept it themselves in/idv. Send type: "agreement" only if your own terms incorporate ours and you already collected their acceptance.
acceptTerms must be true. It is your affirmation of the declaration above.
signatureName is the name the customer typed to sign, in their own words. It is printed on their agreement in a cursive face, so it appears as the signature on the executed document. Up to 255 characters.
signatureDate is when the customer accepted, YYYY-MM-DD. It is printed on their agreement as the date of signature. It should be within one day of today’s date.
5. Launch the customer
Launch into/idv exactly as in the hosted flow. The customer is shown only what’s left: the liveness selfie and any questionnaire you did not answer in step 4.
Once they finish the identity stage, the later stages follow in the same session: the proof of address if one is needed and was not already sent, then the customer agreement. If you forward the agreement yourself, watch for customerAgreement to appear in the requirements list and send it then.
Error handling
Each endpoint’s full response codes are on its API reference page. Errors are problem details; the messages below appear indetail. Requirement and overall statuses are in Tracking verification status. What follows is what actually bites in this flow.
Sandbox
The document checks don’t run, so document content isn’t scrutinised: 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. Mexico’s RFC registry check still runs in sandbox. The sandbox registry returns a single test person, so send"firstName": "LETICIA" and "lastName": "HERNANDEZ GONZALEZ" for a Mexican customer. Any other name is rejected.