KYC Flow¶
Get client’s KYC level¶
GET /v1/clients/kyc-level-info/
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }The response will help you understand whether a KYC application can be created (allowed_to_create_kyc_application) and what KYC levels a client can receive (available_levels_for_upgrade), as well as the UUID of the last KYC application (last_kyc_application_uuid).
Create KYC application¶
POST /v1/clients/kyc-level-info/
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }data = { "kyc_level_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }In response, you will receive an KYC questionnaire that the client will have to fill out.
Update KYC application¶
PATCH /v1/kyc/{*kyc_application_uuid*}/
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }data = { "attribute_changes": [ "key": "string", "value": "string" ] }The KYC questionnaire can be filled out in parts or all at once.
Using the KYC questionnaire, client attributes are filled in. Client attributes have a specific type. Let’s talk about some of them:
Reference data¶
Attribute with selection from a list.
Get attribute definitions:
Legal document¶
Legal document that the client must read.
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_type": "individual", "key": "string" }The attribute value must contain the legal document UUID.
Document¶
Document that the client must upload.
First upload the file(s):
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }files = {}Then create a document based on the previously uploaded file(s):
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }data = { "attribute_key": "string", "files": [] }Put the response in the attribute value.
Attribute Keys for documents:
passport
id_card_front_side
id_card_back_side
driver_license_front_side
driver_license_back_side
residence_permit_license_front_side
residence_permit_license_back_side
proof_of_address
proof_of_funds
In case the document is single-sided, please send its “back side” also, but use any picture for this. For instance the one you used as “front side”.
SumSub liveness check¶
- Some KYC levels need SumSub liveness Check. There are 2 ways of passing this:
Getting an URL leading your customers to https://sumsub.com/ which will guide them through liveness check process.
attribute_key: sumsub_liveness_check_url
Getting a token allowing you to embed SumSub widget on your web page by following this instruction https://docs.sumsub.com/docs/get-started-with-web-sdk#standalone-example-of-websdk-initialization .
attribute_key: sumsub_liveness_check_token
In the both cases your customers will be asked to turn on their camera in order to make some photos.
GET /v1/kyc/{*kyc_application_uuid*}/
query = { "empty_volatile_fields": false, "sumsub_liveness_check_token.ttl_min": 600, "sumsub_liveness_check_token.ttl_max": 3600, "sumsub_liveness_check_token.ttl_renew": false } response = { kyc_steps[] -> "title": "Liveness check" -> questions[] -> "title": "SumSub liveness check token" -> attribute -> { "value": "accessToken", "additional_info" { "email": "email", "phone": "phone" }, ... } }GET /v1/kyc/{*kyc_application_uuid*}/attributes/{attribute_key}/
path = { "attribute_key": "sumsub_liveness_check_token" } query = { "ttl_min": 600, "ttl_max": 3600, "ttl_renew": false, ... } response = { "value": "accessToken", "additional_info" { "email": "email", "phone": "phone" }, ... }We recommend refreshing token with ‘ttl_renew=true’ whenever SumSub stops accepting it.
Note: Each Liveness access token is bound to a particular customer and cannot be used by other customers(even if the corresponding email/phone are provided).
Client signature¶
Some attributes require the client’s signature. Such attributes have a ‘sign_providers’ field, by which you can select the desired signature type.
Send verification code:
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", ... }data = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "object_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "provider_type": "sms", "destination": "string" }In object_uuid you need to put kyc_application_uuid. The destination field must be filled in when a client first enters or changes a phone number.
Therefore, you may need to add the following query parameters to the KYC application update request:
query = { ..., "email_sign_code": "string", "sms_sign_code": "string" }Note: If you are sending multiple attributes with the same signature type in a single KYC application update request, then one signature code is sufficient. The signature code on the sandbox is 111111.
Send KYC application to review¶
POST /v1/kyc/{*kyc_application_uuid*}/send-to-review/
query = { "legal_entity_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "client_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }Sending a KYC application to review may also require a client signature.
Get KYC application review result¶
If you receive a pending status, KYC application will need to be corrected using the instructions for Update KYC application step and sent again to review. The rejected status is final and a new KYC application will need to be created.
GET /v1/kyc/{*kyc_application_uuid*}/
For some documents it is possible to retrieve SumSub document diagnostics as:
response = { kyc_steps[] -> "title": "Liveness check" -> questions[] -> "title": "SumSub liveness check token" -> attribute -> value -> { "verification": { "sumsub": { "verificator": "sumsub", "status": "ignored", "client_note": "There is no available data to recognize from image" } } } }Note: The developer’s application on the sandbox provides a function for changing the status of the KYC application.