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

1. Send a POST /verify/sms request to the SMS Verify API. Include the following param values:

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$$

2. The service then sends an SMS message, replacing the $$CODE$$ variable in the message template with a verification code.

3. Save the value of the property reference_id from the response. You will need it to complete the verification flow.
4. The status.code and status.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.

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

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

2. In the response, if the value of the verify.code_state property is VALID, the verification completed successfully.
3. 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

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
  }
}

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