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 those 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

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

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

FieldMeaning
idYour API key, issued to you by SMSGlobal. Information on managing API keys can be found here.
tsThe Unix timestamp of the time you made the request. We allow a slight buffer on this in case of any time sync issues.
nonceA 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.
macThis 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

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.

Status CodeMeaningScenario
200OKThe request was processed successfully
400Bad RequestYour request contained invalid or missing data
401UnauthorizedAuthentication failed or the Authenticate header was not provided
404Not FoundThe 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
405Method Not AllowedThe HTTP request method you are trying to use is not allowed. Make an OPTIONS request to see the allowed methods
406Not AcceptableThe Accept content type you are asking for is not supported by the REST API
415Unsupported Media TypeThe Content-Type header is not supported by the REST API

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.

Delivery Receipts

Upon delivery confirmation from the carrier, SMSGlobal can notify you of message delivery status. This status will indicate whether the carrier was successful in delivering the message to the handset or whether an error occurred.

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”. To ensure this is the case please use the URL in your local browser before adding it in your settings.

Please find below the list of parameters that are sent.

FieldMeaning
outgoing_idOutgoing message identifier
statusDelivery status of the sms message. Status codes are Deleted, Delivered, Expired, Failed, Rejected, Undelivered, Unknown
update_timeThe date in UTC when the message status was updated
message_idsA collection of Message part identifiers

Examples

http://www.example.com/?outgoing_id=1267885033&status=Delivered&update_time=2015-07-31T10%3A13%3A16%2B10%3A00&message_ids%5B0%5D=6095320502740677&message_ids%5B1%5D=6095320502740688
outgoing_id=1267885033&status=Delivered&update_time=2015-07-31T10%3A13%3A16%2B10%3A00&message_ids%5B0%5D=6095320502740677&message_ids%5B1%5D=6095320502740688
{
  "outgoing_id" : 1267885033,
  "status" : "Delivered",
  "update_time" : "2015-07-31T10:13:16+10:00"
  "message_ids" : ["6095320502740677","6095320502740688"]
}
<?xml version="1.0"?>
<delivery_receipt>
  <outgoing_id>1267885033</outgoing_id>
  <status>Delivered</status>
  <update_time>2015-07-31T10:13:16+10:00</update_time>
  <message_ids>
    <id>6095320502740677</id>
    <id>6095320502740688</id>
  </message_ids>
</delivery_receipt>

Message Status Updates

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

Please find below the list of parameters that are sent.

FieldMeaning
outgoing_idOutgoing message identifier
command_statusCurrent status of the sms message
updated_timeThe date in UTC when the message status was updated
message_idsMessage part identifier

Examples

http://www.example.com/?outgoing_id=1267885033&command_status=255&update_time=2015-08-05%2015%3A50%3A45%20%2B1000&message_id=6095320502740677
outgoing_id=1267885033&command_status=255&update_time=2015-08-05%2015%3A50%3A45%20%2B1000&message_id=6095320502740677
{
  "outgoing_id": 1267885033,
  "command_status": 255,
  "updated_time": "2015-08-05 15:50:45 +1000",
  "message_id": "4338918912211198"
}
<?xml version="1.0" encoding="UTF-8"?>
<command_update>
  <outgoing_id>1267885033</outgoing_id>
  <command_status>255</command_status>
  <updated_time>2015-08-05 15:50:45 +1000</updated_time>
  <message_id>4338918912211198</message_id>
</command_update>

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.

FieldMeaning
toMobile Terminated Number, where the message was sent to
fromMobile Originated Number, where the message was sent from
msgContents of the message
dateDate the message was received by SMSGlobal.

Examples

http://www.example.com/?msg=I+received+your+message&to=61499057767&from=61433111222&date=2015-08-19T17%3A03%3A55%2B10%3A00
msg=I+received+your+message&to=61499057767&from=61433111222&date=2015-08-19T17%3A03%3A55%2B10%3A00
{
  "msg": "I received your message",
  "to": 61499057767,
  "from": "61433111222",
  "date": "2015-08-19T17:03:55+10:00"
}
<?xml version="1.0" ?>
<incoming>
  <from>61433111222</form>
  <to>61499057767</to>
  <date>2015-08-19T17:03:55+10:00</date>
  <msg>I received your message</msg>
</incoming>

Rest API V2
  • auto-topup

    • /v2/auto-topup

        • GET /v2/auto-topup beta since v2

          • Get the auto top-up information associated to the authenticated account.
        • PUT /v2/auto-topup beta since v2

          • Update the auto top-up information associated to the authenticated account.
  • contact group

    • /v2/contact/{id}

        • DELETE /v2/contact/{id} beta since v2

          • Delete a contact
        • GET /v2/contact/{id} beta since v2

          • Get the contact as identified by the given id.
        • PUT /v2/contact/{id} beta since v2

          • Update the contact as identified by the given id. You can only update the default fields associated with each contact.
    • /v2/group

        • GET /v2/group beta since v2

          • View list of groups
        • POST /v2/group beta since v2

          • Create a new contact group.
    • /v2/group/{groupId}/contact

        • POST /v2/group/{groupId}/contact beta since v2

          • Create a contact
    • /v2/group/{groupId}/contacts

        • GET /v2/group/{groupId}/contacts beta since v2

          • Get a list of all contacts in a group.
    • /v2/group/{id}

        • DELETE /v2/group/{id} beta since v2

          • Delete a contact group
        • GET /v2/group/{id} beta since v2

          • Get the contact group as identified by the given id.
        • PATCH /v2/group/{id} beta since v2

          • Update fields of a group as identified by the given id.
  • dedicated-number

    • /v2/dedicated-number

        • GET /v2/dedicated-number stable since v2

          • View list of dedicated numbers
  • opt-outs

    • /v2/opt-outs

        • GET /v2/opt-outs beta since v2

          • View list of opted out numbers
        • POST /v2/opt-outs beta since v2

          • Opt out mobile numbers, the invalid numbers will be skipped
    • /v2/opt-outs/validate

        • POST /v2/opt-outs/validate beta since v2

          • Validate opt out mobile numbers
    • /v2/opt-outs/{number}

        • DELETE /v2/opt-outs/{number} beta since v2

          • Opt in a mobile number
  • sharedpool

    • /v2/sharedpool

        • GET /v2/sharedpool beta since v2

          • View list of shared pools
    • /v2/sharedpool/{id}

        • GET /v2/sharedpool/{id} beta since v2

          • View details of a shared pool
  • sms

    • /v2/sms

        • GET /v2/sms beta since v2

          • View list of outgoing messages
        • POST /v2/sms stable since v2

          • Sent message
    • /v2/sms/{id}

        • DELETE /v2/sms/{id} beta since v2

          • Delete outgoing message
        • GET /v2/sms/{id} beta since v2

          • View details of a outgoing message
  • sms-incoming

    • /v2/sms-incoming

        • GET /v2/sms-incoming stable since v2

          • View list of incoming messages
    • /v2/sms-incoming/{id}

        • DELETE /v2/sms-incoming/{id} stable since v2

          • Delete incoming message
        • GET /v2/sms-incoming/{id} stable since v2

          • View details of a incoming message
  • user

    • /v2/user/billing-details

        • GET /v2/user/billing-details stable since v2

          • Get the authenticated account's billing details.
        • PUT /v2/user/billing-details stable since v2

          • Update the authenticated account's billing details.
    • /v2/user/contact-details

        • GET /v2/user/contact-details stable since v2

          • Get the authenticated account's contact details.
        • PUT /v2/user/contact-details stable since v2

          • Update the authenticated account's contact details.
    • /v2/user/credit-balance

        • GET /v2/user/credit-balance stable since v2

          • View the account balance
    • /v2/user/low-balance-alerts

        • GET /v2/user/low-balance-alerts stable since v2

          • Get the low balance alerts information associated to the authenticated account.
        • PUT /v2/user/low-balance-alerts stable since v2

          • Update the low balance alerts information associated to the authenticated account.
    • /v2/user/sub-account

        • POST /v2/user/sub-account stable since v2

          • Create sub account
    • /v2/user/verified-numbers

        • GET /v2/user/verified-numbers stable since v2

          • Get the authenticated account's verified numbers.