REST API
This API is organized around REST and utilizes predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes authentication, and verbs.
It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses.
This makes it easy to communicate with from a wide variety of environments, from command-line utilities to gadgets to the browser URL bar itself.
The API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.
HTTP Methods
| Method | Description |
|---|---|
| GET | Retrieve a single resource or get an array of resources |
| PUT / PATCH | Update a single resource partially or fully |
| POST | Create a single resource |
| DELETE | Remove a single resource |
Request Format
This API accepts JSON payloads. You must supply a Content-Type: application/json header in PUT and POST requests, and you must set an Accept: application/json header on all requests.
The documented JSON properties for this API are case sensitive. For example, id and Id would not constitute the same property.
Response Format
When you create or update a resource successfully, the API will respond with the resulting resource in JSON.
This API responds to successful requests with HTTP status codes in the 200 or 300 range, and with HTTP status codes in the 400 range if an error occurred.
A list of objects are sent as an array of objects. All other operations return a single object.
Common HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Ok: The request was successful. |
| 400 | Bad request: Most likely a required parameter is missing or in the wrong format. |
| 401 | Unauthorized: Our API server has determined the user or the account doesn't have the required permissions to use the API or has access to that resource. |
| 404 | Not found: That resource was not found. |
| 405 | Method not allowed: The method that you were calling doesn't exist for that integration. |
| 429 | Rate-Limiting has been hit by the 3rd-party vendor's API. Wait 1 second and try again. Each vendor (and your customer's plan at that vendor) will have different rate-limits. |
| 500 | Crash: Help, our server crashed... Don't worry, we know and we will fix it. |