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 thesecurity_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
- Send a Create a verification process request to the Verify API. Include the following param values:
Parameter | Value | Description | Required? |
---|---|---|---|
recipient.phone_number | Digits without spaces or special characters, beginning with the country dialing code. | The recipient's phone number | yes |
verification_policy[0].method | A name of the preferred verification method. | One of the verification methods included in a verification policy. | Required only if the preferred verification method for this request is not already defined as the primary verification method for this account's default verification policy. |
verification_policy[0].fallback_time | A time in seconds. | The time window in seconds that the service waits before abandoning the current verification method and then initiating verification using the next method. | No. In case you don’t specify the fallback time, default fallback time is used. |
verification_policy[1].method | A name of the fallback verification method. | One of the verification methods included in a verification policy. This is your backup method. | No, but recommended in case your recipient cannot be reached by the preferred verification method. |
security_factor | A numeric code, formatted as a string. It's limited to a maximum of 10 characters. | The OTP to include in the message to the end user. This parameter is ignored as part of the logic check if there is no OTP-based method in the verification policy. | Yes in case you want to generate your own code. If you don't specify security_factor , Telesign generates a code for you. |
message_template.name | A string consisting only of lowercase alpha characters and underscores. | A name of the template that is used for this request. | No. If you do not declare a template, Verify API will use a default template. |
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"
}
- The service then sends a message, replacing the
{{otp_code}}
variable in the message template with thesecurity_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"
}
}
- Save the value of the property
reference_id
from the response. You will need it to complete the verification flow. - The
status.code
andstatus.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.
- 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 thereference_id
path parameter.
- Include the
Parameter | Value | Description | Required? |
---|---|---|---|
action | finalize | Specifies how you want to change the verification state for this verification process. | yes |
security_factor | A string consisting of a series of numeric digits. | The end user's asserted one-time passcode (OTP). | yes |
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"
}
}
- The
status.code
andstatus.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.
Updated 20 days ago