Get Started with the SMS API

TeleSign’s SMS API is a REST API that allows you to easily send SMS messages. You can send alerts, reminders, and notifications, or you can send verification messages containing one-time passcodes (OTP).

This page provides instructions and references for features of the SMS API and associated tools.

Request Requirements
Send an SMS
Obtain Transaction Status Results
Buy a Phone Number (Sender ID)
Inbound SMS
URL Shortener
SMS API Examples
Compliance

Request Requirements

Base URL: https://rest-ww.telesign.com/v1/messaging
Authentication: Basic (easiest to implement) or Digest
Encoding: Accepts only UTF-8 unicode characters as inputs.
MIME Type: application/x-www-form-urlencoded
Required Headers: Content-Type - application/x-www-form-urlencoded

Send an SMS

For quick instructions about how to send your first SMS, see the Send an SMS page.

For a list of available parameters, see the POST /v1/messaging page.

Obtain Transaction Status Results

There are two ways to check the status of your transactions:

Get Status API - Get the status of an individual transaction by querying a REST API, for up to 12 hours after sending your message.
Transaction Callback Service - Receive status updates from TeleSign about multiple transactions, at a URL that you provide. Receive status updates from TeleSign about multiple transactions, at a URL that you provide. We recommend using this when you have a high volume of transactions.

Buy a Phone Number (Sender ID)

TeleSign offers the option of buying a sender ID (dedicated phone number) through us to use to send messages with the SMS API. For more details see Phone Numbers API.

Inbound SMS

If you need to receive messages back from customers, a related service that we offer is Inbound SMS. For more about this service, see Inbound SMS.

NOTE:

Speak with our Customer Support Team to enable this feature.

URL Shortener

To help shorten your text messages, TeleSign provides a complimentary URL shortening service. You can read more about how to enable it here: URL Shortener.

SMS API Examples

This section provides examples of a request and response using the SMS API.

POST Request and Response Examples

You use a POST request to send your message.

NOTE:

The phone number in the example is for display only.

Example POST Request with the SMS API

POST https://rest-ww.telesign.com/v1/messaging HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Date: Tue, 31 Jan 2017 14:51:26 GMT

phone_number=15551212&external_id=CustomExternalID_7349&message=Your message here.&account_lifecycle_event=create&originating_ip=203.0.113.45

Here is an example POST response (when you use transaction callbacks to retrieve status information):

Example POST Response

HTTP/1.1 200 OK
Date: Tue, 31 Jan 2017 14:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 316
Allow: GET,POST
Content-Type: application/json

{
   "external_id": "CustomExternalID7349",
   "reference_id": "0123456789ABCDEF0123456789ABCDEF",
   "status": {
      "code": 290,
      "updated_on": "2017-31-03T14:51:28.709526Z",
      "description": "Message in progress"
   }
}

GET Request and Response Examples

You use a GET request to retrieve status information about your POST request.

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:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Date: Tue, 31 Jan 2017 14:53:11 GMT

The GET response body 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"
  }
}

Compliance

For SMS compliance best practices, please refer to the articles in the Compliance section in our Support Center.

Next Steps

This section offers some suggestions for next steps to take.

Send an SMS - Use TeleSign’s SMS API Explorer to send your first request.
POST /v1/messaging - View the API reference page for sending an SMS request.