Pagination

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

Response Envelope

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

Field	Type	Description
`pageNumber`	integer	The page returned (1-based)
`pageSize`	integer	Number of items on this page
`totalItems`	integer	Total matching records across all pages
`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 totalItems 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, totalItems, pageSize } = await res.json();

    allItems.push(...items);

    if (allItems.length >= totalItems) 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,
  "totalItems": 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.