Documentation
Log inSign up

Best Practices

Implement these best practices when integrating with SMSPortal's 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 you are required to pass your credentials as Basic Authentication or the Token you have generated.

_______________________________________________________________________________

Base URL

The base URL for the API is https://rest.smsportal.com 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 https://rest.smsportal.com/v1.

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 credentials, always make sure that you keep them secure. Exposing your credentials publicly can result in your account being compromised.

  • Do not embed API credentials directly in code:

Always be sure not to embed your API credentials within your code. This could result in them accidently being made public and can compromise the security of your account. This is particularly important for any code you intend to execute in the browser, such as a web app, as your credentials can be read by any user of your browser application.

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 Authentication vs Basic Authentication

We support both Token based (a secure internal format AEG) and Basic Authentication on all rest endpoints. Both mechanisms are secure, allowing customers to choose a mechanism best suited to their security requirements. Generated tokens are valid for 24 hours and should be cached in the client’s environment for 23 hours. Your API credentials are valid indefinitely after they have been generated and can only be deactivated by generating a new set of credentials through our client portal.

Token Generation and Caching

Because fetching new tokens is expensive, we recommend using a token cache to prevent unnecessary requests. By default, tokens are valid for 24 hours and are cached in our environment for 23 hours. This means that any new token request within 23 hours of your original request will result in the same token being returned. To allow for uninterrupted messaging in the last hour of a tokens lifetime a new token can be generated from the /authentication endpoint.

Updated 12 months ago

See also