Want to provide feedback?

Write to docs@telesign.com.

Obtain Transaction Status Results

This page describes how you can retrieve the status of your request to send an SMS. You have two choices, you can do a status request to TeleSign and ask for the status of a message, or you can set up callbacks. Callbacks are better for high volumes of transactions. If you choose the callback method, TeleSign posts the status results for every transaction to a private URI that you select.

Read more here:

Status Request (GET)

You can test out doing a GET status request using the SMS API Explorer below. You need your credentials, and you must have sent an SMS and retrieved the reference ID for your request from the response. If you did not already do this, go to the Send an SMS page.

SMS API Explorer
NOTE: When using the SMS API Explorer, you will be charged your contracted rate for each transaction. The time shown in ms is not indicative of regular transmission rates, and only applies to the SMS API Explorer.
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
No $$.env variables are being used in this request.

To get the status of your transaction, do the following:

  1. Click the Settings tab.
  2. For the value field across from reference_id enter the reference ID number for the transaction you want to retrieve status information about. (See all available parameters on the API reference page - GET /v1/messaging.)
  3. Click the Auth [basic] tab.
  4. In the Username field, enter your Customer ID.
  5. In the Password field, enter your API key.
  6. Click Send.
  7. Congratulations! You’ve just retrieved the status of the SMS request you sent.
  8. To get a code snippet, click the Code Generation tab and choose the language and library you want to use to create the code.

Examples of a GET Request

An example request looks like this:

Example GET Request with the SMS API
GET https://rest-ww.telesign.com/v1/messaging/ABCDEF0123456789ABCDEF0123456789 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Date: Tue, 31 Jan 2017 14:53:11 GMT

An example response looks like this:

Example GET Response
  "external_id": "CustomExternalID7349",
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "submit_timestamp": "Tue, 31 Jan 2017 13:36:07 GMT",
  "status": {
    "code": 290,
    "updated_on": "Tue, 31 Jan 2017 13:36:11 GMT",
    "description": "Message in progress"
  "additional_info": {
    "mnc": "03",
    "mcc": "220"

Status Callback (POST)

Delivery results can be obtained by using TeleSign’s transaction callback service (ideal for high volumes of transactions). You provide TeleSign with a URL, and TeleSign posts the results of your transactions to the specified URL.

To set up the callback service, you do the following:

  1. Create a private URI on your web server for receiving callback notifications from TeleSign.
  2. Provide TeleSign with your private URI.
  3. You will receive callback notifications after a transaction completes.
  4. When you receive a callback notification, your server should respond to TeleSign with HTTP 200 OK response.
  5. If TeleSign does not receive a response, or is unable to deliver your callback notification on the first attempt, the TeleSign server waits 10 seconds, then tries again. If the second attempt fails, the server waits an additional 30 seconds and then makes a final attempt.

An example callback looks like this:

Transaction Callback
  "status": {
    "updated_on": "2017-06-29T05:23:10.341823Z",
    "code": 200,
    "description": "Delivered to handset"
  "external_id": "ts_test",
  "reference_id": "B573C93641E0016888403090CF48000B",
  "additional_info": {
    "message_parts_count": 1,
    "price": "0.8054",
    "currency": "USD",
    "mcc": "310",
    "mnc": "170;380"

SMS API Information

  • The URI is https://rest-ww.telesign.com/v1/messaging
  • Authentication - You can authenticate with basic or digest authentication
  • Use UTF-8 encoded unicode characters as inputs for all TeleSign APIs
  • Use Content-Type application/x-www-form-urlencoded in request headers

Next Steps

This section offers some suggestions for next steps to take.