Obtain Transaction Status Results

This page describes how you can find out about 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 find out the status of a specific transaction by sending a GET request that includes the reference ID (use the reference_id parameter) for the transaction. If you want to follow along here, you need a reference_id from sending an SMS request. You can send a test SMS and collect this value by reviewing 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.

You send a request to send an SMS message, and you get a response from TeleSign that the request was received. The next step is to send a request to check on the status of your SMS transaction. 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.
  3. Click the Auth [basic] tab.
  4. In the Username field, enter your customer ID.
  5. In the Password field, enter your API key. (See all available parameters on the API reference page - GET v1/messaging.)
  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.

An example request looks like this:

Example GET Request with the SMS API
GET https://rest-api.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
  "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 the 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 the 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-api.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.

You can read more about parameters you can send in an SMS request on the GET v1/messaging page.

Next Steps

This section offers some suggestions for next steps to take.