Verify By SMS With TeleSign Code

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

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

  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
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 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
&template=Your code is $$CODE$$
  1. The service then sends an SMS message, replacing the $$CODE$$ variable in the message template with a verification code.
Generated Message
Generated Message
  1. Save the value of the property reference_id from the response. You will need it to complete the verification flow.
  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

Once your end-user has submitted a potential code through your application, complete the verification flow with a second API call.

  1. 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 the reference_id path parameter.
Get Status Request
HTTPS
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
  1. In the response, if the value of the verify.code_state property is VALID, the verification completed successfully.
  2. The status.code and status.description properties in the payload of that response indicate the delivery status all the way to the end-user.
Get Status Response
HTTPS
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": 201,
    "description": "Message is read"
  },
  "verify": {
    "code_state": "VALID",
    "code_entered": ""
  },
  "additional_info": {
    "code_entered": null,
    "message_parts_count": 1
  }
}
  1. If the value of the verify.code_state property is EXPIRED or MAX_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.