Skip to main content

API Conventions

Our APIs all follow a core set of conventions. These conventions cover things like pagination, HTTP PUT bodies for updates, and response errors, and common status codes.

Pagination on Query Endpoints​

For query endpoints that list resources we support the use of a handful of querystring parameters which influence things like the results limit and number of results to skip. We also support sort ordering.

  • $skip - Sets the number of results to skip.
  • $limit - Set the number of results to respond with. This is capped at 100 for most endpoints.
  • $sort - Indicates the sort order. Should be written as a path: $sort[fieldName]=asc. You can sort on multiple fields, and the order in the querystring will determine the order in which they are applied: $sort[fieldName1]=asc&$sort[fieldName2]=desc. The value of sort can be either asc or desc.

Response Property Case​

Often programming languages have standards for casing. In order to ease the programming experence when using our API we allow you to change the casing of responses from our system by setting the $propertyCase query string parameter on any request that responds with a body.

  • $propertyCase - Can be set to camelCase, snake_case, or kebab-case. camelCase is the default value.

Common Status Codes​

Our API follows common status code conventions. There are a few status codes you should know as these are used accross our API.

  • 201 - Returned by POST endpoints when a resource was successfully created.
  • 200 - Returned by GET endpoints when a resource was found and is included in the body of the response.
  • 204 = Returned by PUT endpoints when a resource has been modified.
  • 304 - Returned by PUT endpoints when a resource has not been modifed because the requested change has already been applied.
  • 202 - Returned by POST and PUT endpoints that are asyncronous and a success or failure status cannot be given. The result of these endpoints is usually indicated in a webhook event.
  • 401 - Returned by all endpoints that require authentication when either an invalid auth token is used with the request, or a required permission is not assigned to the token or user issuing the request.
  • 403 - Returned by some endpoints when a feature has not been enabled on an account or organization, or the action being performed is not allowed due to configuration.
  • 404 - Returned when an endpoint does not exist, or the path includes an account or organization id the token or user does not have access to.