Skip to content

Welcome!

Welcome to our platform documentation! We'd love to hear what you think of our documentation, please let us know if anything requires further clarification.

Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14, [RFC2119], [RFC8174] when, and only when, they appear in all capitals, as shown here.

Attributes should be consistent across requests. This API does not support partial updates. That means that omitting an array of IDs for a relationship will clear that relationship on update.

In URL paths, parameters will be denoted with accolades (curly brackets) as such: {parameterName}. URL path parameters are always required. Query parameters (if any) will be detailed separately in the endpoint's documentation.

In request bodies, you will see common scalar types (string, int, bool), derivatives of these (e.g. url, which is a string) as well as DateTime and array<T>. Most of these are self-explanatory.

The virtual DateTime type may be provided in the form of a UNIX timestamp (as an integer), or in the following format: YYYY-MM-DD HH:mm, unless specified otherwise. Please take note that all timestamps will be interpreted as UTC unless specified otherwise.

T for arrays may be any other accepted type.

Note however that in some cases these values may in fact have to be sourced elsewhere. Some values may be required to be the ID of another resource available via this API, or even sourced externally via Google Places for example.

Responses and Status Codes

The response status codes can be used to quickly determine a request's result. All responses are in JSON format and will include both status and requestId at the root level object. The former will mirror the HTTP status code, while the latter may be used to help with debugging server side errors. Server error (5xx) responses will also include a error key with a textual description. Client error (400) responses will include a validationErrors object, which maps input values to their errors.

  • 200 Request completed successfully. For read requests, the body will contain the requested resources (if any); for write operations, changes will have been persisted and the body may contain the modified resource.
  • 201 Request completed successfully. Only applies to write requests for new resources.
  • 400 There was a problem with the request body. The response body will indicate what the problem was.
  • 401 The operation requires authentication and it wasn't provided.
  • 403 The operation requires authentication, but the provided authentication is not authorised to perform this operation.
  • 404 The requested resource or endpoint does not exist.
  • 429 This indicates that you've hit our rate limit (1000 req/min). Please take care to throttle any autocompleting UI elements you may, as these will eat into your quota rapidly.
  • 50x A problem occurred. Contact us with the requestId so that we can investigate.