SMS Verify API - Verify with Telesign code
This page walks you step-by-step through how to use Telesign SMS Verify API to send an SMS 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.
Keep the reference pages POST /v1/verify/sms and GET /v1/verify/{reference_id} open in another window while you work on these steps.
Before you begin
- Upgrade your account: Upgrade to a paid account if you are using a trial account.
- "From" phone number: You must buy a “from” phone number from Telesign before sending OTPs to any number other than the one you registered your account with.
- (Optional) Contact our Customer Support Team to configure any of these optional features:
- Validity period: The time duration in minutes after which a verification code expires.
- Max attempts: The number of times an end user can submit potential matches for a specific verification code. If this number is five, for example, an end user's sixth submission is rejected, even if it matches the original code.
Step 1: Send the SMS
- Send a
POST /verify/sms
request to the SMS Verify API. Include the following param values:
Parameter | Value | Description | Required? |
---|---|---|---|
phone_number | Digits without spaces or special characters. | The end user’s phone number you want to send a message to, beginning with the country/dialing code. | yes |
template | Text with a variable. | Text that overrides the contents of the predefined message templates. Include the $$CODE$$ variable to have the verification code automatically inserted. | no |
SMS API Verify request
POST /v1/verify/sms HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com
phone_number=15558675309
&template=Your code is $$CODE$$
- The service then sends an SMS message, replacing the
$$CODE$$
variable in the message template with a verification code.
- 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.
SMS API Verify Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "sms",
"errors": [],
"status": {
"updated_on": "2015-10-03T14:51:28.709526Z",
"code": 290,
"description": "Message in progress"
},
"verify": {
"code_state": "UNKNOWN",
"code_entered": ""
},
"additional_info": {
"message_parts_count": 1
}
}
NOTE:
The
status.code
property gives you status of delivery to the destination carrier, not necessarily all the way to the end-user.
Step 2: 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.
- Send a
GET /verify/{reference_id}
request.- Include the end-user's potential code in the
verify_code
query parameter. - Include the
reference_id
for the transaction in thereference_id
path parameter.
- Include the end-user's potential code in the
Get status request
GET /v1/verify/0123456789ABCDEF0123456789ABCDEF?verify_code=57244 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com
- In the response, if the value of the
verify.code_state
property isVALID
, the verification completed successfully. - The
status.code
andstatus.description
properties in the payload of that response indicate the delivery status all the way to the end-user.
Get status response
HTTP/1.1 200 OK
Content-Type: application/json
{
"reference_id": "ABCDEF0123456789ABCDEF0123456789",
"sub_resource": "sms",
"errors": [],
"status": {
"updated_on": "2015-04-17T22:26:43.784963Z",
"code": 200,
"description": "Delivered to handset"
},
"verify": {
"code_state": "VALID",
"code_entered": ""
},
"additional_info": {
"code_entered": null,
"message_parts_count": 1
}
}
- If the value of the
verify.code_state
property isEXPIRED
orMAX_ATTEMPTS_EXCEEDED
, the verification code is no longer matchable by your end user. If you still want to give them the opportunity to verify, make a new SMS Verify request to send them a new verification code.
Updated 7 months ago