TruFace Validation

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 request use of Truora’s global collection to check against globally reported faces. This requires some internal procedures and activations so please Contact Us for more information.

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.

Report a Face
- Create a POST request to the endpoint api.validations.truorastaging.com/v1/enrollments.
- Set the following key:value pairs within the request body using the application/x-www-form-urlencoded format:
  - type: [Required] set to face-search
  - user_authorized: [Required] Indicates whether the person subject to the validation authorized the validation. Must be true in order to proceed.
  - country: [Required] Allowed: BR┃CL┃CO┃CR┃EC┃MX┃PE
  - 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.

You will receive a Response similar to the following:

Response 200

 
    {
        "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"
    }

Enrollment status will be pending until a picture file is uploaded successfully in the next step.

Note: The enrollment_id and file_upload_link returned by this endpoint will be used in subsequent steps.

Upload Picture
- Create a PUT request to the file_upload_link returned in step 1 (Report Face).
- Upload the photo within the Request Body in binary format. Allowed formats are: JPEG, JPG, or PNG
If the upload is successful, you will receive a Response similar to the following:
Response 200
```
        {
             "code": 10200,
             "http_code": 200,
             "message": "Successfully uploaded"
        }
    
```
Get Enrollment

Allows consulting the status of an enrollment:

Create a GET request to the endpoint api.validations.truora.com/v1/enrollments/{{enrollment_id}. Use the enrollment_id returned in Report Face step.

Response 200


        {
            "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"
        }

Note: Enrollment status will be pending until a picture file is uploaded successfully in the previous step.

When you have successfully uploaded a picture, the enrollment status should change to success:

Response 200


        {
            "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"
        }

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.

Check Face
- Create a POST request to the endpoint api.validations.truora.com/v1/validations.
- Set the following key:value pairs within the request body using the application/x-www-form-urlencoded format:
  - type: [Required] set to face-search.
  - account_id: 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. Note that 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.
    - 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: BR┃CL┃CO┃CR┃EC┃MX┃PE
  Note: The validation_id and file_upload_link returned by this endpoint will be used in subsequent steps.
  Response 200
  { "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" } }
Upload Picture
- Create a PUT request to the file_upload_link returned in step 1 (Check Face).
- Upload the photo within the Request Body in binary format. Allowed formats are: JPEG, JPG, or PNG
  Response 200
  { "code": 10200, "http_code": 200, "message": "Successfully uploaded" }
Get Validation

The validation results can be obtained by Polling or subscribing a Hook, both processes are explained below.

Polling:

Create a GET request to the endpoint api.validations.truora.com/v1/validations/{{validation_id}}. Use the validation_id returned in step 1 (Check Face).
Response 200
```
        {
            "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"
        }
```
Note: To obtain the images of the reported face and the photo uploaded by the user you must:
- Pass the query param show_details with the value true.
  - This endpoint returns a json with the result of the validation and the images:
    - The images are uploaded to S3 and a link is returned where the content can be consulted.
    - These links have an expiration time of 15 minutes, after that time the link cannot be used.
    - To generate new links, the Get Result endpoint must be called again to return the result of the process with new links to view the images.

Postman Query example

Hooks:

To get TruFace validation result automatically, you must subscribe a TruFace hook. For more information, please see Webhooks guide.

Note: The hook only contains the validation result information. To obtain the images of the reported face and the photo uploaded by the user you must:

Get the validation_id field from the decoded hook response.
Make a GET request to the endpoint api.validations.truora.com/v1/validations/{{validation_id}} passing the query param show_details with the value true.
This endpoint returns a json with the result of the validation and the images:
- The images are uploaded to S3 and a link is returned where the content can be consulted.
- These links have an expiration time of 15 minutes, after that time the link cannot be used.
- To generate new links, the Get Result endpoint must be called again to return the result of the process with new links to view the images.

Unblocking a Face

Allows unblocking faces from Truora’ services.

In order to unblock a face, you must know the enrollment_id returned in Report Face step.
Using this enrollment_id and 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:

Response 200


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