REST SMS Gateway API – Specification Document

This blog post has been superseded with our website documentation

For an overview of what REST and our RESTful SMS API is all about you may like to read our RESTful SMS API Overview.
If you prefer you can use the simple SMS gateway, rather than our RESTful implementation.
To get straight into the details, jump to:
Quick Start
Error codes
Sandbox
You can preform the following actions using the REST web service:

• send an SMS (sms post)
• get the number of credits available (credits get)
• transfer credits from one account to another (credits post)
• get a list of delivery reports (deliveryReports get)
• get the contents of a specific delivery report (deliveryReport get)
• check availability of a given keyword on our ShortCode number (keywords get)
• check the names and IDs of your send groups
• add number(s) to a send group

Specification of the resources

1. credits
2. deliveryReports
3. deliveryReport
4. sms
5. keywords
6. group
7. groups

QUICK START

Three things are essentially needed to use the REST SMS API:

1. Ability to make a HTTP request
   • e.g. to https://api.textmarketer.co.uk/services/rest/credits
2. Ability to read the HTTP response headers
   • e.g. ‘200 OK’
3. Ability to parse the XML response
   • e.g. <credits>37</credits>

The Request URI Explained

You will make the HTTP request to a request URI such as:

https://api.textmarketer.co.uk/services/rest/credits

The base request URI is thus composed of :
‘https://api.textmarketer.co.uk/services/rest/‘ + a string that denotes the resource to be accessed, e.g. ‘credits‘, ‘deliveryReports‘, etc.
You can use http instead of https, but https is recommended.
Note that cAsE matters, i.e. ‘deliveryReports‘ will work, whereas ‘deliveryreports‘ (lower case ‘r’) will return an error.
You must obviously identify yourself during the request. If you know how to handle HTTP Digest Authentication, that is the preferred method of authentication.
Otherwise you should attach the following to the end of the resource URI:

?username=myAPIusername&password=myAPIpassword

Or, in the case of a POST request, such as for sending an SMS, include the username/password parameters in the POST parameters (e.g. see sms post).
In our example, the complete URI that results is:

https://api.textmarketer.co.uk/services/rest/credits?username=myAPIusername&password=myAPIpassword

And this should return XML containing the number of credits available on your account.
The HTTP Response Headers
The only vital part of the response headers that you need is the status code. 200 means a successful request, all other codes returned will be errors.
If you get an error, the status message may give you some extra information about the error. For more details about the error codes and their meanings, see Error Codes below.
The XML response
The structure of the XML response is generally quite simple. The response to our credits request example would look like this:

<response processed_date="2010-03-19T14:08:40+00:00">
<credits>37</credits>
</response>

Your preferred programming language will have a method for parsing the XML response to obtain the value.
Example PHP code

<?php
/**
 * GET request on the 'credits' resource
 */
$url = 'http://api.textmarketer.co.uk/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";
// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);
// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);
	$credits = (int) $xml_obj->credits;
	// do something with the result
	echo $credits;
} else {
	// handle the error
	var_dump($responseBody);
}
?>

See the REST API Code Examples for some more example code that you can use.
That’s the end of the Quick Start. You know to send the request, check the status code is 200, and then parse the XML according to its declared structure.

Error codes

ERROR CODES

The HTTP status codes returned by our REST SMS API follow normal HTTP conventions. An example of the HTTP response headers from a request to our REST API:

Date: Wed, 24 Mar 2010 14:45:54 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 317
Connection: close
Content-Type: application/xml
404 Not Found :  (ERR101)

You see the status code, 404 on the last line. Their meaning of the status codes in the context of our REST SMS API are as follows:

IMPORTANT NOTE: Error 503 may be returned if you exceed a certain number of requests per minute. You will see an error message similar to: “Your 201 requests exceed the maximum allowed of 100 requests within 15 minute(s). Please try again later”. This to reduce load on our servers, in order to guarantee a good service to all our users.  There is no restriction on SMS sends.
USEFUL NOTE: the HTTP status message may contain more specific information. If you encounter an unexpected error, the ‘(ERRnn)’ found in the status message is useful in any reports you send us.
In addition to the status codes, an error will also produce an XML response containing details of the error. In this example the XML response might look like this:

<response processed_date="2010-03-24T14:45:54+00:00">
<errors>
	<error code="404">Not Found :  (ERR101)</error>
</errors>
</response>

Some resources, such as https://api.textmarketer.co.uk/services/rest/sms/, have additional error codes specific to the resource. These are documented along with the description of the resource.

Resource Identifier

THE RESOURCE IDENTIFIER

The example of a resource identifier used previously was:
https://api.textmarketer.co.uk/services/rest/credits
All our REST SMS Web Service resource identifiers take the general form:

PROTOCOL://RESOURCE_NAMESPACE/RESOURCE_NAME[/RESOURCE_ID]

where

PROTOCOL = http|https
RESOURCE_NAMESPACE = api.textmarketer.co.uk/services/rest
RESOURCE_NAME = credits|deliveryReports|deliveryReport|sms|keywords|etc

RESOURCE_ID = an_ID (optional) which specifies a particular resource element, e.g. a specific delivery report

e.g.

https://api.textmarketer.co.uk/services/rest/deliveryReport/GatewayAPI_09-02-10

will access a delivery report named ‘GatewayAPI_09-02-10‘.

Resources

RESOURCES

The currently implemented resources are:

1. credits
2. deliveryReports
3. deliveryReport
4. sms
5. keywords
6. group
7. groups

1. credits

http://api.textmarketer.co.uk/services/rest/credits

• GET method – get the number of credits currently available on your account
• POST method – transfer credits between accounts

2. deliveryReports

http://api.textmarketer.co.uk/services/rest/deliveryReports

• GET method – Gets a list of available delivery report names

See the full description of this resource for details.
3. deliveryReport

http://api.textmarketer.co.uk/services/rest/deliveryReport/test-190310

• GET method – Gets the contents of a delivery report – the delivery status of sent messages for a given day/campaign.

See the full description of this resource for details.
NOTE: An individual delivery report that is accessed using this resource shows the current known status of all messages sent on a given day, or for a particular campaign. The REST API resource deliveryReports (note the trailing ’s’) gets a list of available delivery report names, including delivery reports for campaigns (see above).
4. sms

http://api.textmarketer.co.uk/services/rest/sms

• POST method – Used to send an SMS message.

5. keywords

http://api.textmarketer.co.uk/services/rest/keywords/mykeyword

• GET method – get the availability of a given keyword (see Short Code SMS Service)

See the full description of this resource for details.
6. group

http://api.textmarketer.co.uk/services/rest/group

• POST method – add number(s) to a send group

See the full description of this resource for details.
7. groups

http://api.textmarketer.co.uk/services/rest/groups

• GET method – list the available send groups

See the full description of this resource for details.

Sandbox

TESTING/SANDBOX

A sandbox service is available to allow you to test your integration code without using any credits or executing any function that would modify the data in your account. The service is available at
http://sandbox.textmarketer.biz/services/rest
i.e. only the hostname changes from api.textmarketer.co.uk to sandbox.textmarketer.biz within the resource URI.
The sandbox will do the same validation of your request as the live REST API and return the appropriate errors, but will not perform any action that modifies your account data or your credits. Nor will it actually send any SMS messages, so no delivery report will be generated.
NOTE: Accesses to the sandbox is limited to a certain number of requests per minute – to reduce load on our servers – in order to guarantee a good service to all our users. Therefore you may prefer to use the Sandbox only to check that individual requests work correctly, rather than testing bulk SMS sends. There is no restriction on SMS sends on the live system.