iClinic Developers

Pagination

Every list in the iClinic Integration API returns one page at a time. Each endpoint uses one of two paging styles:

StyleEndpoints and when to stop
Cursorlimit, cursor /patients /appointments /receipts /therapy-plans
Stop when nextCursor is null.
Page numberpageSize, page /encounters
Stop when you have received all total encounters (visits), or when a page is empty.

Cursor: patients, appointments, receipts, therapy plans

  1. Make the first call with only limit (1–500, default 200).
  2. The response has nextCursor. If it is not null, there is a next page: call again with cursor= set to that value.
  3. Repeat until nextCursor is null.
  • Keep limit and updatedSince (if you use it) the same on every page.
  • Use nextCursor exactly as you received it. Do not construct or parse it yourself. A wrong cursor returns 400 INVALID_CURSOR.
  • Results are sorted by (updatedAt, id) in ascending order. Records added or changed between two calls do not shift the later pages: a record that has not changed is never skipped or repeated, and a record that has just changed appears once more, at its new position.

Page number: /encounters

Use page (starting at 0) and pageSize (1–500, default 200). Increase page until you have received all total encounters, or until a page is empty.

Results are sorted newest first. If new encounters are created while you are paging, the pages can shift, so deduplicate by encounterUuid when you merge the results.

No need to call often. One call every 5–15 minutes, with from set to one of the last few days, is enough to reconcile appointments.
Cursor: 5 patients, 2 per page

  1. First call, no cursor yet

    SendGET /patients?limit=2

    Receive2 records, nextCursor djF8cGF0…

  2. Paste the nextCursor you just received into cursor

    SendGET /patients?limit=2&cursor=djF8cGF0…

    Receive2 records, nextCursor djF8Z2h5…

  3. Repeat until nextCursor is null

    SendGET /patients?limit=2&cursor=djF8Z2h5…

    Receive1 record, nextCursor null no more pages, stop

The loop, in any language
# the first call has no cursor yet: leave this parameter out
cursor = null
loop:
    page = GET /patients?limit=500&cursor=CURSOR
    process each record in page.patients
    cursor = page.nextCursor
    if cursor is null: stop
Page number: 340 encounters, 200 per page

  1. First page: page=0

    SendGET /encounters?…&pageSize=200&page=0

    Receivetotal 340, 200 encounters

  2. Increase page to 1

    SendGET /encounters?…&pageSize=200&page=1

    Receivetotal 340, 140 encounters. 200 + 140 = 340 all received, stop

… stands for from and to, which stay the same on every page.