Welcome to our API documentation

From here you can browse the full documentation for our HTTP API. Our API is split into sections which you can browse using the menu on the right. If you have any questions, you can contact our team and we'll be happy to help out.

Before you get started, take a few minutes to review the information below about how to interact with our API. It includes information about how to send requests, what response data is sent in and how to handle errors.

Making requests

Our API works over the HTTP protocol with JSON. It is implemented in an RPC-like manner and everything you can do with the API has its own action.

All HTTP requests must be made over HTTPS to the URL shown on the action's page in this documentation. All responses you receive from the API will be returned in JSON. Requests should be made using the POST method with any parameters encoded as JSON in the body of the request.

Receiving responses

All responses will be returned to you encoded as JSON. You will always receive a hash as the response which will look like the JSON below:

{
  "status":"success",
  "time":0.123,
  "flags":{
    ... additional information about the request ...
  },
  "data":{
    ... the data returned from the action ...
  }
}

The status attribute will give you can indication about whether the request was performed successfully or whether an error occurred. Values which may be returned are shown below:

• success - this means that the request completed successfully and returned the data that was expected.
• parameter-error - the parameters provided for the action are not valid and should be revised.
• error - an error occurred that didn't fit into the above categories. This will be accompanied with an error code, a descriptive message and further attributes which may be useful. The actual potential errors for each action are shown in the documentation.

The time attribute shows how long the request took to complete on the server side.

The flags attribute contains a hash of additional attributes which are relevant to your request. For example, if you receive an array of data it may be paginated and this pagination data will be returned in this hash.

The data attribute contains the result of your request. Depending on the status, this will either contain the data requested or details of any error which has occurred.

A note about HTTP status code

The API does not generally use HTTP status codes to return information about the outcome of a request. There are two supported statuses with the API:

• 200 OK - This is the code you'll usually receive. It indicates that the response was successfully delivered and returned to our service (although does not nessesary mean that the action you were expecting was successful). Further status information will be provided in the status attribute on your response body.
• 301 Moved Permanently or 308 Permanent Redirect - This means that the API request should be sent to an alternative URL. This may just mean you need to send your request using https rather than http as the protocol.
• 500 Internal Server Error - This will be returned when an error occurred within the API itself. This was not anticipated by us and should be reported to us.
• 503 Service Unavailable - This will be returned if API is currently unavailable for maintenance or other issue.