# 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](/validators/account_set_up/) and then go to [Authentication](/validators/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**](/validators/document_validation_api/), 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. {{}} ## 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](/validators/face_validation_api/#prerequisites). - ``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](/guides/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](#enrollment-without-validation-auth-required) 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](#8-delete-enrollment-auth-required) 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: {{}} | Failure status reason | Description | |:-------------------------:|-------------| ``no_face_detected`` | Indicates that no face has been detected in the image that will be used as a reference to compare the next photo or video. | ``face_in_blocklist`` | Indicates that the face in the base image has been detected in the client's block list. ***[Click Here](/guides/truface/)*** to learn more about **TruFace** block list. | ``file_format_not_supported`` | Indicates that the format of the base image is not compatible with the system. Allowed formats: JPG, PNG, and JPEG. | ``face_validation_failed`` | The performed ``face-recognition`` validation to confirm a match between the face in the reference image and the user's face was unsuccessful.| ``system_error`` | An error occurred while processing the enrollment inputs.| {{
}} ### 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](/validators/face_validation_api/#prerequisites). - ``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](../face_validation_api/#1-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 {{< 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/" } } {{}} ## 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](#enrollment-without-validation-auth-required) 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**](/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.