/idv, but arrive with most of the work done.
Normally, the customer must confirm their email and complete the liveness selfie. Neither can 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
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 a409. The kyc_updated webhook fires when it lands; send once step 2 returns a requirements list.
1
Submit personal data
2
Read what is being asked for
3
Upload the documents being asked for
4
Submit the questionnaire answers
5
Launch the customer for the rest
Email confirmation, the liveness selfie, and any questionnaire you did not answer over the API.
1. Submit personal data
202 Accepted
POST /ramp/customer/{customer_id}/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
Triggered by thekyc_updated webhook rather than a timer, where you can: it fires when the customer is routed and the requirement list becomes available.
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.
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 (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 /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.
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: email confirmation, the liveness selfie, and any questionnaire you did not answer in step 4.