Verify API - Verify with Telesign code

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page walks you step-by-step through how to use Telesign Verify API to send a message using your preferred channel to an end-user with a verification code generated by Telesign. It also explains how to test if input from an end-user matches that code, so you can complete verification.

📘

NOTE:

Keep in mind that there are two options for generating the code: you can either generate it yourself or we can generate it for you.

Before you begin

• Ensure that you have set up the required integrations for each communication channel you intend to use. For SMS, register for a Sender ID. For WhatsApp, Viber, RCS, and email, follow the setup instructions.
• (Optional) Contact our Customer Support Team to configure any of these optional features:
  • Fixed routing by country: Fixed routing allows you to manage verification methods for each country.
  • Code validity: You can change time duration in seconds after which a verification code expires. The default time is 300 seconds.
  • Code length: You can specify the length of the OTP generated by Telesign. Length can range from 3 to 10 digits. Default value is 6 digits.
  • Fallback times: You can change time to wait before cascading to the next channel. The default fallback times are either 60 or 120 seconds, depending on the verification method.
  • Max attempts: The maximum number of attempts that an end user is allowed to attempt to enter the correct OTP. If this number is five, for example, an end user's sixth submission is rejected, even if it matches the original code.
  • Templates: You can create templates for each channel.

Send OTP

Keep the reference pages Create a verification process and Retrieve a verification process open in another window while you work on these steps.

Send the request

1. Send a Create a verification process request to the Verify API. Include the following param values:

Note that the security_factor is not included in the table, as it should not be provided if you would like Telesign to generate a code for you.

Request

POST /verification HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: verify.telesign.com
{
  "recipient": {
    "phone_number": "11234567890"
  },
  "verification_policy": [
    {
      "method": "whatsapp",
      "fallback_time": 30
    },
    {
      "method": "sms",
      "fallback_time": 30
    }
  ],
  "message_template": {
    "name": "verification_template"
  }
}

2. The service then sends a message, replacing the {{otp_code}} variable in the message template with the code generated by Telesign. In this example, the preferred channel is WhatsApp. If the WhatsApp channel fails, the fallback method is SMS.

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "recipient": {
    "phone_number": "11234567890"
  },
  "state": "ONGOING",
  "verification_policy": [
    {
      "method": "whatsapp",
      "fallback_time": 30
    },
    {
      "method": "sms",
      "fallback_time": 30
    }
  ],
  "status": {
    "code": 3901,
    "description": "Request in progress"
  }
}

2. Save the value of the property reference_id from the response. You will need it to complete the verification flow.
3. The status.code and status.description properties in the response indicate the preliminary delivery status of the SMS.

📘

NOTE:

The status.code property gives you status of delivery to the destination carrier, not necessarily all the way to the end-user.

Complete verification and get delivery status

Once your end-user has submitted a potential code through your application, complete the verification flow with a second API call.

1. Send an Update a verification process request to the Verify API. This is to provide Telesign with the asserted OTP from the end user.

• Include the reference_id for the transaction in the reference_id path parameter.

Request

PATCH /verification/0123456789ABCDEF0123456789ABCDEF/state HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: verify.telesign.com
{
  "action": "finalize",
  "security_factor": "5724433"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": {
    "code": 3900,
    "description": "Verified"
  }
}

2. The status.code and status.description properties in the payload of that response indicate the delivery status all the way to the end-user.