Payloads
The Web API uses standard JSON to communicate data between client and server. All requests and responses have an organised standard response format and while the input data may be form encoded, JSON, or multi-part data, the output will always be returned in JSON and will contain information on the payload as to whether the call was successful or not.
The response format is as follows:
{
"meta": {
"status": "success",
"message": "OK",
"code": 200,
// Conditional
"pagination":{
"records": 1337,
"page": 1,
"pages": 134,
"limit": 10
}
},
// Object or Array depending on request
"data": {...}
}
The 'meta' object is always returned containing header information about the request and response. The following table describes the full response payload parameters.
| Parameter | Type | Description |
|---|---|---|
| meta | Object | The meta object describes the result and record count (pagination) information if available. |
| meta[status] | String | Can only be success or error. Describes the result of the request. |
| meta[message] | String | A human readable message describing the status and the reason. |
| meta[code] | Integer | The code correlates with the HTTP status code and the descriptions are unchanged from the HTTP standards. If a validation or input error occurs an HTTP 422 - Unprocessible entity will be returned, below are the possible HTTP codes that may return: 200 - OK 201 - Created 401 - Unauthorized 403 - Forbidden 404 - Not Found 405 - Method Not Allowed 422 - Unprocessible Entity |
| meta[pagination] | Object | The pagination object is only returned on list requests where a large amount of data is expected. |
| meta[pagination][records] | Integer | The total number of records found, but not necessarily listed due to the pagination of the record list. |
| meta[pagination][page] | Integer | The current page number being viewed. Can be changed by appending the page query parameter to the request URL. |
| meta[pagination][pages] | Integer | The total number of pages calculated according to the specified limit and total record count. |
| meta[pagination][limit] | Integer | The limit of records that have been returned per page which constructs the number of total pages. Can be changed by appending the limit query paramter to the request URL. Maximum: 100, minimum: 1 |
| data | Object/Array | The data object returns the actual data of the request. This will be an object if a single object is returned or an array if a list of objects is returned. |
Important Note: A paginated list of objects will not contain a nested list of objects in each item in the list, but retrieving a single object will return the full payload. For example, the following dummy payload retrieved for a single ID will return the many_items array:
{
"id": 1337.
"name": "Sample Object",
"many_items": [
{
"id": 1,
"name": "Item 1"
},
{
"id": 2,
"name": "Item 2"
},
{
"id": 3,
"name": "Item 3"
}
]
}
However, calling a list of sample objects will not return the many_items array, child lists of a list are not supported:
[
{
"id": 1337.
"name": "Sample Object",
},
{
"id": 1338.
"name": "Sample Object",
},
{
"id": 1339.
"name": "Sample Object",
}
]
This is by REST design and is the consistent rule across all our API's. If you want to list all items of a particular object, refer to that object's API reference to retrieve a list and create your own mapping. Calling a GET request for each object's ID is highly discouraged and an excessive cluster of API hits on the same endpoint per IP address will result in throttling of requests, so it is highly encouraged that the standard REST implementation is established.
For every paginated payload, it is also possible to pass through the ids query parameter to get a paginated list of specific identifiers, for example, if you know exactly which ID's you want to query, you can simple append ?ids=id1,id2,id3 to the end of the request URL to list only objects within the provided identifier list, sample:
HTTP GET /v2/transactions?ids=7d4112fc-6da4-4c0b-aecc-c8aac05f543f,978112fc-6da4-4c0b-aecc-c8aac05f543f