Documentation

With our SMS messaging API you can:

• Send SMS messages
• Receive real time delivery reports (DLR) for all messages sent
• Receive replies and inbound SMS messages
• Access a range of other useful messaging functions such as Lists, Virtual Numbers, Keywords & Reseller features

Our simple REST API allows you to get up and running in minutes, just follow the helpful Quick Start guide. For advanced users, dig deeper into our technology and check our reference guides for more detailed functions and calls. We have a wide range of calls to mirror useful functionality on the site at both user and reseller level. We also offer a number of client libraries and code samples in order to make your experience using the API suite as clean as possible.

So let's now look at how to use and get the best out of the REST API.

Numbers

Numbers are the Caller ID, or from field that your messages will come from. Although not mandatory for API use, we recommend users lease their own Dedicated Virtual Number to send and receive messages through the API. You can choose and lease a dedicated number in the NUMBERS section of your account. This will give you the benefit of having your own number identity that is unique to your account. You are welcome to use the free shared number pool, but will be sharing these numbers with many other small customers, and you won't be likely to get the same number each time you send a message.

Request

All requests must be to the base URL. We provide you with an option of a response as a JSON object, or an XML string. You can choose which response you want by selecting the appropriate suffix (.json OR .xml) in your request.

Base URL: 

https://api.transmitsms.com

HTTP Methods

All requests are submitted through the HTTP POST or GET method using UTF-8 encoding and URL encoded values.

Security

To ensure total security & privacy the API only works over HTTPS protocol for all requests. Also, for your own security, If you have a website with a form which sends SMS be sure to send the request from your server and not directly from the browser otherwise you will be giving away your API secret and opening the floodgates to unwanted charges.

Authentication

All API requests require your API credentials, you will find them once logged into your Account on the API settings page.

Throttling

To provide the best service to all our customers we limit the number of API calls which can be made by each account to 2 calls per sec. For heavy users we can increase your throttling speed, but please contact us to discuss your requirements. If you exceed this limit we will return two indicators which you can use in your code to detect that you have been throttled. The first is the HTTP status code 429 "Too Many Requests", the second is the error code "OVER_LIMIT" in the error block of the response body.

Timestamps

All timestamps are in ISO8601 format, e.g. YYYY-MM-DD HH:MM:SS. The zone is always UTC.

Pagination

Some responses are too large to be returned in one go so we paginate. To identify which calls use pagination look for the "page" and "max" parameters in the parameter descriptions for each API call. These calls include a "page" block in the response with two values, "count" and "number". Count tells you how many pages are available and number indicates the page number you are on. The page parameter is used to request a certain page, it defaults to 1. The max parameter is used to limit the number of results returned per page, the default is 10, the maximum is 100.

Error Reporting

Always check if your API call was successful or resulted in error. You may check the following

• 200 OK response header. It will be 4xx if an error occurred.
• error->code structure should equal to ‘SUCCESS’. Please check the table below for common error constants. Note that some API functions can return custom errors of their own (listed in appropriate document sections). Check the error->description for details, e.g. which field caused an error or which resource you don’t have access to.