Best Practices

Implement these best practices when integrating with our REST API.

Request Structure

All requests to the API consist of the following:

  • Endpoint: The URL that indicates the resource being accessed.
  • Version: The version of the resource being accessed, defaulting to the latest version if not specified.
  • Parameters: Any required/optional parameters for the resource.
  • Body: Any JSON body that is required by the resource (POST only).
  • Authorisation Parameters: In every request made to the REST API (except when generating a token) you will be required to pass your token.

Base URL

The base URL for the API is and supports HTTPS. To access a specific version of the API, simply postfix the URL with the version of the API, as in the case of

The base URL will always be set to use the latest version of the API. However, in order to reduce the chance of compatibility issues, always reference the version you are developing against in the URL.

API Credential Security

When using API keys, always make sure that you keep them secure. Exposing your credentials publicly can result in your account being compromised.

  • Do not embed API keys directly in code:

Always be sure not to embed your API keys within your code. This could result in them accidently being made public and can compromise the security of your account.

Parameter Formatting

  • Date and Time: All date and time parameters are treated as UTC time and should be in the ISO 8601 format. See ISO 8601 for more information.

  • URL Encoding: Parameters must be URL encoded. For ease of reading, however, URL parameters have been left unencoded for the purposes of this document.

  • Number Format: When sending SMSes internationally the REST API requires phone numbers in E.164 format.

Token Generation

Tokens should only be regenerated just before the maximum validity period of 24 hours is about to be reached. Regenerating a new token any sooner is unnecessary and creates additional overhead on the system.