Pagination

In our API, responses that return lists of objects are paginated. Pagination breaks down a large response into smaller responses called pages that the caller can step through to read all of the data.

Check paginates responses to ensure that response sizes are kept small and response times remain low.

Paginated Response

Endpoints that return a list of objects break down the response into multiple pages. Every page contains three fields: next, previous, and results. The previous and next fields contain URLs that point to the pages that come before and after the current one. The results field holds the payload of the page. These payloads are limited to a max size of 25 objects, also referred to as the page size. For example, a list of 100 employees will be broken down into 4 pages, each with a page size of 25.

{
  "next": string | null,
  "previous": string | null,
  "results": [batch of objects queried] 
}

Traversing Pages

Suppose a company has 30 workplaces, and we want to fetch all of them using the list workplaces endpoint. When making a GET request to the workplaces endpoint, the very first page of paginated results will be returned like so:

{
  "next": "https://api.checkhq.com/workplaces?cursor=bz0yNCZwPUFa",
  "previous": null,
  "results": [1st workplace, 2nd workplace, …25th workplace] 
}

The first page contains the first batch of 25 workplace objects. It also contains a URL pointing to the second page of results. You’ll notice that the previous field is set to null as this is the first page and no pages precede it.

To get the second batch of results, we simply perform a GET request on the URL contained in next. The response will look like this:

{
  "next": null,
  "previous": "https://api.checkhq.com/workplaces?cursor=af1b3GajnXza",
  "results": [26th workplace, 27th workplace, …30th workplace] 
}

The 5 remaining workplaces are returned here. This time the next field is null because there are no more pages of results left, and the previous field contains a URL that will return the page of 25 results before this.

Page Sizes

You can use the limit query parameter to control the number of objects returned per page. For most endpoints, excluding list forms and list employee forms , valid values of limit range from 1 to 25, defaulting to 25 if no value is provided.

For endpoints that return a list of objects, you can always expect them to be paginated. Even if the total number of objects queried is less than the page size, a single page will be returned with the next and previous fields set to null.