# Face Re-Validation via API {{}} Learn how to perform a **Face Re-Validation** using our API, understanding the essential API endpoints, responses and errors. > This process will allow you to re-verify users who were previously validated through **Face validations** in our platform. > If you want to perform **Face Validation** for the first time, please visit the [Face Validation via API](/validators/face_validation_api/) guide. ## Prerequisites Before you begin, make sure you have the following: 1. **Truora API-Key:** You should already have your **Truora API-Key**. If you don’t, [set up an account](/validators/account_set_up/) and then go to [Authentication](/validators/authentication/) to obtain your **Truora API-key**. 2. **User Account and Enrollment ID:** You must already have a user account with a successful face validation enrollment process. The user account is represented by the ``account_id``, and the ``enrollment_id`` is obtained with the successful enrollment process. - For more information on Face Validation Enrollment, please visit the [Create Enrollment section](/validators/face_validation_api/#1-create-enrollment) of the **Face Validation via API** guide. 3. **Media Files:** You will need a selfie or video for the face recognition. 4. **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. {{}} ## 1. Get enrollment To perform the **Face Re-Validation**, you must previously verify that the enrollment status is ``success``. If the status is ``failure`` or ``pending``, you will need to complete the enrollment process first (Prerequisite No.2 in this guide). Verify the enrollment status by sending a **GET** request to the endpoint ``https://api.validations.truora.com/v1/enrollments/{{enrollment_id}}``. If the enrollment exists, you will receive a response 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" } {{}} ## 2. 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 of your **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 when creating the user 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 {{< newtab href="/guides/facial_recognition_methods" >}}Facial Recognition Methods{{< /newtab >}} 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/" } } {{}} ## 3. 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" } {{}} ## 4. 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**](/validators/declined_reasons/) section. - To learn more about the possible expired reason, please visit [**Expired Reasons**](/validators/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](../config_validators/) 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**](/validators/webhook_rule/) section.