IM Gateway REST API

Response

Response

The full definition of the response is documented in this table below:

HTTP Status Codes

When responding, the REST API will make use of the appropriate and relevant HTTP status code to describe the nature of the result.

The response codes are mapped as follows:
HTTP Status Code Description
200 All OK.
400 Bad Request – The request is invalid and was not understood by the API.
401 Unauthorized – Header “Authorization” missing, invalid, or revoked; and / or, your host IP is not in the authorized IPs list.
403 The request contains invalid or illegal values.
404 Not Found – The endpoint on which the request was sent to, does not exist, or does not implement the API requested.
405 Method Not Allowed – If the endpoint received a request using an HTTP method (ex. GET instead of POST) that is not allowed by that endpoint.
413 Request entity was too large.
415 Unsupported Media Type – If the request was in a content-type not supported by the endpoint (e.g. text/plain instead of application/json).
429 Too many requests (Throttling).
500 Internal Server Error.

 

JSON Status Codes

The body of the response contains a JSON-structured reply detailing the outcome of your request.For non-HTTP 200 response codes, not all the fields described in Outer Response, RESULT Item, and RESULT_DETAIL Item may be present.

 

Outer Response

Key Type Optional Description
api_job_id String N A UUID identifying the life-cycle of this individual request / response, along with any future pending tasks relating to this request. Useful for error investigations and chaining.
client_job_id String Y If applicable, the job_id you supplied in the request is echoed here.
results Key-Value Y If applicable, this array contains results for each destination (see RESULT Object).
result_info RESULT_INFO N Contains a detailed description of the HTTP status code.

RESULT_INFO Object

Key Type Optional Description
status_code Int N Same as HTTP status code.
Description String N Detailed information about status indicated.

RESULT Object

Key Type Optional Description
{destination_msisdn} RESULT_DETAIL N Each RESULT object includes key (destination MSISDN) and value (its details), See RESULT_DETAIL Object for more info.

RESULT_DETAIL Object

Key Type Optional Description
message_id String N If the request was successful, a unique ID generated by the API for the message to this particular destination is returned here.
custom_id String Y If supplied, the custom_id supplied by the client from the request is echoed here.

Message Status Polling

You can poll our service to check the status of a particular message ID. This call follows the same pattern as the other requests as follows:

HTTP Method: GET
URI: 1/im/status/{message_id}
Headers: Authorization Header as per standard authorisation mechanism

The response is identical to the callback object. Refer to the callbacks section.

Get Started