Pagination

All list endpoints return paginated results. You control pagination using query parameters, and the response includes metadata to help you navigate through pages.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`pageSize`	integer	`100`	Number of items per page. Max 500 on `/patients`, `/insurance-policies` and `/appointments`; max 100 everywhere else, because those endpoints do per-row work that page size multiplies.
`cursorId`	string	—	On delta feeds only, the id of the last row you consumed. See Delta sync.

Example

# Get page 2
curl -X GET "https://api.maxcare.ai/v3/patients?page=2" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"

Response Format

Every paginated response includes a pagination object alongside the data:

{
  "code": "success",
  "data": {
    "patients": [
      {
        "id": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
        "mrn": "MM0000000005",
        "firstName": "Max",
        "lastName": "Test",
        "gender": "Male",
        "dateOfBirth": "1989-09-06"
      },
      {
        "id": "pat_8de030393a9e417ab2b3a8b8df183631",
        "mrn": null,
        "firstName": "EZDerm Other",
        "lastName": "Test",
        "gender": null,
        "dateOfBirth": null
      }
    ],
    "pagination": {
      "page": 2,
      "pageSize": 100,
      "totalCount": 1503,
      "totalPages": 16
    }
  }
}

Pagination Fields

Field	Type	Description
`page`	number	Current page number
`pageSize`	number	Number of items per page
`totalCount`	number \| null	Total number of items across all pages. `null` only on `/bills` when you pass `includeTotals=false`.
`totalPages`	number \| null	Total number of pages. `null` under the same condition.

Iterating Through All Pages

To fetch all records, loop until page equals totalPages:

async function fetchAllPatients(apiKey, orgId) {
  const patients = [];
  let page = 1;
  let totalPages = 1;

  while (page <= totalPages) {
    const response = await fetch(
      `https://api.maxcare.ai/v3/patients?page=${page}&pageSize=100`,
      {
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "X-Organization-Id": orgId,
        },
      }
    );
    const json = await response.json();

    patients.push(...json.data.patients);
    totalPages = json.data.pagination.totalPages;
    page++;
  }

  return patients;
}

import requests

def fetch_all_patients(api_key: str, org_id: str) -> list:
    patients = []
    page = 1
    total_pages = 1

    while page <= total_pages:
        response = requests.get(
            "https://api.maxcare.ai/v3/patients",
            params={"page": page, "pageSize": 100},
            headers={
                "Authorization": f"Bearer {api_key}",
                "X-Organization-Id": org_id,
            },
        )
        data = response.json()

        patients.extend(data["data"]["patients"])
        total_pages = data["data"]["pagination"]["totalPages"]
        page += 1

    return patients

Tips

Use the largest pageSize that makes sense for your use case to minimize the number of requests — up to 500 on /patients, /insurance-policies and /appointments, up to 100 elsewhere.
On /bills, pass includeTotals=false if you do not need totalCount. The totals cost a second aggregate over the whole filtered set, recomputed on every page of a walk, and they are the dominant cost of that endpoint. Leave them on if you use the count to decide a walk was complete.
The first page is page=1, not page=0.
An empty page returns an empty array with totalCount: 0.
Some list endpoints support search filters (e.g., ?search=smith on /v3/patients). Pagination applies after filtering.

Delta sync and `cursorId`

/bills, /patients, /insurance-policies and /appointments accept updatedSince (and updatedUntil) to return only records that changed. Always send a full instant with an explicit UTC offset — 2026-08-01T00:00:00Z, not 2026-08-01. On /patients, /insurance-policies and /appointments a zone-less value is rejected with a 400. /bills predates that rule and still accepts one, but it is resolved against the database’s timezone rather than as UTC, so the same string can mean a different instant there than on the other three. Send the offset everywhere and the difference never arises. cursorId is available on /patients, /insurance-policies and /appointments. /bills does not have it yet: unknown query parameters are ignored rather than rejected, so sending cursorId there is silently dropped and you get the offset walk described below. Until it does, walk /bills with updatedUntil pinned to the instant your walk started, keep includeTotals on, and treat a totalCount that shrinks between pages as a walk you must not trust — re-read the window instead of advancing your cursor. Do not walk a delta feed with page/offset. The rows are ordered by the same change stamp the sync workers rewrite, so a record on an earlier page that changes mid-walk moves to the end of the results. Everything after it shifts one position toward the front, and the offset for your next page steps over whichever record moved into that slot. That record is never returned, and its stamp is below the cursor your walk ends on, so you never see it again — while the walk itself looks like it completed cleanly. Use cursorId instead, always requesting page 1:

async function fetchChangedPatients(apiKey, orgId, since) {
  const out = [];
  let cursor = { updatedSince: since, cursorId: undefined };

  for (;;) {
    const qs = new URLSearchParams({ pageSize: "500", updatedSince: cursor.updatedSince });
    if (cursor.cursorId) qs.set("cursorId", cursor.cursorId);

    const res = await fetch(`https://api.maxcare.ai/v4/patients?${qs}`, {
      headers: { Authorization: `Bearer ${apiKey}`, "X-Organization-Id": orgId },
    });
    const { data } = await res.json();
    if (data.patients.length === 0) break;

    out.push(...data.patients);
    const last = data.patients[data.patients.length - 1];
    cursor = { updatedSince: last.updatedAt, cursorId: last.id };
  }
  return out;
}

On a cursorId page, pagination.totalCount counts the window that starts at your cursor, so it shrinks as you walk — 250, then 150, then 50. That is expected. Stop on a short page rather than on the count, and do not read the shrink as a signal that the walk is untrustworthy (that signal belongs to the offset-paged /bills walk described above, where a shrinking total means a row left the window and may have been skipped). Two limits to design around:

A change feed cannot report a deletion. If you prune local records the source no longer has, you still need a periodic full walk; the delta only replaces the reading.
Each feed tracks its own row. /appointments compares lastSyncedAt, which moves only when an appointment’s own columns change — renaming a patient changes patientLastName in the appointment response without the appointment appearing in the feed. Likewise /insurance-policies does not move when payer or plan names change, and /patients does not move for include=contact or include=identity data. Mirror those from their own endpoints.

Overview

Core Concepts

Working with Appointments

Working with Patients

Building Apps

Query Parameters

Example

Response Format

Iterating Through All Pages

Tips

Delta sync and `cursorId`

​Query Parameters

​Example

​Response Format

​Pagination Fields

​Iterating Through All Pages

​Tips

​Delta sync and cursorId

Query Parameters

Example

Response Format

Pagination Fields

Iterating Through All Pages

Tips

Delta sync and `cursorId`