Want to provide feedback?

Write to docs@telesign.com.

Transaction Callback Service

Use the TeleSign Transaction Callback web service to get the transaction status of requests to another TeleSign service. While the Get Status API is used to learn about the status of individual transactions, the Transaction Callback web service can be used to learn the status of multiple transactions at the same time. It makes more efficient use of network system resources (for example, bandwidth or server load) in these cases, and so is best suited to TeleSign customers that have a high volume of transactions.


This service is only usable with the RCS API, SMS API, SMS Verify API, Voice API, Voice Verify API, and Inbound SMS service.


You must use standard ports for transaction callbacks to work properly. For HTTPS (transport layer security (TLS)), the default standard port is 443.

Service Setup

To use the Transaction Callback service:

  1. Create a private URI on your web server for receiving callback notifications from TeleSign. Fields that will be sent back with the JSON formatted response include:
  • Custom Authorization header (refer to section Authenticate Callbacks from TeleSign below).
  • Reference ID
  • Sub-Resource
  • Errors
  • Status: Updated On
  • Status: Code
  • Status: Description
  • Verify: Code State
  • Verify: Code Entered
  • Verify: Code Submitted
  • Submit Timestamp
  • Additional Info: MNC (see NOTE 2)
  • Additional Info: MCC (see NOTE 2)
  • Additional Info: Price
  • Additional Info: Currency

For mission critical applications, TeleSign recommends that you provide redundancy by implementing two URIs instead of one.


Additional Info is an optional parameter that returns Mobile Network Code (MNC) and Mobile Country Code (MCC). You must request that our Customer Support Team enable the Additional Info parameter if you want it returned.

  1. Provide TeleSign with your private URI.
  2. Allow 1 business day for setup to be completed.
  3. You will receive callback notifications after both of the following occur:
    • A verification transaction completes
    • TeleSign determines the final status of the transaction (refer to the section Transaction Status Codes on the Codes, Languages, and Timezones page for a list of status codes that may be returned).
  4. If TeleSign is unable to deliver your callback notification on the first attempt, the TeleSign server waits 30 seconds, then tries again. If the second attempt fails, the server waits an additional 5 minutes and then makes a final attempt. After that, to obtain verification information, your application should resort to using the Get Status (pull) mechanism, described above.
Contents of a Successful Callback Notification
  "status": {
    "updated_on": "2019-09-20T12:43:46.710291Z",
    "code": 200,
    "description": "Delivered to handset"
  "submit_timestamp": "2019-09-20T12:43:45.339000Z",
  "errors": [],
  "verify": {
    "code_state": "VALID",
    "code_entered": "12345"
  "sub_resource": "sms",
  "reference_id": "C5B53ACC84EC01048994FE7AADF900CD",
  "additional_info": {
    "message_parts_count": 1,
    "price": "0.5112",
    "mnc": "05;09",
    "mcc": "220",
    "currency": "USD"

Here is a diagram of what the flow would look like, using SMS Verify for the example. The flow is the same for Voice Verify.

Authenticate Callbacks from TeleSign

You can authenticate callbacks for added security. For more details on how to do this, see Authenticated Callbacks With the Transaction Callback Service.

Transaction Callback Examples

Here is an example of a Verify Transaction Callback service POST request to your provided URL:

Example Verify Transaction Callback
Accept-Encoding: gzip, deflate
Authorization: Basic 78E5ACC9-83C1-4E25-BE21-44A0CA1D57B4:KdpP11dPeAUW/6IVRx30JA3FG1eCOFVoE8ojI8NqnTA=
Content-Length: 308
Content-Type: application/json
User-Agent: python-requests/2.9.1

  "status": { 
     "updated_on": "2016-07-08T20:52:46.417428Z", 
     "code": 200, "description": "Delivered to handset" 
   "submit_timestamp": "2016-07-08T20:52:41.203000Z", 
   "errors": [], 
   "verify": { 
     "code_state": "UNKNOWN", 
     "code_entered": null 
   "sub_resource": "sms", 
   "reference_id": "2557312299CC1304904080F4BE17BFB4"