Pagination
All API calls that return lists of resources (patients, appointments, invoices, reports, etc.) are paginated: the server never returns the entire dataset in one response, but a window of results you can scroll through request by request.
Response structure
Each list endpoint includes pagination fields in the response:
| Header | Value |
|---|---|
Authorization | Bearer {access_token} |
Accept | application/json |
totalCount
The total number of records matching the request filters, regardless of the current window.
Use it to compute the number of pages, show "1842 patients found" to the user, or decide whether to iterate further pages.
totalCount = 1842 → total pages with limit=50: ceil(1842/50) = 37offset
The starting position (zero-based) of the current window within the total list.
offset: 0→ reading from the first recordoffset: 50→ reading from the fifty-first recordoffset: 100→ reading from the hundred-and-first record
offset reflects the value you sent in the query string. If you did not send it, the default is 0.
limit
The maximum number of records returned in this response.
The actual value in the response may be less than the requested limit if you are on the last page and fewer records remain. limit reflects the value you sent (or the server default if not specified).
totalCount=1842, offset=1800, limit=50 → items contains 42 records (the last)hasMore
Boolean flag indicating whether more records exist after the current window.
| Value | Meaning |
|---|---|
true | More records exist — increment offset and make another request |
false | End of list reached — no further requests needed |
hasMore is the ideal exit condition for pagination loops: stop making requests when it becomes false, without manually computing arithmetic between totalCount and offset.
Query string parameters
You control the result window by passing offset and limit in the query string of each list request.
| Parameter | Type | Default | Description |
|---|---|---|---|
offset | integer ≥ 0 | 0 | Index of the first record to return |
limit | integer > 0 | depends on endpoint | Maximum number of records to return |
Example
The following illustrates sequential calls.
| Header | Value |
|---|---|
Authorization | Bearer {access_token} |
Accept | application/json |
Practical tips
Choose a limit suited to your use case.
For background sync you can use higher values (e.g. 200–500) to reduce the number of requests. For user interfaces, lower values (20–50) make navigation more responsive.
Do not skip pages based on totalCount alone.totalCount can change between requests if data is modified concurrently. Always use hasMore as the exit condition.
Combine pagination with filters.
The offset and limit parameters combine with any other filter supported by the endpoint (dates, status, etc.): totalCount always reflects the number of records matching the active filters.
Next steps
- Rate limiting — request limits per time window
- API reference — available endpoints and resource structure
- Swagger — interactive documentation with all parameters