Verify API - Verify with your own 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 your own one-time passcode (OTP) to an end-user. It also explains how to complete verification and send us completion data.

📘

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. If you include the security_factor parameter in your request, your code is used. In case you provide an invalid value or its length is out of range, you will receive an error code. If you don't provide the security_factor parameter, Telesign generates a code 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.
  • 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.
  • 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.
  • 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.

📘

NOTE:

Updating a verification process using the procedure explained in Complete verification and get delivery status is a mandatory step when using Verify API. This step allows Telesign to know the real state of your verification as well as control all the features related to a verification process such as fallback, callback, and pricing. If your end user has verified themselves but the verification process is not updated, these features might not work as intended which can lead to extra costs or incorrect billing.

Send the request

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

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"
  },
   "security_factor": "5724433"
}

2. The service then sends a message, replacing the {{otp_code}} variable in the message template with the security_factor you provided in the request. 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"
  }
}

3. Save the value of the property reference_id from the response. You will need it to complete the verification flow.
4. 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

🚧

WARNING:

Even when you generate the code, this step is necessary to end the verification process and avoid added costs due to additional sends to the end user.

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.

📘

NOTE:

Sending us completion data helps us identify and resolve issues with delivery, operators, and routes, ensuring best user experience and expected behavior of all features and pricing.