SMS Verify API - Verify with your own code
This page walks you step-by-step through how to use Telesign SMS Verify API to send your own verification code to an end-user. It also explains how to complete verification and send us completion data to improve the service.
Keep the reference pages POST /v1/verify/sms and PUT /v1/verify/completion/{referenceid} 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.
- Transaction Callback Service: Set up the Transaction Callback Service so you can get the delivery status of the SMS messages you send.
- (Optional) Contact our Customer Support Team to configure any of these optional features:
- Validity period: A time duration in minutes after which a verification code expires.
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 |
verify_code | A numeric code as a string, between 000 and 9999999 . | The verification code used for the code challenge. By default, Telesign randomly generates a seven-digit numeric value for you. You can override the default behavior by including your own numeric code as a value for this parameter. Either way, the verification code replaces the variable $$CODE$$ in the message template. | 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 |
* You can directly include the verification code in your custom template if you prefer, but this is not recommended. If you use the Telesign default template, the verify_code
param is required.
SMS Verify API 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=1234567890
&verify_code=57244
&template=Your code is $$CODE$$
- The service then sends an SMS message, replacing the
$$CODE$$
variable in the message template with your verification code.
SMS Verify API response
HTTP/1.1 200 OK
Content-Type: application/json
{
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "sms",
"errors": [],
"status": {
"updated_on": "2022-10-03T14:51:28.709526Z",
"code": 290,
"description": "Message in progress"
},
"verify": {
"code_state": "UNKNOWN",
"code_entered": ""
},
"additional_info": {
"message_parts_count" : 1
}
}
- Save the value of the property
reference_id
from the response to use later when getting delivery status. - 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.
Step 2: Complete verification and report completion
- Once your end-user has submitted a potential code through your application, compare it to the verification code you created. If the two codes match, the verification completed successfully.
- (Optional) We recommend that you notify Telesign each time you successfully verify an end-user, by sending a
PUT /verify/completion/{reference_id}
request that includes the reference ID from the original SMS Verify API transaction.
Completion request
PUT https://rest-ww.telesign.com/v1/verify/completion/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com
Completion Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"reference_id": "0123456789ABCDEF0123456789ABCDEF",
"sub_resource": "sms",
"errors": [],
"status": {
"code": 1900,
"updated_on": "2022-10-14T18:07:26.078515Z",
"description": "Verify completion successfully recorded"
}
}
NOTE:
Sending us completion data helps us identify and fix any issues with delivery, operators, and routes, which leads to a higher quality experience for you and your end-users.
Updated 7 months ago