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.

Send the Create enrollment request you just created, and 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 be pending until the reference image is successfully uploaded in the next step.
• The account_id, enrollment_id and file_upload_link returned by this endpoint will be used in subsequent steps.

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

Get enrollment request will consult the status of the enrollment. The status will remain as pending until the image is successfully uploaded in the previous step, when it will change to success.

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 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 status 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:33:28.544161536Z",
        "validation_type": "face-recognition"
    }

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.
   • 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 is to be used for the face validation. Disabled state or empty is selfie.
   • subvalidations [Optional]: Allowed: passive_liveness ┃ similarity ┃ government. You can select more than one. Indicates which subvalidations you want to perform during a face validation execution. If empty we only use similarity value.
   • retry_of_id [Required if you want to retry a previous validation]: Refers to the validation_id of the failed validation. Note: Only enabled for passive liveness.
   • account_id [Optional]: Use the same account_id that was used in Create enrollment.

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",
        "details": {
            "face_recognition_validations": {
                "confidence_score": 0,
                "passive_liveness_status": "pending"
            }
        },
        "remaining_retries": 2,
        "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.

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
}

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.

Getting results automatically (Webhooks)

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