Verify By SMS With Your Own Code

This page walks you step-by-step through how to use the 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.

Before you begin, set up the Transaction Callback Service so you can get the delivery status of the SMS messages you send.

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

  • (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

  1. 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 Request
HTTPS
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
&verify_code=57244
&template=Your code is $$CODE$$
  1. The service then sends an SMS message, replacing the $$CODE$$ variable in the message template with your verification code.
Generated Message
Generated Message
  1. Save the value of the property reference_id from the response to use later when getting delivery status.
  2. The status.code and status.description properties in the response indicate the preliminary delivery status of the SMS.
SMS Verify Response
HTTPS
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

  1. 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.
  2. Search for a call from TeleSign to your Transaction Callback Service for this integration, based on the reference_id property in the payload. Look for a value in this property that matches the reference_id of the SMS Verify transaction you saved earlier.
  3. The status.code and status.description properties in the payload of that call indicate the delivery status all the way to the end-user.
Callback Request
HTTPS
POST /your_resource HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json
Host: yourcallbackurl.com

{ 
  "status": { 
     "updated_on": "2016-07-08T20:52:46.417428Z", 
     "code": 200, 
     "description": "Delivered to handset" 
   }, 
   "submit_timestamp": "2016-07-08T20:52:41.203000Z", 
   "errors": [], 
   "verify": { 
     "code_state": "UNKNOWN", 
     "code_entered": null 
   }, 
   "sub_resource": "sms", 
   "reference_id": "0123456789ABCDEF0123456789ABCDEF" 
}

Step 3: Report Completion

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 transaction.

Completion Request
HTTPS
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
HTTPS
HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "code": 1900,
    "updated_on": "2014-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.