Skip to main content

Pagination, Filtering, and Syncing Changes

How to page through list results, filter them, and keep your system in sync with NikoHealth efficiently.

Pagination

List endpoints (for example GET /v1/patients, GET /v1/orders, GET /v1/payers/dictionary) return results one page at a time.

Parameter

Description

pageIndex

The page number, starting at 0.

pageSize

The number of results per page. The default varies by endpoint; it's usually 10, and some endpoints use 20.

selectCount

Set to true to return the total number of matching records in Count. Defaults to false on most endpoints.

Response shape

{
"Count": 428,
"Items": [ ... ]
}

⚠️ Always set selectCount=true when you need Count. On some endpoints, Count is returned as 0 unless selectCount=true, even when there are results.

Example: page through all patients, 100 at a time

GET /v1/patients?pageIndex=0&pageSize=100&selectCount=true
GET /v1/patients?pageIndex=1&pageSize=100
GET /v1/patients?pageIndex=2&pageSize=100
...

Keep requesting the next pageIndex until a page returns fewer items than pageSize, or until you've retrieved Count records.

💡 Don't rely on the default page size. If you don't set pageSize, you may only get the first 10 results and assume that's everything.


Filtering

Most list endpoints accept filters as query parameters. Each endpoint's filters are listed in Swagger under Parameters.

Common filter patterns

Pattern

Example

Notes

Date and date-time ranges

created.from, created.to, modified.from, modified.to

ISO 8601, e.g. 2026-11-10T00:00:00Z

Multiple values

status=New&status=InProgress (orders)

Repeat the parameter for each value, on filters that accept a list

IDs

ids=10000105&ids=10000160

Repeat the parameter

Archived records

includeArchived=true

Archived records are excluded by default

Text search

fullName=Jane Doe, name=Cigna

URL-encode values

Nested filters

order.patientId=10000105, item.statuses=Shipped

Used by GET /v1/orders/items

Example: active patients created this month

GET /v1/patients?status=Active&created.from=2026-11-01T00:00:00Z&pageSize=100&selectCount=true

Syncing changes

To keep another system in sync with NikoHealth, combine webhooks for real-time updates with a scheduled catch-up that uses modified-date filters.

1. Real time: webhooks

Subscribe to events like patient.created, patient.updated, order.status.updated, and order.item.updated. NikoHealth notifies your endpoint as changes happen. See Webhooks API.

2. Catch-up: modified-date filters

Webhooks can be missed if your endpoint is down longer than the retry window. Run a scheduled job (e.g. hourly or nightly) that pulls anything changed since the last successful run.

These endpoints support modified.from / modified.to:

Endpoint

Filter

GET /v1/patients

modified.from / modified.to

GET /v1/orders

modified.from / modified.to

GET /v1/patients/{patientId}/orders

modified.from / modified.to

GET /v1/orders/items

order.modified.from / order.modified.to

GET /v1/tasks

modified.from / modified.to

GET /v1/payments

modified.from / modified.to

GET /v1/custom-fields

modified.from / modified.to

GET /v1/document-management

modifiedOn.from / modifiedOn.to

Notes endpoints use period.from / period.to instead:

GET /v1/patients/notes
GET /v1/orders/notes

Example: everything modified since the last sync

GET /v1/patients?modified.from=2026-11-10T06:00:00Z&pageIndex=0&pageSize=100&selectCount=true

Recommended sync pattern

  1. Store the time your last sync started (not finished).

  2. On the next run, request records with modified.from set to that stored time.

  3. Page through all results.

  4. Upsert each record by its ID, so a record that appears in both a webhook and the catch-up isn't duplicated.

  5. Save the new start time only after the run succeeds.

💡 Overlap the window slightly (for example, subtract a few minutes from the stored time) so records modified during the previous run aren't missed.


Be kind to the API

  • Use the largest page size that suits you instead of many small requests.

  • Request only what changed using modified-date filters instead of re-pulling everything.

  • If you receive 429 Too Many Requests, slow down and retry with an increasing delay.


Related articles

Did this answer your question?