Authentication
Try the API Explorer
APIs
SMS API
SMS Verify API
Bulk SMS API
Anonymous SMS API
Voice Verify API
Phone Numbers API
PhoneID API
Score API
Completion API

Get Started with the Get Status API

This API is only for use with TeleSign’s SMS Verify, Voice Verify, and Smart Verify APIs. You use it to retrieve the status of individual transactions for voice or SMS messages from these products.

You use it for two situations:

  • If you provided your own OTP code in a message using one of the SMS Verify, Voice Verify, or Smart Verify APIs, you can do a regular Get Status request.
  • If you let TeleSign provide your OTP code for you, then you must do a request where you send completion data.

Completion data consists of the reference ID for the end user’s transaction, and the code the end user entered (exactly as the end user entered it). Completion data is used by TeleSign to determine the outcome of a transaction.

While providing completion data is not required if you generate your own OTP codes, it is strongly recommended, so that TeleSign can better monitor the quality and security of the services TeleSign provides to you.

The following sections cover the topic of verifying transaction statuses and providing completion data:

NOTE:

If you will have a high volume of service requests, TeleSign recommends setting up the Transaction Callback Service instead. Read about setting up this service and available features on the Transaction Callback Service page.

Get Status API Information

All requests submitted for the Get Status API:

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

Use Get Status to Request the Status of a Transaction

Read about how to use the Get Status API in the scenario where you had TeleSign choose your verification codes for you here: Get Transaction Status

Get Status is the term used to refer to the Verify web service that allows you to manually verify the status of a user transaction. Get Status is available for use with the products SMS Verify, Voice Verify, and Smart Verify.

If you want to receive the status of transactions for a high volume of transactions, see the Transaction Callback Web Service page.

NOTE:

If your configuration includes having TeleSign generate verification codes for your end users, you must also use Get Status to send TeleSign your completion data.

Get Status Examples

This section provides examples of what a Get Status request and response looks like.

Here is an example of how to get the status of a transaction using a Get Status request:

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

The header for a response from TeleSign to this request looks like this:

Example GET Status Response
HTTP/1.1 200 OK
Date: Wed, 29 May 2013 00:09:08 UTC
Server: CERN/3.0 libwww/2.17
Content-Length: 314
Allow: GET,POST,HEAD
Content-Type: application/json

{
   "reference_id" : "ABCDEF0123456789ABCDEF0123456789",
   "sub_resource" : "sms",
   "errors": [],
   "status" : {
      "updated_on" : "2015-04-17T22:26:43.784963Z",
      "code" : 290,
      "description" : "Message in progress"
   },
   "verify" : {
      "code_state" : "UNKNOWN",
      "code_entered" : ""
   },
   "number_deactivation_status" : {
      "error_code" : "0",
      "description" : "Number Deactivation check succeeded",
      "last_deactivated" : "2015-02-02T10:41:55.464231Z"
   },
   "additional_info": {
      "code_entered": null,
      "message_parts_count" : 1
   }
}

Use Get Status to Share Completion Data

If you decided to have TeleSign set up the verification code, then you must send completion data where you send TeleSign the code that the end user provided. You can read more about this on the Get Status with Completion Data page.

Next Steps

This section offers some suggestions for next steps to take.

  • SMS Verify API - Check out the SMS Verify API and learn about using it to send one-time password (OTP) messages. This is one of the APIs that would use the Get Status API.
  • Voice Verify API - Check out the Voice Verify API and learn about using it to send one-time password (OTP) voice messages. This is one of the APIs that would use the Get Status API.