Pagination

The Simplifi API is in Developer Preview. While not all features are finalised, we encourage you to explore and share your feedback — including thoughts on endpoint design, response structure, or areas where documentation could be clearer.

Overview

Endpoints that return lists of records are paginated. Rather than returning every matching record in a single response, the API breaks results into pages and provides links to navigate between them.

Default Page Size

The default page size is 200 records. If you do not specify a pageSize, each response will contain up to 200 records.

Query Parameters

Control pagination using the following query string parameters:

Parameter	Type	Default	Description
page	Integer	1	The page number to retrieve. Starts at 1.
pageSize	Integer	200	The number of records to return per page.

Example Request

javascript

const response = await fetch('https://your-instance.simplifi.work/api/timesheets?page=2&pageSize=50', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Pagination Response Object

Paginated endpoints return a pagination object alongside the data array:

javascript

{
  "data": [ ... ],
  "pagination": {
    "page": 2,
    "pageSize": 50,
    "totalRecords": 340,
    "totalPages": 7,
    "nextPage": "https://your-instance.simplifi.work/api/timesheets?page=3&pageSize=50",
    "previousPage": "https://your-instance.simplifi.work/api/timesheets?page=1&pageSize=50"
  }
}

Field	Type	Description
page	Integer	The current page number.
pageSize	Integer	The number of records per page used for this response.
totalRecords	Integer	The total number of records matching your request.
totalPages	Integer	The total number of pages available.
nextPage	String	The full URL for the next page, or omitted if on last page.
previousPage	String	The full URL for the previous page, or omitted if on page 1.

Navigating Pages

The nextPage and previousPage fields contain ready-to-use URLs that preserve all your existing query parameters (such as date filters). The only change between them is the page value.

To retrieve all records, keep requesting the nextPage URL until it is no longer present in the response.

javascript

let url = 'https://your-instance.simplifi.work/api/timesheets';
let allRecords = [];

while (url) {
  const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
  const json = await response.json();

  allRecords = allRecords.concat(json.data);
  url = json.pagination.nextPage ?? null;
}

Notes

• Page numbers start at 1. Requesting page=0 is treated as page=1.
• If pageSize is not supplied or is 0, the default of 200 is used.
• Filters such as dateFrom and dateTo are applied before pagination, so totalRecords reflects your filtered result set.
• The nextPage and previousPage URLs are absolute and include your instance’s base URL.