Want to provide feedback?

Write to docs@telesign.com.

Get Started with the SMS Verify API

The SMS Verify API delivers phone-based verification and two-factor authentication using a time-based, one-time passcode sent over SMS.

This page provides instructions and references for features of the SMS Verify API and associated tools.

General Information

All requests submitted for the SMS Verify API:

  • Can be authenticated with Basic (easiest to implement) and Digest authentication
  • Use https://rest-ww.telesign.com/v1/verify/sms as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type - application/x-www-form-urlencoded in request headers

Send an SMS with a Verification Code

For details about sending your first SMS containing a one-time password (OTP), refer to the Send an SMS with a Verification Code page.

If you want to see the API reference, go to the POST v1/verify/sms page.

Obtain Transaction Status Results / Send Completion Data

For information about obtaining details about transaction status, as well as providing completion data, refer to the Obtain Transaction Status Results / Send Completion Data page.

Response When You Enable Score

If you choose to enable Score with SMS Verify, you will be able to assess a phone number’s risk level for fraud (referred to as the phone number’s score) prior to sending an SMS verification message. If a phone number’s score is too high for the threshhold you select (work with your Customer Success Manager (CSM) to set this), you can block it.

You can find out more about Score on the following page:

You can learn more about enabling Score on the Send an SMS with a Verification Code page.

Buy a Phone Number (Sender ID)

TeleSign offers the option of buying a sender ID to use to send messages to your end users. A sender ID is sometimes referred to as a dedicated phone number.

You can use the Phone Numbers API to buy a phone number. This is best if you do not need to buy numbers in areas that have special restrictions. Details about the Phone Numbers API (and what areas have restrictions) are available on the Get Started with the Phone Numbers API page.

Alternatively, you can speak with your CSM to purchase one or more phone numbers to use as a sender ID. You need at least one if you want to receive messages using inbound SMS.

Inbound SMS

If you need to receive messages back from customers, an optional feature that can be made available is inbound SMS. You can learn more about this feature by reviewing the Inbound SMS page.

If you want to enable this feature, you must have:

  • a phone number available for use as a sender ID
  • a callback URL

URL Shortener

To help shorten your text messages, TeleSign provides a complimentary URL shortening service. You can read more about how to enable it and what features are offered here: URL Shortener.

SMS Verify API Examples

This section contains examples of requests and responses for the SMS Verify API.

POST Request and Response Examples

You use a POST request to send your OTP message.

Example POST Request with SMS Verify
POST https://rest-ww.telesign.com/v1/verify/sms HTTP/1.1
Accept-Encoding: gzip,deflate
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: ca10235f-f41a-4c54-baf1-1bd808f7404f
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Wed, 03 Oct 2015 14:51:26 -0700
Content-Type: application/x-www-form-urlencoded; charset=utf-8
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com
Content-Length: 59

phone_number=complete_number_with_no_special_characters_or_spaces
   &ucid=TRVF
   &originating_ip=203.0.113.45
   &language=en-US
   &verify_code=9876543
NOTE:

The request parameters are shown on separate lines for illustration purposes.

The response from TeleSign to a POST request from the SMS Verify API looks like this:

HTTP/1.1 200 OK
Date: Wed, 03 Oct 2015 14:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 316
Allow: GET,POST,HEAD
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
    }
}

GET Request and Response Examples

You retrieve verification results by sending a GET request message to the TeleSign web server.

You use a GET request with the reference_id you received in the POST response from TeleSign to retrieve transaction status information.

Example GET Status Request
GET https://rest-ww.telesign.com/v1/verify/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com

Here is an example response body from TeleSign to a GET request for an SMS Verify transaction:

Example Response Body for a GET Request for SMS
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2015-05-29T00:09:08.784963Z",
    "code": 1190,
    "description": "Transaction in progress"
  },
  "user_response": {
    "received": null,
    "verification_code": null,
    "selection": null
  }
}

Callback Service Verification Results

The following example illustrates the JSON objects delivered by the TeleSign Verify Transaction Callback service.

HTTP/1.1 200 OK
Date: Wed, 06 Nov 2015 13:35:40 -0800
Server: CERN/3.0 libwww/2.17
Content-Length: 296
Allow: GET
Content-Type: application/json

{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "submit_timestamp": "Wed, 06 Nov 2015 13:36:07 -0800",
  "sub_resource": "sms",
  "errors":[],
  "status": {
     "updated_on": "Wed, 06 Nov 2015 13:36:11 -0800",
     "code": 290,
     "description": "Message in progress"
  },
  "verify": {
     "code_entered": null,
     "code_state": "UNKNOWN"
  }
}

Verify a TeleSign-Generated Code Request and Response Example

When TeleSign generates the value of the verification code, you can check whether the code that the user entered matches the one that TeleSign generated. To do this, send a GET request with verify_code as an input parameter, and set it to the value the user entered. For example, if the code entered was 57244, you would make the GET request as follows:

GET https://rest-ww.telesign.com/v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244 HTTP/1.1

The response body from TeleSign when you include the verification code looks like this:

Example Response Body When You Send Verification Code
{
  "reference_id": "AEBC93B5898342F790E4E19FED41A7DA",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2015-04-17T22:26:43.784963Z",
    "code": 290,
    "description": "Message in progress"
  },
  "verify": {
    "code_state": "valid",
    "code_entered": "57244"
  }
}

Compliance

For SMS compliance best practices, please refer to the SMS Compliance section of the Compliance page.

Next Steps

This section offers some suggestions for next steps to take.