Patient history & readiness

POST /v4/patients/history reads the appointment and bill history of up to 25 charts at once. It exists for apps that decide something from a patient’s whole history — a recall campaign, a gap-in-care check — where a missed row is a wrong decision, and where waiting for a clinic-wide import to finish is not an option. Scopes: read:patients, plus read:appointments and/or read:bills for the resources you ask for. The recipe for one linked group (one person’s EZDerm and ModMed charts):

POST /v4/patients/history/refresh with the group’s EZDerm charts (optional, see Per-patient refresh).
POST /v4/patients/history with every chart in the group and the coverage window you care about.
Act only when groups[].appointments.status is complete. Otherwise look at each chart’s readiness to see what is missing.
Stay current from GET /v4/changes: a new booking on either chart arrives as appointment.changed; re-read that group.

Request

POST /v4/patients/history
{
  "patientIds": ["pat_c56103bcd39c46d39f3138dd2b5e05f6", "pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a"],
  "resources": ["appointments", "bills"],
  "coverage": { "from": "2024-10-01", "to": "2026-10-06" },
  "limit": 100,
  "cursors": []
}

Field	Rules
`patientIds`	1–25 unique chart ids (`pat_…` or UUID).
`resources`	`appointments`, `bills`, or both (default).
`coverage`	Facility-local days appointment `readiness` is judged over. Default: the last two years through today (UTC). At most 3,660 days.
`limit`	Rows per chart per resource, 1–200, default 100. Lowered so one response holds at most 2,500 rows; the applied value is `limitPerResource`.
`cursors`	`nextCursor` values from earlier responses. Each names its own chart and resource.

Unknown fields are a 400, not ignored. A cursor issued to another organization, malformed, repeated, or naming a chart or resource not in this request is a 400.

Response

{
  "code": "success",
  "data": {
    "snapshotAt": "2026-10-06T04:30:00.000Z",
    "limitPerResource": 100,
    "patients": [
      {
        "patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
        "found": true,
        "chart": {
          "id": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
          "instanceId": "ins_0b6f2a1c9d8e4f7a8b6c5d4e3f2a1b0c",
          "ehrType": "modmed",
          "ehrPatientId": "112233",
          "mrn": "MM-100",
          "updatedAt": "2026-10-01T14:03:11.412Z",
          "masterPatientId": "mpt_4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a",
          "duplicatePatientIds": ["pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a"],
          "identityLinks": [{ "patientId": "pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a", "basis": "name_dob" }],
          "identityReview": { "status": "linked", "candidates": [] }
        },
        "appointments": {
          "status": "ok",
          "version": "9b2f…",
          "totalCount": 3,
          "hasMore": false,
          "nextCursor": null,
          "readiness": {
            "status": "complete",
            "basis": "window",
            "requestedFrom": "2024-10-01",
            "requestedTo": "2026-10-06",
            "asOf": "2026-09-30T02:10:00.000Z",
            "liveAsOf": "2026-10-06T04:25:00.000Z",
            "excludes": [],
            "scopes": [
              { "scope": "fac_…", "status": "complete", "verifiedDays": 736, "totalDays": 736,
                "firstUnverifiedDay": null, "lastUnverifiedDay": null,
                "asOf": "2026-09-30T02:10:00.000Z", "liveAsOf": "2026-10-06T04:25:00.000Z",
                "lastFailureAt": null, "lastFailureReason": null }
            ],
            "patientRefresh": null
          },
          "items": [
            { "id": "apt_…", "ehrAppointmentId": "778899", "status": "scheduled", "integrationStatus": "PENDING",
              "scheduledStartDate": "2026-10-20T13:00:00.000Z", "scheduledEndDate": "2026-10-20T13:15:00.000Z",
              "facilityId": "fac_…", "ehrFacilityId": "2706", "providerId": "prv_…", "appointmentTypeName": "Follow up",
              "isNewPatient": false, "isCosmetic": false,
              "createdAt": "2026-10-05T18:00:00.000Z", "lastSyncedAt": "2026-10-05T18:00:00.000Z",
              "removedFromEhrAt": null }
          ]
        },
        "bills": {
          "status": "ok", "version": "41ac…", "totalCount": 12, "hasMore": false, "nextCursor": null,
          "readiness": { "status": "unverified", "pendingHydration": 0 },
          "items": [ "…" ]
        }
      },
      { "patientId": "pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a", "found": true, "chart": { "…": "…" } }
    ],
    "groups": [
      {
        "masterPatientId": "mpt_4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a",
        "memberIds": ["pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a", "pat_c56103bcd39c46d39f3138dd2b5e05f6"],
        "missingMemberIds": [],
        "appointments": { "status": "complete" },
        "bills": { "status": "unverified" }
      }
    ]
  }
}

A chart outside your organization and a chart that does not exist both answer { "patientId": …, "found": false } and nothing else. Linked charts are returned separately, each with its own EHR, MRN, facility ids and contacts; nothing is merged. To find a group’s latest qualifying appointment, take the latest across every member chart’s items, skipping rows with removedFromEhrAt.

Consistency: snapshot, version, cursor

One snapshot per response. Every chart and resource in a response is read in one REPEATABLE READ transaction at snapshotAt.
Paging is per (chart, resource). Rows are ordered by id, which never changes. A large chart returns hasMore: true and a nextCursor while the others in the batch finish; send only the cursors you still need.
version is a content hash of every row in that chart’s resource at the snapshot (bills: bills plus coding groups, line items and diagnoses). Any insert, update or delete changes it, including writes that move no timestamp.
A cursor only continues the set it was cut from. If the version changed, the resource returns status: "snapshot_changed" with no items: restart that (chart, resource) without a cursor. A walk either reads one unchanged set end to end or is told to restart; it never skips or repeats a row silently. The hash covers sync bookkeeping too, so a chart being re-synced while you page can restart more than once. Most charts fit one page and never need a cursor.

Readiness

items: [] means “the mirror has no rows”. readiness says whether that can be trusted. Paging to the end proves nothing about the EHR; only readiness does.

Appointments

Readiness rests on one of two kinds of evidence (basis): window — facility-day sweeps. The appointment sync reads one facility-local week per call (ModMed per facility, EZDerm per practice) and records each day of the week only after every page of that week was read and written (an appointment the EHR returns without a patient is not mirrored, so it cannot be part of any chart’s history). A week the EHR did not answer records a failure on its days instead. The rolling sync reads one week back through the booking horizon every five minutes; history older than that is read by the historical backfill (see Rollout).

`status`	Meaning for the requested `coverage` window
`complete`	Every scope (facility or practice) of the chart’s EHR instance has a verified sweep for every day, and, if the window reaches into the last week, those days were verified within the hour. An empty list means no appointment in the window.
`stale`	Every day is verified, but the last week’s newest verification is over an hour old (the rolling sync has not been succeeding).
`partial`	Some days are unverified — e.g. the historical backfill has not reached them. `scopes[].firstUnverifiedDay`/`lastUnverifiedDay` say which.
`failed`	An unverified day’s latest sweep failed (`lastFailureReason`).
`in_progress`	No complete evidence yet, but a per-patient refresh is queued.
`not_imported`	Nothing verified for the window. An empty list proves nothing.

patient — per-patient refresh. A refresh that read the chart’s whole history in one patient-scoped EHR call makes that chart complete on its own for a day (stale after), whatever the facility sweeps say — so one linked group can become ready while the rest of the clinic is still importing. patientRefresh shows that evidence even when basis is window. asOf is the EHR state the evidence reflects: an EHR change after it is not covered. excludes lists appointment kinds the sync never imports for this EHR (virtual_encounters on EZDerm).

Bills

The bill sync keeps no completeness evidence, so the platform never calls a bill history complete:

`status`	Meaning
`in_progress`	`pendingHydration` of this chart’s bills are discovered but not yet read in full.
`unverified`	Every bill the mirror knows about is read in full; whether the EHR has bills not yet discovered is unknown.

Groups

groups[] has one entry per linked identity among the requested charts. Its status is the least ready member’s, or missing_members while a chart linked to the identity in your organization was not in patientIds — a group’s history is not whole until every member chart is read.

What the evidence does not guarantee

A day that left the rolling sync’s one-week lookback is not re-read; an EHR change to an appointment more than a week after its date is not reflected until a backfill or per-patient refresh re-reads it.
Only facilities linked to a live connector are swept. A ModMed facility no connector is linked to is outside scopes; a facility whose only connector is disconnected reads as not covered.
EZDerm sweeps and refreshes request non-virtual encounters only (excludes).
EZDerm’s encounter search is unpaginated with an undocumented cap. A week of 400+ results is re-read day by day; a day of 400+, or a patient with 400+, is written but never verified (possible-truncation).
A sweep that crashes records nothing for the weeks it did not finish; their verification stops advancing and asOf/liveAsOf show it.

Appointments the EHR no longer has

When a fully read week (or a patient refresh) no longer returns a mirrored appointment, the row is kept with removedFromEhrAt set, and an appointment.removed change is published. A later read that returns it again clears the field. A rescheduled appointment can read as removed until the week it moved to is read. Do not count removed rows as visits or bookings.

Per-patient refresh

POST /v4/patients/history/refresh
{ "patientIds": ["pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a", "pat_c56103bcd39c46d39f3138dd2b5e05f6"] }

202
{ "code": "success", "data": { "patients": [
  { "patientId": "pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a", "status": "queued" },
  { "patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6", "status": "unsupported",
    "reason": "No verified patient-scoped appointment history call for this EHR; readiness comes from facility sweeps." }
] } }

Scope read:appointments. Up to 25 charts. already_queued while a refresh for the chart is pending (a pending refresh older than ten minutes may be queued again). Foreign charts answer not_found.
EZDerm only. The refresh uses EZDerm’s patient-scoped encounter search, the call the platform already uses for a patient’s upcoming appointments. ModMed has no patient-scoped appointment call verified against live traffic, so ModMed charts are always unsupported and rely on facility sweeps plus the historical backfill.
Whose login reads. The body may carry sessionToken, the App Bridge session token of the logged-in user making the request. The refresh picks which EHR login reads the chart, in order: your organization’s office (system) EZDerm connection on the patient’s practice; if it has none live, the personal EZDerm connection of the logged-in user who made the request, when you send their App Bridge sessionToken (verified; a token that does not verify for your app and organization is a 401 for the whole request, and nothing is queued); otherwise none. Another staff member’s personal connection, and the practice’s autosubmission connection, are never used. With none, the chart is still queued here and its refresh then fails with no-live-connector. A read through a personal connection writes what that login can see but never marks appointments removed and never makes the chart complete: readiness reports failed with lastFailureReason read-through-personal-login. That is final for that login; retrying reads the same partial view again.
A chart whose refresh is still pending answers already_queued, whoever queued it; that run reads with the login it was queued with. Once it has run, a request with your sessionToken queues a new read.
An empty answer for a chart the mirror holds appointments for is treated as a failure (empty-result-contradicts-mirror), never as a wiped history.
The refresh writes every returned appointment, marks the chart’s mirrored appointments the EHR no longer returns, then records the evidence. If it crashes before the last step the chart stays unverified; re-running is safe.

Identity

chart is one EHR chart. Charts of the same person share masterPatientId and list each other in duplicatePatientIds; identityLinks gives the evidence for each link:

`basis`	Meaning
`name_dob`	Linked automatically: first name, last name and date of birth matched, with every other populated identifier agreeing.
`manual`	Linked by a person in the registry.
`legacy_name_dob_match`	Linked before the basis was recorded; the charts’ names and dates of birth agree.
`legacy_unverified`	Linked before the basis was recorded with nothing on the charts corroborating it. May rest on a shared household phone or email — do not treat as the same person.

Shared phone or email alone never links charts. MRNs are per EHR and are not used to link charts across EHRs. Existing links are not rewritten; review legacy_unverified links in the patient registry. A link or unlink changes every member chart’s updatedAt and publishes patient.identity_changed for each on GET /v4/changes.

Charts waiting for identity review

identityReview says whether a chart is linked, pending_review or unmatched. A chart is pending_review when matching found identities it would not link on its own: some identifiers agreed and others did not, for example the same name and date of birth with a different phone. It stays unlinked, with no masterPatientId, until a person decides. candidates names the identities in your organization it might belong to and which identifiers agreed (name_dob, phone, email). A candidate is not a link: do not merge charts on it, and treat a phone or email match without name_dob as a possible relative. A chart may be pending_review with no candidates listed. A reviewer’s decision arrives as an ordinary link: the chart joins the group with basis manual, and every member gets a new updatedAt and a patient.identity_changed event. Contacts: with include=contact on GET /v4/patients/{id}, each phone number carries source (ehr_chart or intake) and sourceUpdatedAt. Numbers are never copied between linked charts, so you can prefer one EHR’s chart. Linked charts can disagree on phone, email and address. Being linked says the charts are the same person; it does not say which chart’s contact details are current. The API does not tell you which contact is newer:

updatedAt and an ehr_chart number’s sourceUpdatedAt advance together for every member of a group when the group changes, and for any demographic change on the chart. They order chart versions, not contact edits.
No field records when the EHR last changed a contact, or which contact the practice prefers.

Keep each chart’s contacts separate. Do not pick a current contact by matching phone numbers or by ordering chart ids.

Reviewed contact sources

When linked charts disagree, a person can record which chart holds the current phone, email or mailing address. With include=contact (which needs read:patient_pii), GET /v4/patients/{id} and GET /v4/patients return:

{
  "identityMembershipVersion": "v1:3f2a…",
  "contactVersions": { "phone": "v1:9c1e…", "email": null, "mailingAddress": "v1:77d0…" },
  "contactSources": {
    "phone": {
      "status": "resolved",
      "decisionId": "4be6…",
      "sourcePatientId": "pat_0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a",
      "valueVersion": "v1:9c1e…",
      "membershipVersion": "v1:3f2a…",
      "decidedAt": "2026-10-07T15:04:05.000Z",
      "invalidReason": null,
      "value": "3135550123"
    },
    "email": { "status": "unresolved", "decisionId": null, "sourcePatientId": null, "valueVersion": null, "membershipVersion": null, "decidedAt": null, "invalidReason": null, "value": null },
    "mailingAddress": { "status": "stale", "invalidReason": "value_changed", "value": null, "…": "…" }
  }
}

identityMembershipVersion (also returned with include=identity and on every history chart) changes whenever a chart joins or leaves the identity. contactVersions is a version of this chart’s own contact values. Both are opaque: compare them as strings.

unresolved: no reviewed choice is recorded. This is the normal state for most identities and does not mean the contact needs review: where the charts agree, or your own rule clearly prefers one chart, use it. A review is only for contacts the charts dispute. Never settle a dispute by chart id or updatedAt.
resolved: the choice still holds. The source chart is still a member, the identity’s members are the ones the reviewer saw, and the source chart’s value is the one reviewed. value is that chart’s current value.
stale: the choice no longer holds (source_unlinked, membership_changed, value_missing or value_changed). Treat it as unresolved until a person reviews it again.

To pin a choice, keep decisionId, valueVersion and membershipVersion. Use them only while the same response shows status: "resolved" and membershipVersion equal to identityMembershipVersion. A choice is the same on every chart of the identity and appears only to your organization. It records where the contact comes from, not consent: your opt-out and do-not-contact rules still apply. Nothing is chosen automatically, including for charts linked before this existed.

Limits

25 charts per request, 200 rows per chart per resource, 2,500 rows per response.
Requests count against the app’s normal rate limit.

Rollout and backfill

On deploy the coverage grid is empty: every chart reads not_imported until the rolling sync’s first verified weeks (within five minutes per connector), and history older than the lookback reads partial until backfilled.
Historical backfill is the appointments-coverage-backfill task, run per connector with { "connectorId", "from": "YYYY-MM-DD" }. It reads unverified weeks newest-first, four per run, re-queues itself, resumes from the grid after any interruption, and reports stalled weeks the EHR refused three times. It is started by an operator, not on a schedule.
EZDerm groups can be made ready immediately with a per-patient refresh, without waiting for the backfill.

Not provided

Bill completeness. No connector records bill discovery completeness.
ModMed per-patient history. Needs a verified patient-scoped appointment endpoint (the spec shows GET /ema/ws/v3/appointments?where=patient==…, but it is unverified against live data).
Notes are not part of this endpoint.

Overview

Core Concepts

Working with Appointments

Working with Patients

Prescriptions

Patient Tracking

Building Apps

Request

Response

Consistency: snapshot, version, cursor

Readiness

Appointments

Bills

Groups

What the evidence does not guarantee

Appointments the EHR no longer has

Per-patient refresh

Identity

Charts waiting for identity review

Reviewed contact sources

Limits

Rollout and backfill

Not provided

​Request

​Response

​Consistency: snapshot, version, cursor

​Readiness

​Appointments

​Bills

​Groups

​What the evidence does not guarantee

​Appointments the EHR no longer has

​Per-patient refresh

​Identity

​Charts waiting for identity review

​Reviewed contact sources

​Limits

​Rollout and backfill

​Not provided

Request

Response

Consistency: snapshot, version, cursor

Readiness

Appointments

Bills

Groups

What the evidence does not guarantee

Appointments the EHR no longer has

Per-patient refresh

Identity

Charts waiting for identity review

Reviewed contact sources

Limits

Rollout and backfill

Not provided