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.

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. You can get this value in the response to a previous SMS API request. You can send a test SMS and collect this value by reviewing the Send an SMS page.

To try out getting the status of your transaction using the API Explorer, do the following:

  1. Open the reference page for the GET /v1/messaging/{reference_id} endpoint.
  2. Under the PATH PARAMS header in the middle panel of the page, enter the reference ID from your previous SMS API transaction.
  3. Under the AUTHENTICATION header in the right panel of the page, put your Customer ID in the username field and your API key in the password field.
  4. Click Try It! in the right panel to see your transaction.
  5. If you want you can also click the copy icon to the left of Try It! to copy the code snippet displayed. To change the programming language of the snippet, select one of the options under the LANGUAGE header in the right sidebar.

Congratulations! You've just retrieved the status of the SMS request you sent.

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.

Did this page help you?