# Phone Validation via API

{{<tags >}}

Phone validation verifies a person's ownership of a phone number by comparing the code they enter with the one that was sent to the phone. 
These are the countries we support OTP (one-time password) shipping to:
- Mexico (+52)
- United States (+1)
- Chile (+56)
- Colombia (+57)
- Peru (+51)
- Venezuela (+58)
- Brazil (+55)
- Ecuador (+593)
- Australia/Cocos/Christmas Island (+61)

## 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. **Phone Number:** If you already know the phone number you want to validate, please provide it yourself. Otherwise, request it from your user.
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">}}

## 1. Create Enrollment
Create a phone validation associated with an account. The account allows a user to be identified on the Truora platform and is represented by the ``account_id``.

>The enrollment should only be done once per ``phone_type``. If the user account already has a ``phone-verification`` enrollment. Please proceed to create the validation directly.

### Setup main Request Headers and Body

To configure the main request headers and body, follow these steps:

1. Create a ``POST`` request to ``https://api.validations.truora.com/v1/enrollments``.
2. Set the **Headers**
    - ``Truora-API-Key`` enter the value obtained in the step of get 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 ``phone-verification``
    - ``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.
    - ``phone_number`` [***Required***]: Phone number to be associated with the validation account on successful validation. Must include the country code (e.g., +57300XXXXXXX).
    - ``phone_type`` [***Required***]: Allowed: ``home``|``office``|``recover``. Specifies the label of the phone number to be associated with the validation account upon successful validation. 
    You can associate up to three phone numbers with a user account. To do this, you must create a new enrollment by choosing a different ``phone_type`` each time.
    - ``country`` [***Optional***]: Allowed: ``CO``|``CL``|``MX``|``BR``|``VE``|``PE``|``EC``|``AR``|``US``. Origin country of the person to be validated.
    - ``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.
    <!-- - ``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. -->

If everything goes well with the enrollment, you should receive a response similar to the following:
{{<code lang="json" method="POST" endpoint="/v1/enrollments">}}
{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-05-02T17:36:56.611943501Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "success",
    "update_date": "2024-05-02T17:36:56.611943583Z",
    "validation_type": "phone-verification"
}
{{</code>}}

> Note: The ``phone_type``, ``enrollment_id`` and ``account_id`` of the response on this endpoint will be used in later steps.

## 2. Get Enrollment
Allows searching for an enrollment in order to verify its progress, this step is **optional**.
The enrollment status will be ``success`` or ``failure`` depending on the internal verifications performed on the number.

- Create a **GET** request to the endpoint ``https://api.validations.truora.com/v1/enrollments/{{enrollment_id}}``.


- If everything goes well with the enrollment, you should receive a response similar to the following:
{{<code lang="json" method="GET" endpoint="/v1/enrollments/{{enrollment_id}}">}}
{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-05-02T17:36:56.611943501Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "success",
    "update_date": "2024-05-02T17:36:56.611943583Z",
    "validation_type": "phone-verification"
}
{{</code>}}

- For Colombia, an additional verification is performed on the behavior of the line. A score ranging from 0 to 1 is obtained. 
The closer the score of the line is to 1, the indication is that the line has not been reported for suspicious activity.
You should receive a response similar to the following:

{{<code lang="json" method="GET" endpoint="/v1/enrollments/{{enrollment_id}}" response="200 - Success Status CO">}}
{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-04-30T20:06:14.966465317Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "validator_data": {
        "phone_trust_score": {
            "phone_behavior_score": 1
        }
    },
    "status": "success",
    "update_date": "2024-04-30T20:06:14.966465432Z",
    "validation_type": "phone-verification"
}
{{</code>}}

- If a number from a country not supported is sent, you will receive a response like this:
{{<code lang="json" method="GET" endpoint="/v1/enrollments/{{enrollment_id}}" response="200 - Phone Number Out of Coverage">}}
{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-05-02T17:28:32.893426649Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "reason": "phone_number_out_of_coverage",
    "status": "failure",
    "update_date": "2024-05-02T17:28:32.893426739Z",
    "validation_type": "phone-verification"
}
{{</code>}}

- If an invalid number is sent, you will receive a response like this:
{{<code lang="json" method="GET" endpoint="/v1/enrollments/{{enrollment_id}}" response="200 - Phone Number Not Found">}}
{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-05-02T17:32:38.069756729Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "reason": "phone_number_not_found",
    "status": "failure",
    "update_date": "2024-05-02T17:32:38.069756843Z",
    "validation_type": "phone-verification"
}
{{</code>}}

## 3. 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 ``https://api.validations.truora.com/v1/validations``.
2. Set the **Headers**
    - ``Truora-API-Key`` enter the value obtained in the step of get 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 ``phone-verification``
    - ``verify_channel`` [***Required***]: Allowed: ``sms``|``call``|``whatsapp``. Indicates the channel used to perform the verification. Some problems may occur when receiving the SMS due to external protocols of the mobile service providers, so we recommend giving an additional option to the users.*
    - ``phone_locale`` [***Required***]: Allowed: ``en``|``es``|``pt-BR``. Language used to perform the validation via the selected verification channel.
    - ``phone_type`` [***Required***]: Allowed: ``home``|``office``|``recover``. Specifies the label of the phone number to be associated with the validation account upon successful validation. The phone type must have already been enrolled.
    - ``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](/guides/phone_validation_api/#setup-main-request-headers-and-body).
    - ``country`` [***Optional***]: Allowed: ``CO``|``MX``|``BR``|``CL``|``PE``|``VE``|``EC``|``US``|``AU``. Origin country of the person to be validated.
    - ``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 600 seconds (10 minutes).
    <!-- - ``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. -->


*If you set ``whatsapp`` as the ``verify_channel`` value, you must have your own **WABA line** and **Activate** it. Then, create your **Outbound message** of type **OTP** and **Contact Support** to provide your **Outbound ID** for inclusion in your process:
  - This guide explains how to {{< newtab href="/guides/waba_acquisition/" >}}Create a WABA line and Activate it{{< /newtab >}}.
  - This guide explains how to {{< newtab href="/guides/outbound/" >}}Create an Outbound message{{< /newtab >}} and obtain your message´s **Outbound ID**. Follow the guide and select **OTP** in the **Message Category**.
    - After the message is approved, **Contact Support** and provide the **Outbound ID** of your message to our team to include it in your process.

After setting the required values in the Request Body, if everything goes well with the **Create Validation** request, you should receive a response similar to the following:

{{<code lang="json" method="POST" endpoint="/v1/validations" response="200 - Pending Status">}}
{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "XXX.XXX.XX.XX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "phone-verification",
    "validation_status": "pending",
    "creation_date": "2024-05-02T15:44:13.026469583Z",
    "remaining_retries": 2
}
{{</code>}}
> Note: The ``validation_id`` of the response on this endpoint will be used in later steps.

## 4. Perform Validation
### Setup main Request Headers and Body

To configure the main request headers and body, follow these steps:

1. Create a **POST** request to ``https://api.validations.truora.com/v1/validations/{{validation_id}}``.
2. Set the **Headers**
    - ``Truora-API-Key`` enter the value obtained in the step of get 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 ``phone-verification``
    - ``token`` [***Required***]: Validation code sent via sms, voice call or WhatsApp.

If everything goes well with the Perform Validation, you should receive a response similar to the following:
{{<code lang="json" method="POST" endpoint="/v1/validations/{{validation_id}}">}}
{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "phone-verification",
    "validation_status": "success",
    "creation_date": "2024-05-02T15:45:18.548661435Z",
    "remaining_retries": 2
}
{{</code>}}

> By default, the user will have 2 retries to enter the code. You can see the remaining retries in the field ``remaining_retries``.

## 5. Get Validation
This API endpoint allows you to retrieve the current status and information 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 details such as the inputs of the validation, you can send the query parameter ``show_details`` with the value of ``true``.

- Once executed, if the validation is still processing, ``validation_status`` will be ``pending`` and you will receive a response similar to the following:
{{<code lang="json" method="GET" endpoint="/v1/validations/{{validation_id}}" response="200 - Pending Status">}}
{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "XXX.XX.XX.XX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "phone-verification",
    "validation_status": "pending",
    "creation_date": "2024-05-02T23:01:22.698831731Z",
    "remaining_retries": 2
}
{{</code>}}

- When the validation is completed successfully, ``validation_status`` will be ``success`` and you will receive a response similar to the following:
{{<code lang="json" method="GET" endpoint="/v1/validations/{{validation_id}}">}}
{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "XXX.XX.XX.XX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "phone-verification",
    "validation_status": "success",
    "creation_date": "2024-05-02T23:01:22.698831731Z",
    "remaining_retries": 2
}
{{</code>}}

- If you send the query parameter ``show_details``, you will receive a response similar to the following:
{{<code lang="json" method="GET" endpoint="/v1/validations/{{validation_id}}?show_details=true">}}
{
    "type": "phone-verification",
    "validation_status": "success",
    "creation_date": "2024-05-02T23:01:22.698831731Z",
    "processing_start_date": "2024-05-02T23:03:05.388468447Z",
    "processing_finish_date": "2024-05-02T23:03:06.973605823Z",
    "validation_inputs": {
        "phone_type": "home",
        "verify_channel": "sms",
        "phone_locale": "es",
        "phone_number": "+57XXXXXXXXXX",
        "phone_trust_score": {
            "phone_behavior_score": 1
        }
    },
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "XXX.XX.XX.XX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "allowed_retries": 2,
    "remaining_retries": 2
}
{{</code>}}

## 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.