External API Overview

Prerequisites

To use the Xtremepush API you must have an authorisation token. The two options for this are to use the general App Token that can be found within a Project in Settings > Integrations > API Integration, within the App Token field. Alternatively, you can create a token using the OAuth2.0 standard, as described in our dedicated guide.

🚧

Token security

The API token is unique to a project. It is generated as a random string when the project is created, with uniqueness checks performed against the Xtremepush environment.
The token is only available to users with an admin role for the project.
Care should be taken when sharing the token, as it grants full API access to the project.
A single token is available for the project and can only be rotated manually through coordination with our support team.

Creating requests

The external API methods are used by sending HTTP POST requests with JSON body to an API Endpoint.

https://external-api.xtremepush.com/api/external/{method name}/{model name}

Xtremepush manages a number of different instances located in different world regions. Each project on the platform is located in a single region, which is selected when creating a project. You should use the corresponding API endpoint for each project:

The method and model names are shown in detail in the API Reference along with the available parameters. Examples are provided for cURL for easy testing, and the documentation allows live testing by supplying your own values for parameters.

Processing responses

After making a request to the API, the response is returned as a JSON formatted object with an appropriate HTTP status code. Specific examples are given in the API Reference for each method, but they all follow a basic structure:

{
  "code"      : integer http error/success code
  "success"   : boolean - whether client request is successful
  "message"   : string - system error message if code is error (4xx-5xx) for use in logging so can be reviewed in the event of errors 
  "errors"    : errors list if success is false (optional)
  "data"      : contains array of response data (optional)
  "model"     : contains created / updated object attributes (optional)
}

Success

A successful response may contain a message and the associated model when creating or updating, or for a list method may contain a data property with an array of objects.

{
  "code": 200,
  "success": true,
  "message": "Campaign successfully created",
  "model": {
    "id": CAMPAIGN_ID,
    "text": "Testing Campaign is sent to subscribers to 15_01_04",
    "title": "Flag Test Campaign",
    ....
  }
}

Error

An API implementation should handle error responses, indicated by standard HTTP 4xx-5xx status codes.

4xx errors indicate an issue in the request such using an invalid URI or having incorrect API parameters. Where possible additional information will be provided to help you debug on the client side.

{
  "code": 400,
  "success": false,
  "message": "Campaign is not created",
  "errors": {
    "text": ["Text cannot be blank."]
  }
}

Handling error responses

General guideline for handling error responses:

• 4xx – Client issue. Log error so alert goes to IT team.
• 5xx – Network connectivity or Xtremepush issue. Retry up to retry limit, then log error with alert to IT team who can escalate with Xtremepush support if needed.

A possibly retry strategy (depending on your use case) is to send one retry immediately and then, if that still returns the same code, try once more after 30 seconds. The request, response and timestamp for anything other than a 2XX response code should be recorded so it can be looked into later.