REST API

Introduction

The REST API allows programmatic access to SMSGlobal features in MXT. To use the REST API, you will need an MXT account and an API key and secret.

Note: Login to your MXT account to create your REST API Key and Secret

Use of SSL is supported and strongly encouraged. The REST API takes full advantage of all HTTP headers. Each part of a request and response is meaningful, including the request method (GET/POST, etc.), the individual headers (Location, Content-Type, Accept, etc.), and the response status code (200, 400, 404, etc.). Use of this API assumes a working knowledge of these HTTP components, and general use of RESTful web APIs.

API Endpoint

The REST API can be accessed at api.smsglobal.com

Postman Collection

Get started quickly with our Postman Collection for our API

Includes our REST, HTTP, SOAP and OTP API, with authentication scripts will get you sending messages in minutes.

Authentication

The REST API uses an authentication scheme based on this OAuth 2 specification. All requests to resources (excluding the schema pages) must be accompanied by a correct Authorization header as per this specification. The header looks like this:

Authorization: MAC id="your API key", ts="1325376000", nonce="random-string", mac="base64-encoded-hash"

NOTE: To get testing quickly, authentication is already handled in our Postman Collection scripts.

Authorization header fields

The value of the header is made up of the following components.

Calculating the mac hash

The hash is a SHA-256 digest of a concatenation of a series of strings related to the request. The string is:

Timestamp
Nonce
HTTP request method
HTTP request URI
HTTP host
HTTP port
Optional extra data

Each part of the string is separated by a line feed character (\n or 0x0A; not \r or \r\n). The entire string also ends with a line feed character. Here's an example for a POST request to the sms resource via HTTPS. The \n characters are shown for clarity.

1325376000
random-string
POST
/v2/sms
api.smsglobal.com
443

Note that the optional extra data line is blank. Our API does not currently use this field, but it must be included in the hash as an empty string as per the OAuth 2 specification. Once this string has been constructed, you must then hash it using the HMAC method, with your API secret (issued with your API key) used as the hash key. SMSGlobal uses the SHA-256 algorithm for hashing. It is recommended that you use a pre-existing library to calculate the hash, as it is quite calculated. Ensure the hash is output in binary, and not in hexadecimal. Once the hash is calculated, base 64 encode it and include it in the HTTP header. For this example, the hashed string is:

EJQ15pg5cEYsotgQaGyCHRxnPvmAemamOh6w7YRDif4

Things to check include checking to ensure the REST API keys are correct as well as the time they are authenticating with.

The computer must have accurate time as the authentication MAC is build using the time, so authentication will fail if the client computer time is different to our server time.

Response Codes

The following response codes apply to all requests. Check each request type in the list below for more response codes specific to that request.

Response and Request Data Formats

You can specify the formats you want to use for request and response data.

Supported Request Formats

Use the Content-Type header to specify the format your data is in.

• JSON: application/json
• XML: application/xml

Supported Response Formats

Use the Accept header to specify the output desired format.

If you can't set that header, use the format parameter in the query string. The format parameter takes precedence over the Accept header.

• JSON: application/json
• XML: application/xml

HTTP Post Backs

You can get HTTP post-backs for delivery receipts, message status updates and incoming messages.

Post-backs are HTTP GET requests by default and parameters passed in the query string. You can set the post-back format in the following formats.

• form+http://www.example.com/ for form encoded post
• json+http://www.example.com/ for JSON encoded post
• xml+http://www.example.com/ for XML encoded post

Delivery Receipts

Click here to see more on Delivery Receipts

Message Status Updates

SMSGlobal can notify you of change in message delivery status to allow you to monitor the status of messages sent.

Note: To use notifyURL, delivery receipts will need to be enabled in your MXT settings first.

Please find below the list of parameters that are sent.

Example (GET)

https://example.url?id=6419785166510955&outgoing_id=5346907663&status=Delivered&update_time=2020-09-16T16%3A32%3A17%2B10%3A00

Example (POST)

id=6419785166510955&outgoing_id=5346907663&status=Delivered&update_time=2020-09-16T16%3A32%3A17%2B10%3A00

Example (POST JSON)

{
"id":"6968154134564265",
"outgoing_id":"5347047793",
"status":"Delivered",
"update_time":"2020-09-16T16:50:33+10:00"
}

Example (POST XML)

<?xml version="1.0" encoding="UTF-8"?>
<delivery_receipt>
<id>6929949692100437</id>
<outgoing_id>5347049893</outgoing_id>
<status>Delivered</status>
<updated_time>2020-09-16T16:53:09+10:00</updated_time>
</delivery_receipt>

Incoming Messages

If you would like to receive notification of your Incoming SMS to be pushed to your server, please ensure you specify a URL in your outgoing message request or default URL in your account settings.

In order for our system to know that your URL has received the delivery notice, at the end of your script you must echo out “OK”.

Please find below the list of parameters that are sent.

Example (GET)

http://www.example.com/?from=61433111222&to=61499057767&msg=response+&date=2020-09-16+16%3A29%3A50&msgid=471047771

Example (POST)

from=61433111222&to=61499057767&msg=response+&date=2020-09-16+16%3A29%3A50&msgid=471047771

Example (POST JSON)

{
"from":"61433111222",
"to":61499057767,
"msg":"response ",
"date":"2020-09-16 16:51:59",
"msgid":471051471
}

Example (POST XML)

<?xml version="1.0" ?>
<incoming>
<from>61433111222</from>
<to>61499057767</to>
<msg>response</msg>
<date>2020-09-16 16:53:19</date>
<msgid>471051701</msgid>
</incoming>