List Responses

For APIs that respond with lists of objects, there are a few common concepts that are covered here; Filtering, Sorting and Pagination.

Filtering

Filtering of data will be contextual to that data, but we do follow a common set of standards to remain consistent across our APIs:

• Query params should be used for anything non-sensitive
• Header params should be used for anything sensitive
• Some forced filtering is performed to ensure security based on your API key - see our notes on Security for more detail.

In some cases where more flexibility is required, we may also use a single filter query parameter that allows for the passing of multiple query fields (using the : and ; separators), e.g.

GET /exp/v1/merchant-boarding/merchant-applications/1234/bank-accounts?filter=accountHolderName:bob;bankAccountCurrency:GBP

Sorting

All list operations have some ability to sort the data returned. By default, list data is usually returned sorted by the most relevant datetime field in descending order (newest first).

For custom sorting, the sort query parameter can be used with the following syntax:

<+ OR -><field1>,<+ OR -><field2>,...

For example:

GET /exp/v1/documents?sort=-created

would sort descending by the field created.

Refer to the specific API reference for details on what fields can be used to sort the results.

Pagination

Any requests which return a list of objects follow the same pattern in terms of the request parameters as well as response structure.

Request

When building the request, you can specify the following parameters to control the number and set and results:

• limit - the maximum number of objects to return from the query
• offset - the offset to begin searching from

For example, the following would return up to 20 results, skipping the first 40 that match:

GET /exp/v1/documents?limit=20&offset=40

This method can be used to 'page' through data. In this case the 'page size' is 20, and the 'page number' would effectively be 3 (since we're skipping over 40, or 2 pages of 20, results).

Response

List responses are made up of an array of all data items returned for a given 'page' of results as per the limit and offset above.

In order to help clients know how and when to paginate further, our APIs may include one or both of the following headers:

• Total-Count - the total number of records matching the given filters and ignoring pagination params, can be used to contstruct a full picture of how many 'pages' of results there would be
• Has-More-Records - whether or not there is another 'page' of results after the current one, if this is false, the client can be confident they can stop paginating further

See the specific API reference for more detail on which of those are used.