Skip to main content

API basics

Our Partner API is a RESTful API that uses JSON for representation. All requests must be authenticated using an access token.

Interface contract​

Our OpenAPI documentation shows the input and output payloads for each route.

To fill correctly the input payload, please pay close attention to each attribute definition (whether the field is required or not) to make sure your input payload matches the expected format.
Otherwise, you will receive a 400 (Bad Request) response from the server and your payload will not be taken into account.

Status codes​

We use conventional HTTP response codes to indicate the success or failure of an API request.

In general:

  • 2xx status codes indicate a successful payload
  • 4xx status codes indicate an error in the payload that failed, given the information provided (e.g. an invalid authentication token or missing a required field)
  • 5xx status codes indicate an error with our servers

Error format​

Errors returned by the API are normalized in order for you to easily understand the error made. Here is an example of the basic error format:

{
  "error": {
    "code": 401,
    "message": "Invalid token",
    "reasons": ["Token expired"],
    "type": "authentication/token-expired"
  }
}

As you can see, our error messages always come with a unique technical error code (see type In our example above, the type informs us that the token used has expired.


We will always try to provide you with an error message a human can understand to ease development.


To have a look of all our error messages, click here.