Email Validation via API

Product: Validators
Verifies the ownership or permissions a person has over an email by comparing the code the person enters and the one that is mailed to the email address provided.

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 and then go to Authentication to obtain your Truora API-key.
  2. Email: If you already know the email 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.

https://www.postman.com/truora-api-docs/workspace/truora-api-docs/collection/26510995-ad2e7c71-b39a-40e4-8322-ae3316160634?ctx=documentation

1. Create Enrollment

Create an email validation associated with an account. The account allows a user to be identified on the Truora platform and is represented by the account_id.

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 email-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.
    • email [Required]: Email to be associated with the user account.
    • user_authorized [Required]: Indicates whether the end user authorized the validation. Must be true in order to proceed.
    • 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 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 for more details.

If everything goes well with the enrollment, you should receive a response similar to the following:

POST
/v1/enrollments 

{
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "creation_date": "2024-05-03T22:45:18.442513747Z",
    "enrollment_id": "ENRXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "success",
    "update_date": "2024-05-03T22:45:18.442513837Z",
    "validation_type": "email-verification"
}

Note: The 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:

    GET
    /v1/enrollments/{{enrollment_id}} 
    
{
  "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "creation_date": "2024-05-03T22:49:06.865635072Z",
  "enrollment_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "success",
  "update_date": "2024-05-03T22:49:06.86563517Z",
  "validation_type": "email-verification"
}

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 email-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.
    • account_id [Required]: Use the same account_id that was used in Create Enrollment.
    • 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 for more details.
    • language [Optional]: Allowed: es|en. Language of the email that the final user receives.
    • user_name [Optional]: Custom name for verification messages.

If everything goes well with the Create Validation, you should receive a response similar to the following:

POST
/v1/validations 

{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "ip_address": "191.106.236.136",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "email-verification",
    "validation_status": "pending",
    "creation_date": "2024-05-04T00:24:35.124115749Z",
    "remaining_retries": 2
}

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 email-verification.
    • token [Required]: Validation code sent via email.

If everything goes well with the Perform Validation, you should receive a response similar to the following:

POST
/v1/validations/{{validation_id}} 

{
    "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "email-verification",
    "validation_status": "success",
    "creation_date": "2024-05-04T00:27:50.227404806Z",
    "remaining_retries": 2
}

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:

    GET
    /v1/validations/{{validation_id}} 
    
{
  "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "ip_address": "XXX.XX.XX.XX",
  "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "type": "email-verification",
  "validation_status": "pending",
  "creation_date": "2024-05-02T23:01:22.698831731Z",
  "remaining_retries": 2
}

  • When the validation is completed successfully, validation_status will be success and you will receive a response similar to the following:

    GET
    /v1/validations/{{validation_id}} 
    
{
  "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "ip_address": "XXX.XX.XX.XX",
  "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "type": "email-verification",
  "validation_status": "success",
  "creation_date": "2024-05-02T23:01:22.698831731Z",
  "remaining_retries": 2
}

  • If you send the query parameter show_details, you will receive a response similar to the following:

    GET
    /v1/validations/{{validation_id}}?show_details=true 
    
{
  "type": "email-verification",
  "validation_status": "success",
  "creation_date": "2024-05-04T00:24:35.124115749Z",
  "processing_start_date": "2024-05-04T00:27:50.146421126Z",
  "processing_finish_date": "2024-05-04T00:27:50.227481467Z",
  "validation_inputs": {
     "email": "XXXX@XXXXX.com"
  },
  "validation_id": "VLDXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "ip_address": "XXX.XXX.XXX.XXX",
  "account_id": "ACCXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "allowed_retries": 2,
  "remaining_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 section.
  • To learn more about the possible expired reason, please visit 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 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 section.