REST

Integrate SMS Sending Capabilities

Looking for information regarding our v1 documentation? Contact us now for further details.

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. You can generate these inside your MXT account. The REST API can be accessed at api.smsglobal.com. 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.

Authentication Scroll to Top ▲

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"

Authorization header fields Scroll to Top ▲

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

FieldMeaning

id

Your API key, issued to you by SMSGlobal. Information on managing API keys can be found here .

ts

The Unix timestamp of the time you made the request. We allow a slight buffer on this in case of any time sync issues.

nonce

A randomly generated string of your choice. Ensure it is unique to each request, and no more than 32 characters long.

To prevent replay attacks, a single nonce can only be used once.

mac

This is the base 64 encoded hash of the request.

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\n
 random-string\n
 POST\n
 /v2/sms/\n
 api.smsglobal.com\n
 443\n
 \n

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 Scroll to Top ▲

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

Status CodeMeaningScenario

200

OK

The request was processed successfully

400

Bad Request

Your request contained invalid or missing data

401

Unauthorized

Authentication failed or the Authenticate header was not provided

404

Not Found

The URI does not match any of the recognised resources, or, if you are asking for a specific resource with an ID, that resource does not exist

405

Method Not Allowed

The HTTP request method you are trying to use is not allowed. Make an OPTIONS request to see the allowed methods

406

Not Acceptable

The Accept content type you are asking for is not supported by the REST API

415

Unsupported Media Type

The Content-Type header is not supported by the REST API

Response and Request Data Formats Scroll to Top ▲

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

Supported Request Formats Scroll to Top ▲

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

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

Supported Response Formats Scroll to Top ▲

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 Scroll to Top ▲

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.

Delivery Receipts Scroll to Top ▲

Click here to see more on Delivery Receipts

Message Status Updates Scroll to Top ▲

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

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.

FieldMeaning

id

Message part identifier

status

Current status of the sms message

update_time

The date in UTC when the message status was updated

outgoing_id

Outgoing message identifier

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

Incoming Messages Scroll to Top ▲

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.

FieldMeaning

to

Mobile Terminated Number, where the message was sent to

from

Mobile Originated Number, where the message was sent from

msg

Contents of the message

date

Date the message was received by SMSGlobal.

msgid

Message identifier

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

API Endpoints Scroll to Top ▲

  • auto-topup
    /v2/auto-topup
  • contact group
    /v2/contact/{id}
    /v2/group
    /v2/group/{groupId}/contact
    /v2/group/{groupId}/contacts
    /v2/group/{id}
  • dedicated-number
    /v2/dedicated-number
  • opt-outs
    /v2/opt-outs
    /v2/opt-outs/validate
    /v2/opt-outs/{number}
  • sharedpool
    /v2/sharedpool
    /v2/sharedpool/{id}
  • sms
    /v2/sms
    /v2/sms{id}
  • sms-incoming
    /v2/sms-incoming
    /v2/sms-incoming/{id}
  • user
    /v2/user/billing-details
    /v2/user/contact-details
    /v2/user/credit-balance
    /v2/user/low-balance-alerts
    /v2/user/sub-account
    /v2/user/verified-numbers
Loading Form