# TruFace Validation
{{<tags>}}

You can use **TruFace** to help your company identify, block and report fraudsters faces. Here is how it works:
- **When making an onboarding process:** Our system will automatically check if the person undergoing your onboarding process has been reported before and will alert you.
    - **Report faces:** If you identify fraudsters, you can report and block those faces and these will be added to your collection.
    - **If you mistakenly blocked a face:** Don't worry! You also have the option to unblock it.
    - **Checking Faces:** The process involves checking against your registered collection of blocked faces. 
        - ***Note**: Optionally your company could make use of risky faces detected by Truora. This requires a request for access, to do so please ***[Contact Us](https://wa.link/6tj5j2)***.*

## 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 (**Report a face**) and another image to compare and make the validation (**Check a face**).

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.
{{<copy-url src="https://www.postman.com/truora-api-docs/workspace/truora-api-docs/collection/26510995-ad2e7c71-b39a-40e4-8322-ae3316160634?ctx=documentation">}}


## Blocking faces
- Create an **enrollment** for the validation account.
- Use ``fraud_reason`` to block a face from being validated. 
- Save the ``account_id`` and ``enrollment_id`` from the response, since these will help you identify people who have been reported.

### 1. Create enrollment (Report a Face)

#### 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/truface/#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-search``.
    - ``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 links the face to an account. It is a unique value assigned to each user in the system to distinguish them and access their information and processes. An automated account id is created if left blank, otherwise, a validation account is created with the custom account id provided. Use this ID to trace the blocked face.
    <br>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.
        * **Note:** For better tracking, it is recommended that your company sets this ID with a traceable system.
    - ``country`` [***Required***]: Allowed: ``ALL``|``BR``|``CL``|``CO``|``CR``|``EC``|``MX``|``PE`` . Country of the reported face.
    <br>**Note:** If you are going to use **TruFace** as a [Face Validation](/validators/face_validation_api/) compliment, you must use ``ALL`` as country.
    - ``fraud_reason`` [***Required***]: Indicates the reason to block a face. Set one of the following:
        - *``manipulated_document`` ➜ indicates that this person is known to use manipulated documents to pass identity validations.*
        - *``manipulated_photo`` ➜ indicates that this person is known to manipulate photos to pass identity validations.*
        - *``non_payment`` ➜ indicates that this person has incomplete payments and refuses to pay.*
        - *``criminal_records_in_company`` ➜ indicates that this person has some sort of criminal history with your company, or an ally.*
        - *``fraudster`` ➜ indicates you know this person to be a fraudster for reasons different from the above.*
    <!-- - ``alias_id`` [***Optional***]: The alias identifier linked to an existing ``account_id``. Omit the ``account_id`` when using the ``alias_id`` instead. See the [Aliases Guide](/guides/aliases/) for more details. -->

Send the **Create enrollment** request you just created, and will receive a response similar to the following:
   
{{<code lang="json" method="POST" endpoint="/v1/enrollments" response="200 - Pending Status">}}
    {
        "account_id": "ACCf4846c6a03de98ca8xxxxxxxxxxxxx",
        "creation_date": "2023-03-24T18:35:10.941370621Z",
        "enrollment_id": "ENR84b0443a9481aexxxxxxxxxxxxx",
        "fraud_reason": "manipulated_document",
        "reason": "waiting_file_upload",
        "status": "pending",
        "update_date": "2023-03-24T18:35:10.941370721Z",
        "validation_type": "face-search",
        "file_upload_link": "https://files.truora.com/xxxxxx"
    }
{{</code>}}

> **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 Picture

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 lang="json" method="PUT" endpoint="{{file_upload_link}}">}}
    {
            "code": 10200,
            "http_code": 200,
            "message": "Successfully uploaded"
    }
{{</code>}}

### 3. Get Enrollment
The **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:

{{<code lang="json" method="GET" endpoint="/v1/enrollments/{{enrollment_id}}" response="200 - Pending Status">}}
    {
        "account_id": "ACCa5e3a5c66996c78xxxxxxxxxxxxxxx",
        "creation_date": "2023-02-13T21:49:22.820356188Z",
        "enrollment_id": "ENRf72bae49d31cxxxxxxxxxxxxxxx",
        "report_reason": "manipulated_document",
        "reason": "waiting_file_upload",
        "status": "pending",
        "update_date": "2023-02-13T21:49:22.820356276Z",
        "validation_type": "face-search"
    }
{{</code>}}

If the file is successfully uploaded, you will receive a response with status ``success`` similar to the following:

{{<code lang="json" method="GET" endpoint="/v1/enrollments/{{enrollment_id}}">}}
    {
        "account_id": "ACCa5e3a5c66996c78xxxxxxxxxxxxxxx",
        "creation_date": "2023-02-13T21:49:22.820356188Z",
        "enrollment_id": "ENRf72bae49d31cxxxxxxxxxxxxxxx",
        "report_reason": "manipulated_document",
        "status": "success",
        "update_date": "2023-02-13T21:49:22.820356276Z",
        "validation_type": "face-search"
    }
{{</code>}}

## Checking faces
Allows you to create a validation of the person who will perform the onboarding process. The account identifies a user in Truora's system and is represented by the ``account_id``.

### 1. Create validation (Check a Face)

#### 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/truface/#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-search``.
    - ``account_id`` [***Optional***]: Validation account ID linked with this validation. An automated account id is created if left blank, otherwise, a validation account is created with the custom account id provided. Use this ID to trace the validations performed by the account later on.
    <br>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.
        * **Note:** For better tracking, it is recommended that your company sets this ID with a traceable system.
    - ``user_authorized`` [***Required***]: Indicates whether the person subject to the validation authorized the validation. Must be ``true`` in order to proceed.
    - ``country`` [***Required***]: Allowed: ``ALL``|``BR``|``CL``|``CO``|``CR``|``EC``|``MX``|``PE`` 
    <br>**Note:** If you are going to use **TruFace** as a [Face Validation](/validators/face_validation_api/) compliment, you must use ``ALL`` as country.
    - ``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).
    <!-- - ``alias_id`` [***Optional***]: The alias identifier linked to an existing ``account_id``. Omit the ``account_id`` when using the ``alias_id`` instead. See the [Aliases Guide](/guides/aliases/) for more details. -->

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

{{<code lang="json" method="POST" endpoint="/v1/validations" response="200 - Pending Status">}}
    {
        "validation_id": "VLDcde37b3070c8xxxxxxxxxxxxxxxxx",
        "ip_address": "xxx.xxx.xx.xx",
        "account_id": "ACC3aa01732f763b17xxxxxxxxxxxxxxxxx",
        "type": "face-search",
        "validation_status": "pending",
        "threshold": 0.98,
        "creation_date": "2023-02-22T21:50:01.47020878Z",
        "instructions": {
            "file_upload_link": "https://files.truora.com/xxxxxxxxxxx"
        }
    }
{{</code>}}

> **Note**
> - The ``validation_id`` and ``file_upload_link`` returned by this endpoint will be used in subsequent steps.

### 2. Upload Picture

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 lang="json" method="PUT" endpoint="{{file_upload_link}}">}}
    {
        "code": 10200,
        "http_code": 200,
        "message": "Successfully uploaded"
    }
{{</code>}}

### 3. 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 (Check a Face)** request.
- If you want to obtain links of the reported face image and the photo uploaded by the user, send the query parameter ``show_details`` with value ``true`` in the **Get validation** request, and you will receive the response with the links ``validation_input_files`` and ``input_files``. 
    - **NOTE:** These links will be valid for 15 minutes. To generate new links, the **Get Result** endpoint must be called again to return the result of the process with new links.

Once executed you will receive a response similar to the following:

{{<code lang="json" method="GET" endpoint="/v1/validations/{{validation_id}}" response="200 - Failure Status">}}
        {
            "validation_id": "VLD853e95094e1bb5c938xxxxxxxxxxx",
            "ip_address": "xxx.xxx.xx.xx",
            "account_id": "ACC54350f7b7983b3c0aee50xxxxxxxxxxx",
            "type": "face-search",
            "validation_status": "failure",
            "failure_status": "declined",
            "declined_reason": "fraudster_face_match_in_client_collection",
            "creation_date": "2021-08-03T03:03:34.849954642Z",
            "message": "matched with face reported in enrollment ENR019e4390008b25634d8xxxxxxxxxx for fraudster",
            "fraudster_enrollment_id": "ENR019e4390008b25634d8xxxxxxxxxx"
        }
{{</code>}}

> **Note**: 
> - If the ``validation_status`` is ``success``, it indicates that the user's face was not found in any collection of reported faces.
> - If the ``validation_status`` is ``failure`` and the ``declined_reason`` is ``fraudster_face_match_in_client_collection``, it indicates that the user's face matched one reported as a fraudster.

## Unblocking a Face

### Delete enrollment (Unblock a face)
In order to unblock faces from Truora's services you must:
   - Know the ``enrollment_id`` returned in **Create enrollment (Report a Face)** step.
   - Create a **DELETE** request to the endpoint ``api.validations.truora.com/v1/enrollments/{{enrollment_id}}``.

The following success ``message`` confirms that the face has been unblocked:

{{<code lang="json" method="DELETE" endpoint="/v1/enrollments/{{enrollment_id}}">}}
    {
        "message": "Enrollment was successfully deleted"
    }
{{</code>}}

## Getting results automatically (Webhooks)
To get validation results automatically, you must subscribe webhooks. For more information, please see [Webhooks](/validators/webhook_rule/) section.

***Note***: The hook only contains the validation result information. If you want to obtain links of the reported face image and the photo uploaded by the user, you must:

- Decode the hook response and extract the value of ``validation_id`` field.
- Use the ``validation_id`` to make the [Get validation](../truface/#3-get-validation) request with the query parameter ``show_details`` set to ``true``.
- The **Get validation** response will include the links in the fields ``validation_input_files`` and ``input_files``. 
- These links will be valid for 15 minutes. To generate new links, the [Get validation](../truface/#3-get-validation) endpoint must be called again to return the result of the process with new links.

## 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
Using our API you can configure other parameters to improve the behavior of the validators and the user experience according to your particular needs. Please see the {{< newtab href="/guides/config_validators/" >}}Config Validator Guide{{< /newtab >}} for more information on customization.

> **Please Note:**
> - The config parameters you will see in the {{< newtab href="/guides/config_validators/" >}}Config Validator Guide{{< /newtab >}} are global parameters for your account and will affect all the validations across your account.
> - However, validations performed using the flow you created will prioritize the configuration in the Validator Block of your flow. All other parameters, not configurable within the Flow Builder, will take the global configuration values.