Face Validation via API

Learn how to perform a Face Validation using our API, understanding the essential API endpoints, responses and errors.

Prerequisites

Before you begin, make sure you have the following:

1. Truora API-Key: This key grants access to our services. If you don’t have one already, set up an account and then go to Authentication to obtain your Truora API-key.

2. Media Files: You will need a reference image to perform user enrollment and a selfie or video for the face recognition.

Note: If you are also implementing Document Validation, we suggest using the front side of the document as the reference image for user enrollment.

3. Postman: Use Postman or any other collaboration tool for API development. Although it is not required to perform the integration, it will help perform tests along the way.

Truora provides a Postman collection online that includes the necessary tools to simplify the testing process.

https://www.postman.com/truora-api-docs/workspace/truora-api-docs/collection/26510995-ad2e7c71-b39a-40e4-8322-ae3316160634?ctx=documentation

Copied

1. Create enrollment

Setup main Request Headers and Body

To configure the main request headers and body, follow these steps:

1. Create a POST request to the endpoint https://api.validations.truora.com/v1/enrollments.

2. Set the Headers

   • Truora-API-Key: enter the value obtained in the step of get Truora API-key.
   • Content-Type: the value should be application/x-www-form-urlencoded.

3. Set required values for the request body

   • type [Required]: Indicates the type of validation to be performed. Set this value to face-recognition
   • user_authorized [Required]: This indicates that you have the authorization of the person to be verified. This is mandatory in order to comply with data protection laws. Value must be set to true in order to perform the validation.
   • account_id [Optional]: The account_id is a unique value assigned to each user in the system to distinguish them and access their information and processes. Only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. Please go to Create an Account ID to learn more about it.
   • confirmation [Optional]: Allowed: none. Used to specify the creation of enrollment that does not require an identity validation to complete. Set as none to skip the required validation. If omitted, the enrollment will require the normal validation process to be successful.*

   *Note 1: To use the confirmation parameter your company’s account must be authorized. To request authorization, please contact our Support Team. This authorization will affect only your Truora-API-Keys created after the approval.
   
   *Note 2: If your company requires this functionality, read the next section Enrollment without validation to learn about this special process.

Please be aware that the Create Enrollment endpoint will not allow the creation of an enrollment for an account that already has an associated enrollment.

Send the Create enrollment request you just created, and you will receive a response similar to the following:

{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-04-23T15:33:28.544161454Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "reason": "waiting_file_upload",
    "status": "pending",
    "update_date": "2024-04-23T15:33:28.544161536Z",
    "validation_type": "face-recognition",
    "file_upload_link": "https://files.truora.com/..."
}

Note:

• Enrollment status will initially be pending with the reason set to waiting_file_upload until the reference image is successfully uploaded in the next step. Once the image is uploaded, the status will remain pending, but the reason will change to waiting_face_validation.
• The account_id, enrollment_id and file_upload_link returned by this endpoint will be used in subsequent steps.

Enrollment without validation (auth required)

To request authorization for this feature, please contact our Support Team. This authorization will affect only your Truora-API-Keys created after the approval.

In certain scenarios, such as when migrating faces from old databases or when a known user cannot pass validation post-migration, your company may need to manage face enrollments without requiring face validation. To handle this, we offer the following solution:

1. Create Enrollment without validation: The confirmation body parameter set to none in the Create enrollment endpoint allows you to enroll faces via API without requiring face validation. This is useful for updating the database without revalidating users.

2. Delete Enrollment: This endpoint allows you to delete an existing enrollment, enabling you to manage and update face data as needed, such as in cases of picture updates, impersonation, or user data deletion requests. Visit the Delete enrollment endpoint section to learn more.

This ensures a streamlined process for managing your face database in special cases.

If you send the Create enrollment request with the body parameter confirmation set to none, then no face validation will be needed for a successful enrollment, and your response should look as follows:

{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-04-23T15:33:28.544161454Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "reason": "waiting_file_upload",
    "status": "pending",
    "update_date": "2024-04-23T15:33:28.544161536Z",
    "validation_type": "face-recognition",
    "confirmation": "none",
    "file_upload_link": "https://files.truora.com/..."
}

Note:

• Enrollment status will initially be pending with the reason set to waiting_file_upload until the reference image is successfully uploaded in the next step. Once the image is successfully uploaded, the status will change to success
• The account_id, enrollment_id and file_upload_link returned by this endpoint will be used in subsequent steps.

In case your account is not authorized, you will receive an “Insufficient permissions” message:

    {
        "code": 10403,
        "http_code": 403,
        "message": "Insufficient permissions"
    }

2. Upload reference image

The reference image must be submitted through a PUT request to the URL returned in the file_upload_link field of the previous step, selecting the Binary type in the Body. The image formats supported are: jpeg, png and webp. Maximum size is 10 MB.

After sending the PUT request you will receive a response similar to the following:

{
    "code": 10200,
    "http_code": 200,
    "message": "Successfully uploaded"
}

3. Get enrollment

The Get enrollment request checks the status of the enrollment, which can be either pending, success or failure:

Pending Status

• The status starts at pending with the reason set to waiting_file_upload, and remains that way until the image is successfully uploaded (previous step).
• After the upload, the status remains pending, but the reason changes to waiting_face_validation.

Note: After a successful upload, if the body parameter confirmation was set to none in the Create enrollment step, no validation will be required so the status will change to success.

Success Status

Success can occur in two scenarios:

1. Once the face validation is successful (next steps), the enrollment status will change to success.

2. After a successful reference image upload, if the body parameter confirmation was set to none in the Create enrollment step, no validation will be required so the status will change to success.

NOTE: After a successful enrollment, no further enrollments can be performed with the same account_id.

Failure Status

• The enrollment status can also be failure if the enrollment is declined or due to an internal error. Here´s a complete reference of the reasons why an enrollment can be declined:

Get enrollment request

To check the status of the enrollment, send a GET request to the endpoint https://api.validations.truora.com/v1/enrollments/{{enrollment_id}}.

If the file has not yet been uploaded successfully, you will receive a response with status pending with the reason set to waiting_file_upload, similar to the following:

    {
        "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "creation_date": "2024-04-23T15:33:28.544161454Z",
        "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "reason": "waiting_file_upload",
        "status": "pending",
        "update_date": "2024-04-23T15:33:28.544161536Z",
        "validation_type": "face-recognition"
    }

If the file is successfully uploaded, you will receive a response with the status pending and the reason will change to waiting_face_validation. This indicates that the image was successfully uploaded and is now awaiting a face validation (next steps):

    {
        "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "creation_date": "2024-04-23T15:33:28.544161454Z",
        "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "reason": "waiting_face_validation",
        "status": "pending",
        "update_date": "2024-04-23T15:33:28.544161536Z",
        "validation_type": "face-recognition"
    }

If the file is successfully uploaded and body parameter confirmation was set to none in the Create enrollment step, no validation will be required so the status will change to success:

    {
        "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "creation_date": "2024-04-23T15:33:28.544161454Z",
        "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "status": "success",
        "update_date": "2024-04-23T15:33:28.544161536Z",
        "validation_type": "face-recognition"
        "confirmation": "none"
    }

4. Create validation

Setup main Request Headers and Body

To configure the main request headers and body, follow these steps:

1. Create a POST request to the endpoint https://api.validations.truora.com/v1/validations.

2. Set the Headers

   • Truora-API-Key: enter the value obtained in the step of get Truora API-key.
   • Content-Type: the value should be application/x-www-form-urlencoded.

3. Set required values for the request body

   • type [Required]: Indicates the type of validation to be performed. Set this value to face-recognition
   • user_authorized [Required]: This indicates that you have the authorization of the person to be verified. This is mandatory in order to comply with data protection laws. Value must be set to true in order to perform the validation.
   • account_id [Required]: Use the same account_id that was used in Create Enrollment.
   • threshold [Optional]: The minimum required similarity between the base image and the facial recognition image or video to pass validation. By default, the threshold is set to 0.65.
   • liveness [Optional]: Allowed: passive ┃ disabled. Indicates whether liveness detection is to be used for the face validation. If is set to disabled or the parameter is omitted, the system will default to using a selfie for validation. *
   • subvalidations [Optional]: Allowed: passive_liveness ┃ similarity | speech_match. You can select more than one. Indicates which subvalidations you want to perform during face validation execution. If omitted, only similarity will be used. *
   • retry_of_id [Required if you want to retry a previous validation]: Refers to the validation_id of the failed validation. Only available if passive liveness is enabled in subvalidations or liveness parameters. *
   • minimum_precision [Required for speech_match subvalidation]: Allowed: very_high | high | medium | low. Minimum precision that the audio transcription obtained from the video selfie should have with the speech_token.
   • timeout [Optional]: The time, in seconds, users will have to complete the validation. If omitted, the timeout from the client’s config will be used. The default value is 300 seconds (5 minutes), with a maximum of 21600 seconds (6 hours).

   *NOTE: The parameter liveness is soon to be deprecated and will be replaced with the parameter subvalidations. For more information, please visit the Facial Recognition Methods guide and/or Contact Support.

Send the Create validation request you just created. You will receive a response similar to the following:

    {
        "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "ip_address": "XXX.XXX.XXX.XX",
        "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "type": "face-recognition",
        "validation_status": "pending",
        "threshold": 0.65,
        "creation_date": "2024-04-23T16:33:10.490088132Z",
        "instructions": {
            "file_upload_link": "https://files.truora.com/"
        }
    }

5. Upload Image or Video to Compare

The reference image must be submitted through a PUT request to the URL returned in the file_upload_link field of the previous step, selecting the Binary type in the Body.

• The image formats supported are: jpeg, png and webp. Maximum size is 10 MB.
• The video formats supported are: webm, mp4, avi, and mov. 10 MB for passive liveness.

After sending the PUT request you will receive a response similar to the following:

{
    "code": 10200,
    "http_code": 200,
    "message": "Successfully uploaded"
}

6. Get validation

The Get validation request allows you to retrieve the current status and results of a validation. The validation_status begins as pending. Upon completion, the validation can either be success or failure.

• To obtain the validation results, send a GET request to the endpoint https://api.validations.truora.com/v1/validations/{{validation_id}}, where validation_id is the identifier returned in the Create validation request.
• If you want to obtain the reference image and the image used for comparison, use the query parameter show_details with the value of true in the request.

Once executed, if the validation is still processing, validation_status will be pending and you will receive a response similar to the following:

{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "XXX.XXX.XXX.XX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "face-recognition",
    "validation_status": "pending",
    "threshold": 0.65,
    "creation_date": "2024-04-23T17:41:23.120796175Z",
    "remaining_retries": 2
}

When the validation is completed successfully, validation_status will be success and you will receive a response similar to the following:

{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "XXX.XXX.XXX.XX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "face-recognition",
    "validation_status": "success",
    "threshold": 0.65,
    "creation_date": "2024-04-23T16:45:13.604278626Z",
    "details": {
        "face_recognition_validations": {
            "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "similarity_status": "success",
            "age_range": {
                "high": 28,
                "low": 20
            },
            "confidence_score": 0.99,
            "face_search": {
                "status": "success",
                "confidence_score": 0
            }
        }
    }
}

If you send the query parameter show_details with value true in the Get validation request, you will receive the response with the links of the uploaded reference image validation_input_files, and the user image to compare input_files. These links will be valid for 15 minutes:

{
    "type": "face-recognition",
    "validation_status": "success",
    "creation_date": "2024-04-23T16:45:13.604278626Z",
    "processing_start_date": "2024-04-23T16:45:22.10851339Z",
    "processing_finish_date": "2024-04-23T16:45:26.67850316Z",
    "details": {
        "face_recognition_validations": {
            "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "similarity_status": "success",
            "age_range": {
                "high": 28,
                "low": 20
            },
            "confidence_score": 0.99,
            "face_search": {
                "status": "success",
                "confidence_score": 0
            }
        }
    },
    "validation_inputs": {
        "validation_input_files": [
            "https://truora-files/"
        ]
    },
    "user_response": {
        "input_files": [
            "https://truora-files/"
        ]
    },
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "XXX.XXX.XXX.XX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "threshold": 0.65,
    "allowed_retries": 2
}

7. Get enrollment - After Validation

As stated in the Get enrollment step, the enrollment status will only be set to success after a successful validation. This step is optional but will confirm that the enrollment is now successful.

After a successful validation (previous step), send a GET request to the endpoint https://api.validations.truora.com/v1/enrollments/{{enrollment_id}}.

You should receive a response with the status set to success, similar to the following:

    {
        "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "creation_date": "2024-04-23T15:33:28.544161454Z",
        "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "status": "success",
        "update_date": "2024-04-23T15:55:18.433121824Z",
        "validation_type": "face-recognition"
    }

8. Delete enrollment (auth required)

To request authorization for this feature, please contact our Support Team. Remember this special feature will be enabled upon your company’s request, and will be automatically enabled when requesting the Enrollment without validation feature. This authorization will affect only your Truora-API-Keys created after the approval.

In order to delete an enrollment you must:

• Know the enrollment_id returned in Create enrollment step.
• Create a DELETE request to the endpoint api.validations.truora.com/v1/enrollments/{{enrollment_id}}.

Be sure to keep track of the account_id of any deleted enrollment, as you will need it to create a new enrollment for the same account_id.

The following success message confirms that the enrollment has been deleted, indicating that no enrollment is now associated with the account_id of this user:

    {
        "message": "Enrollment was successfully deleted"
    }

In case your account is not authorized, you will receive an “Insufficient permissions” message:

    {
        "code": 10403,
        "http_code": 403,
        "message": "Insufficient permissions: missing access to validations.face_recognition.enrollments.delete"
    }

Declined and Expired reasons

Whenever a validation fails due to inconsistencies in the validation process or expires in the validation process, the API provides a reason to indicate why the validation was declined or expired:

• To learn more about the possible declined reasons, please visit the Declined Reasons section.
• To learn more about the possible expired reason, please visit Expired Reasons section.

Additional configurations

You can configure other parameters to improve the behavior of the validators and the user experience. Please see the Config Validator section for more information on customization.

Getting results automatically (Webhooks)

To get validation results automatically, you must subscribe webhooks. For more information, please see Webhooks section.