Verify API - Specify Verify API template
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.
This page explains step-by-step how to specify a Verify API template. A template is declared once for the entire verification process and it is available for use on all channels. If a template isn't specified, Verify API will use a default template.
NOTE:
You must use the same template name for each of your active channels (for example, WhatsApp, Viber, Email, SMS) if you are utilizing a fallback channel.
Before you begin
Set up a template for Verify API. Contact Telesign Customer Support or your Telesign contact to create this template.
Specify a Verify API template
- 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 |
recipient.email | A valid email address. | The recipient's email address. | Yes, if the primary verification method is email. |
message_template.name | lowercase alpha characters and underscores. | The name of your template. | Yes |
verification_policy[0].method | sms , viber , whatsapp , rcs or email . | One of the verification methods included in a verification policy. | Required only if a channel 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, but recommended in case your recipient cannot be reached using the primary verification channel. |
verification_policy[1].method | sms | 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 using the primary verification channel. |
security_factor | A numeric code, formatted as a string. | The OTP to include in the message to the end user. | No. Can be used if you wish to define your own OTP instead of allowing Telesign to generate an OTP. |
- The service then sends a message using the primary channel you selected to your end user, inserting a randomly generated OTP in the message. (See the appropriate channel-specific guide page for more information.)
- 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. - Follow the steps for Complete verification and get delivery status on the appropriate channel-specific guide page.
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 and you can be billed incorrectly.
Successful request
This is an example of a successful request using a message template named verification_template
that was previously set up.
curl --request POST \
--url https://verify.telesign.com/verification \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"recipient": {
"phone_number": "11234567890"
},
"message_template": {
"name": "verification_template"
},
"security_factor": "123456",
"verification_policy": [
{
"method": "viber",
"fallback_time":60
},
{
"method": "rcs",
"fallback_time":120
}
]
}
Successful response
This is a successful response returned after a successful attempt with the correct template name.
HTTP/1.1 200 OK
Content-Type: application/json
{
"mobile_app_token": "b7591bc3bd874f6085ec300ccec02462",
"recipient": {
"phone_number": "11234567890"
},
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"state": "CREATED",
"status": {
"code": 3901,
"description": "Request in progress"
}
}
NOTE:
The
status.code
property gives you status of delivery to the destination carrier, not necessarily all the way to the end user.
Unsuccessful request
In this example, the wrong template name, verify_template
, instead of verification_template
, is used.
curl --request POST \
--url https://verify.telesign.com/verification \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"recipient": {
"phone_number": "11234567890"
},
"message_template": {
"name": "verify_template"
},
"security_factor": "123456",
"verification_policy": [
{
"method": "viber",
"fallback_time":60
},
{
"method": "rcs",
"fallback_time":120
}
]
}
Unsuccessful response
This is an unsuccessful response returned after an attempt using the wrong template name.
HTTP/1.1 200 OK
Content-Type: application/json
{
"mobile_app_token": "948861fb5d0446ad9475d18d8a59c6e6",
"recipient": {
"phone_number": "11234567890"
},
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"state": "CREATED",
"status": {
"code": 3901,
"description": "Request in progress"
}
}
Unsuccessful callback example or GET example
When you have callbacks or delivery reports (DLRs) enabled, an unsuccessful request or an unsuccessful GET results in additional details including the reason for the failure provided to you. In this case, the callback notes that "Specified template does not exist for selected channel".
curl --request POST \
--url https://your-callback-url.com/verify_dlr_endpoint \
--header 'content-type: application/json' \
--data '
{
"created_on": "2024-09-02T13:10:21.328000Z",
"inner_methods": [
{
"err_code": 3112,
"err_msg": "Specified template does not exist for selected channel",
"expires_on": "2024-09-02T13:11:21.339000Z",
"method": "viber",
"state": "FAILED",
"tried_on": 1725282621339,
"updated_on": "2024-09-02T13:10:21.356545Z"
},
{
"err_code": 3112,
"err_msg": "Specified template does not exist for selected channel",
"expires_on": "2024-09-02T13:15:21.360000Z",
"method": "rcs",
"state": "FAILED",
"tried_on": 1725282621360,
"updated_on": "2024-09-02T13:10:21.000000Z"
}
],
"push_registration": false,
"recipient": {
"phone_number": "11234567890"
},
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"state": "FAILED",
"updated_on": "2024-09-02T13:10:21.401000Z",
"verification_policy": [
{
"fallback_time": 60,
"method": "viber"
},
{
"fallback_time": 300,
"method": "rcs"
}
]
}
Updated 11 days ago