Skip to content

Live verification

Live verification consists of verifying the user’s identity remotely through a live video. This feature contributes to mitigating fraud risk while optimizing the user experience.

Gear icon

Configuration – Environment configuration by Treezor

Contact Treezor to use one of the live verification features.

Treezor relies on a live verification provider which offers two ways to verify user identity. You can use only one of these two methods.

MethodDescription
LivenessRequires a video of the end user, their identity proof, and a SEPA transfer into their Treezor Wallet as an extra validation step.
Certified video (PVID)Requires a video of the end users and their identity proof. It contains challenges for the user to complete, so no extra validation step is necessary. PVID is ANSSI-certified.

Both features use the same endpoint with a transparent behavior.

Bulb icon

Tip – The KYC live verification interface is customizable

Contact Treezor to change the colors, logo, redirection URL once the process ends, etc. More information available in the KYC Liveness implementation guide in Treezor's Support Center.

Process

Documents upload live verification
  1. You initiate a live verification for the User – /v1/users/{userId}/Kycliveness
  2. Treezor answers with the live verification URL (identification-url).
  3. You redirect the User to the identification-url.
  4. The User follows the step-by-step live verification process, hence uploading the document.
  5. Treezor keeps you informed of the documents processing with the KYC Liveness webhooks.
  6. Once the kycliveness.update webhook returns a kyc-status set to processed, you may request a KYC review:
    a. Retrieve the documents/v1/users/{userId}/Kycliveness
    b. Request a KYC review/v1/users/{userId}/Kycreview
  7. Treezor sends you the user.kycreview webhook upon validation or refusal.

Note that the live verification process may take some time.

Please don't call the /v1/users/{userId}/Kycliveness endpoint for a given user before the previous live verification is completed. When this situation occurs:

  • The newer request replaces the previous one.
  • Trying to upload documents for the first live verification results in an HTTP error.

Key attributes (webhooks)

Live verification relies exclusively on webhooks to provide you with information regarding the process:

  • kycliveness.create – Received when the end user completes (or abandons) the live verification process.
  • kycliveness.update – Received when Treezor identity verification partner completes the verification.

Below are some of the key attributes you may find in these webhooks.

AttributeTypeDescription
kyc-statusstringThe status of the live verification process. See the redirectURL query parameters.
commentstringComment from Treezor providing additional information regarding the live verification process.
reasonsarrayList of reason codes and messages indicating why the user has been refused.
See the list of reason codes below.

Reason codes (reason-code)

When using the live verification feature (either Liveness or Certified video), the kycliveness.update webhook returns the reason-code and the corresponding reason-message, providing insights on the refusal.

Some of these errors are sensitive regarding AML/CFT, please remember not to share the reasons for refusal with your end users when that’s the case.

CodeMessage
1201Applicant did not have a sufficient connexion
1301Applicant’s document video is too blurry (mostly due to too much movement but if this error persists the camera quality might be at fault)
1302Applicant has not presented the front of the document
1303Applicant has not presented the back of the document
1304Applicant hides part of the document
1305Applicant did not present a dynamic view of the document
1310Applicant’s video of their face is too blurry (mostly due to too much movement but if this error persists the camera quality might be at fault)
1311Applicant has not presented a face
1312Applicant did not show the full front view of their face
1313Applicant did not move to prove the liveness
1320Applicant performed their id verification under poor lighting conditions
1901Internal non-categorizable error
1911The received videos cannot be played
2101Applicant presented an expired document
2102Applicant presented a document which is not accepted
2103Applicant has submitted a damaged document
2201Applicant presented a photocopy of the document
2202Applicant presented the document on a screen
2301Applicant has submitted a counterfeit or falsification
2302Applicant presented a document declared as stolen or lost
2303Applicant presented the front and back of two different documents
2304Applicant is not the rightful owner of the document
2305Applicant presented another person's face
2306Applicant has altered his/her appearance
2307Applicant has digitally altered the videos
2399Generic code when a fraud has been detected within a certified identity verification
2401Applicant’s identity does not match with the expected one
2402Applicant used a device that has been technically altered
2403Applicant seems to have performed the check against his will

Initiate a live verification

Before initiating the live verification process, the User must be created with the relevant attributes (as required by Treezor Compliance).

At least the firstname, lastname, and birthday of the user must be populated, otherwise, the API call returns an HTTP 428 error.

Parameters

You can optionally override the default URL to which the user will be redirected after the live verification.

AttributeTypeDescription
redirectUrlstringThe URL to which the User will be redirected after the live verification.

Additional information is added to the defined redirect URL in the form of query parameters. This can help the end user understand why a live verification process has been aborted.

The query parameters provided with the redirectUrl are the following:

ParameterDescription
identification_idThe unique identifier of the live verification process.
statusThe status of the live verification, which in this case can be either processing in case of success or aborted for failures.
return_reasonThe reason for the live verification process abortion.
error_typeIndicates the type of error that led to the live verification process abortion.
More about the Redirect URL query parameters

If you take the following URL:

redirect_url?identification_id=123&status=aborted&return_reason=error&error_type=device_not_found

You can deduce that the identification process 123 was aborted due to an error; the device was not found (i.e., the device did not have any camera).

Here is the list of values for the query parameters:

statusreturn_reasonerror_typedescription
processingnonenoneThe user completed their verification.
abortedrefusalnoneThe user refused to perform the verification now.
abortedno_documentnoneThe user did not have their document available to them.
abortedverify_laternoneThe user refused to start the verification process.
abortedfocus-lostnoneThe user switched tabs/application while performing the id verification.
abortedconnections_issuebad_connexionThe connection was not good enough.
aborteddoc_instructions_not_followedchallenge_timeoutThe user did not follow the instruction for the document challenge.
abortedface_instructions_not_followedchallenge_timeoutThe user did not follow the instruction for the face challenge.
abortederrorbad_connexionThe connection was not good enough.
abortederrorno_SMSThe user did not receive the SMS.
abortederrorpublishError during video connection.
abortederrordevice_not_allowedThe user refused to give access to their camera.
abortederrorbrowser-not-supportedThe browser was not supported.
abortederrordevice_not_foundThe user’s device did not have any camera.
abortederrorwrong_phone_numberThe user wanted to change their phone number and were not allowed to for security reasons.

Request

You can use the following request to initiate the live verification process.

bash
curl -X POST {baseUrl}/v1/users/{userId}/kycliveness \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{"redirectUrl": "https://www.my-domain.tld"}'

Answers with a 201 HTTP Status Code and returns the identifier of the verification process and the identification-url. The latter is where the end user is to be redirected to go through the live verification process.

json
{
    "identification": {
        "identification-id": "f8048bee-3182-48dc-93e5-7eef9db77050",
        "identification-url": "https://id.ubble.ai/f8048bee-3182-48dc-93e5-7eef9db77050",
        "type": "video_certified"
    }
}

Once redirected, end users are guided through the steps for the relevant live verification feature.

Info icon

Information – The redirection link may not be supported by the end user's device

See the redirectURL query parameters to know which error is returned when this occurs.

End user live verification

Once redirected, end users are guided through the live verification steps:

  • Which differ depending on the live verification type.
  • Which documents vary depending on the country of the end user.
Click to see the KYC Liveness steps for your end users (mobile)Liveness user steps 1Liveness user steps 2Liveness user steps 3Liveness user steps 4
Click to see the Certified video steps for your end users (mobile)Certified video user steps 1Certified video user steps 2Certified video user steps 3

After the last step:

  • The user is redirected to the redirectUrl or the URL configured with Treezor.
  • Treezor sends you a kycliveness.create webhook with a kyc-status set to processing.

Retrieve the live verification document

Once you have received the kycliveness.update webhook with a kyc-status set to processed, you must retrieve the documents from the live verification provider for them to be uploaded to Treezor.

These documents include documents uploaded by the end user during the process and the live verification process synthesis document, which is either:

  • Liveness result for the liveness process (documentTypeId = 26).
  • Certified Liveness Result for the certified video process (documentTypeId = 34).

To retrieve the documents, use the following request.

bash
curl -X PUT {baseUrl}/v1/users/{userId}/kycliveness \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Answers with an HTTP 200 status code and makes the documents available for download.

Treezor sends you as many document.create webhooks as there are documents for the user’s live verification. You can make your KYC Review request only once you've received all the document creation webhooks.

Download the live verification documents

If you're eligible, you may be able to collect some of the uploaded documents whose documentTypeId allows for it.

Gear icon

Configuration – Download is not enabled by default

Please contact Treezor to request access to this feature.

Downloading a document is a 2-step process, in which you:

  1. Request the download URL
  2. Download the document within 30 seconds

Request the download URL

To request the download URL, you need the corresponding documentId (available in the document.create webhook for instance).

bash
curl -X GET {baseUrl}/v1/documents/{documentId}/download \
	--header 'Authorization: Bearer {accessToken}' \

Returns the URL to download the document, with all the necessary query parameters for the next step.

json
{
    "url": "{documentDownloadUrl}"
}

Download the document

You have 30 seconds to download the document from the moment the URL has been generated in the previous step.

bash
curl -X GET {documentDownloadUrl}

The document is returned in its initial format.

Request a KYC Review for the User

Before requesting a KYC review from Treezor, please make sure all the information and documents are properly updated for the user.

You can use the dedicated endpoint:

Warning icon

Alert – Documents must be uploaded for children users too

When there are parent-children hierarchical relationship, in most cases, the KYC Review must only be requested for the parent user. But you may need to upload Documents for the children before that. Please abide by the Treezor Compliance team recommendation for a smooth experience.

Learn more in the KYC Request article.

Endpoints

EndpointScope
/v1/users/{userId}/Kycreview
Initiate the user KYC review process
read_write
/v1/users/{userId}/Kycliveness
Initiate the user Live verification process
read_write
/v1/users/{userId}/Kycliveness
Upload the documents once the Live verification is completed.
read_write
/v1/documents/{documentId}/download
Retrieve a document download URL
read_only