Pagination

Some endpoints support pagination, and to ensure stable, reliable, and efficient performance, we use ‘seek’ pagination. The main advantage of ‘seek’ pagination is that the items within a given page remain stable, even when new data is added, allowing for better performance optimization.

The after query parameter is used to retrieve all items that come after a specified item. In most cases, the id of an item is used for the after parameter, as shown in the example below. The documentation for each endpoint specifies which field should be used for the after parameter.

When polling our paginated endpoints periodically, use the last retrieved value for the next request. Since the after parameter is interpreted in a strict “greater than” (>) sense, an empty page might be returned, indicating there are no new items.

For consecutive pages, the link_next field in the response contains the relative URI to fetch the next set of results. Additionally, the Link: header provides the same relative URI for the next page.

Example of a current page result:

{
    "items": [...],
    "page_size": 500,
    "link_next": "/main/v1/msp-chargesession?after=NLTD1_608C9A13-E3DC-4353-8BEE-7437305BC8D7"
}

To retrieve the next page, use the provided link_next value for your next request: GET https://example-api.on-tandemdrive.com/main/v1/msp-chargesession?after=NLTD1_608C9A13-E3DC-4353-8BEE-7437305BC8D7

Be aware that providing an invalid after value, such as a non-existent identifier, will also result in a 400 Bad Request error.

Initial request

If you want to retrieve all items from the start, you can omit the after parameter in your initial request. In most cases that’s the best approach.

For large datasets where you only need records created after a specific point in time, you can use the created_gt query parameter (available on select endpoints) to establish a starting position.

When using created_gt, please be aware of the following behaviors and constraints:

• Initial use only: Use created_gt strictly to establish your starting position. All subsequent pagination and polling must be handled using the after parameter by tracking the id of the last received item.

• Empty initial response: Your first request will not return any data items. Instead, it generates a link_next URL pointing to the first page of relevant results.

• First item excluded: Because the generated link_next relies on standard after logic, it strictly fetches data after the exact timestamp excluding the very first matching item.

• Mutual exclusivity: created_gt cannot be combined with any other parameters in the initial request (including after). To apply additional filters, append them directly to the link_next URL in your subsequent requests.

Page size

To control the number of results returned per request, use the optional page_size parameter. While the default is typically 500, check the specific endpoint documentation for exact minimum, maximum, and default values. This default tries to strike a balance between reducing the number of required requests and keeping the response size within limits.

Note: The API could adjust your requested page size. The actual page size applied to your request will always be returned in the response body.

Pagination how-to

Below you’ll find a basic pagination example. The example uses the GET /customer endpoint, but the techniques apply to all endpoints that use pagination.

To start pagination through a set of results provided by a particular endpoint, use the endpoint URL without the after parameter:

$ curl -u $public_id:$secret "$base_url/main/v1/customer"

This results in a page of customer data, for example:

{
  "items": [
    {
      "id": "cd1ddcf5-9858-4f90-b132-094e505c0725",
      "admin_id": "graant",
      "name": "Mr. Grain",
      "country": "NL",
      "entity_type": "person",
      "external_reference": "R00001"
    },
    ...
    {
      "id": "8bb33876-d098-429e-b9ed-77f81ce6db00",
      "admin_id": "silaye",
      "name": "Gardening Enterprise",
      "country": "GB",
      "entity_type": "organisation",
      "company_reg_num": "6984621"
    }
  ],
  "page_size": 500,
  "link_next": "/main/v1/customer?after=8bb33876-d098-429e-b9ed-77f81ce6db00"
}

Retrieve the next page using the link_next value if more data is available. If no link_next is provided then you’ve reached the last page.

It is important to store the id of the last item so that data retrieval can later be continued. To later poll for more data use the after parameter with the id of the last item:

$ curl -u $public_id:$secret "$base_url/main/v1/customer?after=8bb33876-d098-429e-b9ed-77f81ce6db00"