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:

GET /v1/attributes/{*attribute_key*}/definitions/

Document

Document that the client must upload.

First upload the file(s):

POST /v1/documents/files/

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):

POST /v1/documents/

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:

  1. Getting an URL leading your customers to https://sumsub.com/ which will guide them through liveness check process.

    attribute_key: sumsub_liveness_check_url

  2. 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:

POST /v1/verification-codes/

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.