Table of contents
Introduction To The Web API
SMSPrime exposes an HTTP Post Application Programming Interface (i.e. Web API) for corporate and premium users that lets you integrate short messaging services into your projects for multifarious applications including services like notification and reminder systems, confirmation systems, marketing and advertising systems etc.
A subset of the functionality already available in our client dashboard has been exposed as web methods to make it easy to automate certain tasks from within your applications and services.
Our Web API runs on top of HTTP, and can be implemented in most environments that support creating HTTP POST requests.
Activating The Web API
When a user is first registered on SMSPrime, an endpoint is created for that user that permits automatic method requests via the API.
However the endpoint is deactivated by default for security reasons and has to be enabled on a per user basis. To activate the Web API, login to your dashboard on http://smsprime.com/user/login/ with a valid account.
Navigate the menu to API -> Activate to get to the Web API section.
Generate a API Key to use for your requests, and then click on the Activate button.
Copy and save the key for later use.
The Web API URL
The primary SMSPrime URL for sending your requests varies for each client, but it usually goes in the template form:
The parameters in square brackets can be any of:
- username - The username of the client registered on SMPrime
- datatype - The input and output data format. SMSPrime currently supports the use of the strings xml, and json
Consider a scenario for a client registered on SMPrime as userfoo, who wants to send an SMS to a client from his website.
A sample request to send an SMS message using XML would be posted to a URL that looks like this:
Request and Response Data Structure and Formats
SMSPrime currently supports two platform independent mime formats (i.e. XML,JSON) for exchanging data via the Web API.
A request is essentially initiated by building a request block in your preferred mime format with the essential instructions.
Consider the generic synopsis of a request:
Notice how the name of the root xml element is Request
The JSON variation would look something like this:
Again, notice how the root element is named Request
The internal structure of the data block is similar, and interchangeable between these data formats. Which format you use depends on which one best suits your application and needs.
HTTP Responses are similarly built into the requested format and are wrapped up in Response tags or elements,as appropriate.
Authentication and Signature
The SMSPrime Web API is an authenticated service. Only registered users on the SMSPrime network can make requests via the API.
It is important to note that SMSPrime does not require you to authenticate the request with your password in clear text. Each request is made to a per-user URL, and the mime data must contain a head section which carries the signature of the user. The signature is obtained from an md5 hash of the concatenation of the user's API Key and username.
The signature of the user can be generated thus in language agnostic terms:
The plus operator in that illustration merely indicates a concatenation of the two string fields (i.e. the username, and the API Key).
Hence the head block of the request would be built thus in XML:
Where the signature is the md5 hash of the concatenation of the username and key generated from your console at SMSPrime.
Web API Service Methods
Web methods are the ways by which tasks are executed on the Web API. Each request must specify a method as a unit of execution within a request via the API. Based on the specific method, parameters may be needed to further define the context in which the method must run.
A sample template request with a method and parameters is as follows:
The following methods are supported:
The send method directs the platform to send an SMS on your behalf. It works with the following parameters:
|Parameter||Parameter Specification||Parameter Options||Sample|
|type||Type of message to send||default,flash||flash|
|destination||A comma separated list of mobile recipients. Take care to format these recipients in their international formats||A valid MSISDN||2348034853921|
|source||Your sender id||A maximum of 11 characters for alpahnumeric names and 16 for numbers||Mr Sender|
|header||A header for binary and concatenated messages, optional||A valid UDH|
|shortmessage||The SMS message||A string that must be a maximum of 160 characters|
|group||The name of a group or list that exists on SMSPrime, optional||A valid group name||group one|
A sample request block would go as follows:
This request also includes an auxillary instruction that requests the user's balance after the operation. A sample response from the server would go something like:
An outright balance method directs the platform to return the user's current balance. It has no parameters.
A balance request looks like this:
A sample response look like this:
Standard Error Codes
SMSPrime supports the following error codes on the API
|303||Request is empty or invalid. No data found|
|304||Request data is not well formed|
|305||Request method is not allowed|
|306||Your request was not processed|
|307||No method was indicated or invalid method|
|399||399 features a range of platform specific error codes varied by context|
This section features some examples in specific languages. For all intent and purposes, we will assume the following:
username : johnsmith
API Key : 84212BF54BD90A6B42B0E96B88E5AEE3
data format : XML
Derivate API URL : https://smsprime.com/api.module/johnsmith/xml