Pagination

Most list endpoints return a PagedResponse<T> envelope and support cursor-free, page-number-based pagination.

Response Envelope

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalItemsCount": 1483,
  "items": [
    { ... },
    { ... }
  ]
}

Field	Type	Description
`pageNumber`	integer	The page returned (1-based)
`pageSize`	integer	Number of items on this page
`totalItemsCount`	integer, nullable	Total matching records across all pages. Some endpoints don't provide a total and return null here, don't assume it's always present
`items`	array	The records for this page

Query Parameters

Parameter	Default	Description
`page-number`	`1`	Which page to return (1-based)
`page-size`	varies	Items per page, check the specific endpoint for its default and maximum

Paging Through All Records

To retrieve all records, keep incrementing page-number until the items returned are fewer than page-size (or use totalItemsCount to compute the number of pages):

async function fetchAll(url, apiKey) {
  const allItems = [];
  let page = 1;

  while (true) {
    const res = await fetch(`${url}&page-number=${page}&page-size=200`, {
      headers: { Authorization: `ApiKey ${apiKey}` },
    });
    const { items, totalItemsCount, pageSize } = await res.json();

    allItems.push(...items);

    // totalItemsCount can be null for some endpoints, so also stop once a
    // page comes back short of a full page.
    if (items.length < pageSize) break;
    if (totalItemsCount != null && allItems.length >= totalItemsCount) break;
    page++;
  }

  return allItems;
}

Handling Empty Results

When no records match the filters, the API returns 200 OK with an empty items array, not 404:

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalItemsCount": 0,
  "items": []
}

Some endpoints (like GET /time-punches) return 404 when no records are found. Check the specific endpoint documentation.

Tips

Request only what you need. Use filters (date ranges, company-ids, employee-ids) to narrow results before paginating, this is faster and reduces load.
Don't rely on record order. The sort order of results is not guaranteed to be stable across pages; avoid using page-based pagination for change detection.
For incremental syncs, filter by date ranges rather than paging all records every time.