You must first request access to the API from your account manager. Once the API is turned on, you can find your API Key in the API Settings page under your Account’s API Settings. The API Key is required in every API call and is passed in the x-api-key custom HTTP header.
Once the API is turned on, you can also find the API URL in the API Settings page under your Account’s API Settings. Please note that future updates to our API service may change the API URL. We will provide advance notice of any URL change.
Calls to the API are made in the form of HTTP requests using the POST request method with UTF-8 encoded JSON data passed inside the request body. All the V2 API requests are expected to include a content-type HTTP header i.e., Content-Type: application/json; charset=utf-8
Postback notifications use the POST request method and the request body is a UTF-8 encoded JSON formatted according to the schemas described in this document. Postback notifications are issued as HTTP requests to the pre-configured postback URL you have provisioned to your account. Postback notifications are forwarded to your server one by one and require an HTTP STATUS 200 response as acknowledgement.
We expect your server to accept the postback HTTP request we send within 10 seconds by responding with a standard HTTP STATUS 200 header (success). If establishing a connection to your postback URL or your response takes longer than 10 seconds, the connection will time out and be dropped. If the connection times out or the HTTP code is not 200 we will retry the postback notification again approximately five minutes later for a maximum of 5 retries per notification. Postback notifications to your Postback URL are queued and will be sent over a single keep-alive connection as fast as you accept them. Consider storing the raw postback requests and performing any heavy database processing operations later asynchronously for better performance.
During your onboarding, we will provide you with the host IP addresses from where the postback notification request will originate. If you perform any IP whitelisting or have a firewall configured, these IP addresses must then be granted access to your server hosting the postback URL. Please note that we may update the postback IP address in the future. You will be notified in advance of any changes.
You may have a throughput limit set on your account in which case your Message sending API requests that exceed this throughput value will be queued and forwarded to carriers at a controlled rate. We will attempt to balance your queued messages based on the time it was requested as well as the velocity per originating number.
There may also be limits on the number of API requests allowed per second. These limits will be set on your Account API Settings and communicated to you through your account manager or can be viewed on your Account API Settings. API currently returns an ‘API exceeded’ error when your API requests exceed the throughput limit and instruct your system to retry. If you receive this error code you should throttle back your request speed or number of connections and retry any rejected API calls with this error code again.
Secure access to the API is provided by making the interface available via HTTPS. Authentication of API calls is done by using the accounts API key as well as IP whitelisting. In case an authentication error takes place, the following error codes are used to indicate the type of error. Authenticating your API call can be done by passing the account’s API key into the x-api-key header. Each API request must contain the API key passed into the header.
Authentication Error codes: E100, E103, E104, E105, E109.
Error JSON Example:
{ "status": "Failure", "error-code": "E100", "error-info": "Invalid request. Please make a valid JSON POST request with all the required variables." }
