Availability & the appointment finder

Three endpoints answer “when can this patient be seen?”. They read the same EHR but answer different questions:

Endpoint	What it returns	Use it for
`GET /v4/schedule/slots`	Bookable slots for a window. Max AI holds and pending bookings are already subtracted, and override-only slots are never offered.	Everything you book from: slot pickers, the final check before `POST /appointments`.
`GET /v4/schedule/finder`	The EHR’s own view: one search of its appointment finder, every option it offers, grouped by provider and facility. Nothing is subtracted.	Showing what staff see on the EHR’s finder screen, first-available searches, weekday and part-of-day filters, override-only slots.
`GET /v4/schedule/finder/provider-locations`	Provider and facility pairs that can take an appointment type (eligible, not necessarily open).	Building provider and location pickers before searching.

All three need the read:schedule scope, and all three accept the optional X-Session-Token header.

Book from /schedule/slots, not from /schedule/finder. A finder slot can already be held by another booking session in Max AI, or taken by a booking accepted but not yet written to the EHR. /schedule/slots subtracts both. A booking is re-checked against the EHR either way, so the cost of booking from the finder is a 409 slot_unavailable, not a double-book.

Which EHRs support what

Ask GET /v4/schedule/capabilities once, at configuration time:

{
  "success": true,
  "data": {
    "ehr": "modmed",
    "slotSearchStrategy": "native",
    "appointmentFinder": true,
    "availabilitySearchOptions": [
      "timeFrame=first_available",
      "timeFrame=specific_date",
      "timeFrame=date_range",
      "timeFrame=time_frame",
      "weekday",
      "timeOfDay",
      "display",
      "allowOverride",
      "alternateDurations",
      "afterFirstAppointment",
      "bufferMinutes"
    ],
    "availabilityCompleteness": "complete"
  }
}

(Other capability fields omitted.)

appointmentFinder: false means both finder endpoints return 501 capability_unsupported for this organization. Today ModMed has a finder and EZDerm does not. /schedule/slots works on both.
availabilitySearchOptions lists the finder parameters this EHR honours, by public name. A timeFrame mode or option missing from it is a 400 that names the parameter.
availabilityCompleteness: "complete" means this EHR’s availability is read live, so an untruncated /schedule/slots answer is the whole truth. See completeness.

Bookable slots: `GET /v4/schedule/slots`

GET /v4/schedule/slots?appointmentTypeId=atp_9f1c2d3e4b5a46f78901234567890abc&facilityId=fac_2706aaaa4bbbccccddddeeeeffff1111&from=2026-11-02&to=2026-11-15
X-Session-Token: <maxcare.appToken()>

{
  "success": true,
  "data": {
    "slots": [
      {
        "providerId": "prv_35103413aaaa4bbbccccddddeeeeffff",
        "facilityId": "fac_2706aaaa4bbbccccddddeeeeffff1111",
        "startsAt": "2026-11-02T09:15:00-05:00",
        "endsAt": "2026-11-02T09:30:00-05:00",
        "remainingCapacity": 1,
        "templateIds": []
      }
    ],
    "nextAvailableByProvider": {
      "prv_35103413aaaa4bbbccccddddeeeeffff": "2026-11-02"
    },
    "meta": {
      "sourceKind": "live_read",
      "strategy": "native",
      "completeness": "complete",
      "generatedAt": "2026-11-01T14:00:00.000Z",
      "actingAs": "user",
      "resolvedBy": "personal_connector"
    }
  }
}

Parameter	Type	Required	Notes
`appointmentTypeId`	`atp_…`	yes
`from`, `to`	`YYYY-MM-DD`	yes	Both inclusive, clinic calendar days. At most 120 days apart.
`facilityId`	`fac_…`	no	Repeat or comma-separate for several. Defaults to every facility. Facility-limited keys must pass it.
`providerIds`	`prv_…`	no	Comma-separated.
`durationMinutes`	int 5–480	no	Defaults to the type’s default duration.
`newPatient`	bool	no	Ignored on ModMed.
`consistency`	`strong`	no	No effect on ModMed: every search is already live. On EZDerm it asks the EHR instead of Max AI’s ledger.

How ModMed slots are produced

On EHRs read live (ModMed, through EMA’s appointment finder), every slot search asks the EHR; there is no cached grid. The response says so:

meta.sourceKind: "live_read" and meta.strategy: "native".
remainingCapacity is the EHR’s open seats minus Max AI holds and minus bookings Max AI has accepted but not yet written to the EHR.
templateIds is empty: finder slots are not tied to a template id you can pin.

The 5-open-days cap is handled for you. EMA’s finder returns at most 5 open days per provider per call. For a longer window Max AI calls again from the day after the earliest cut-off, up to 8 calls in total (about 40 open days per provider). Each call takes roughly 0.2–0.8 s. On EZDerm the default grid still comes from Max AI’s capacity ledger (sourceKind: "mirror", strategy: "synthesized"); consistency=strong asks the EHR.

Completeness

Branch on meta.completeness, never on strategy:

Value	Meaning
`complete`	The EHR answered live for the whole window. A slot that is absent really is unavailable.
`lower_bound`	Real availability may be larger than what is listed. Either the EHR still capped its answer after 8 calls (a long window with a busy provider), or the grid came from Max AI’s ledger, which can lag.

lower_bound cannot cause a double-book; it only under-offers. For an empty lower_bound grid, say “nothing bookable online” rather than “the practice is full”, or narrow the window and search again.

`nextAvailableByProvider`

The earliest bookable day per provider inside [from, to], computed after holds are subtracted, so every listed day has at least one slot in slots. A provider with nothing bookable in the window is absent. It never reports a day beyond to; to look further out, widen the window.

The EHR’s view: `GET /v4/schedule/finder`

One call to the EHR’s appointment finder, with every option it offers. Ids are mapped to Max AI ids; nothing else is changed.

Parameters

Parameter	Type	Default	Used by	Notes
`appointmentTypeId`	`atp_…`	required	every mode
`timeFrame`	`first_available` · `specific_date` · `time_frame` · `date_range`	required		The search mode, below.
`date`	`YYYY-MM-DD`	—	`specific_date` (required)	One clinic calendar day.
`from`, `to`	`YYYY-MM-DD`	—	`date_range` (both required)	Both inclusive, at most 120 days apart.
`offset`	int ≥ 1	—	`time_frame` (required)	How far out to start searching.
`offsetUnit`	`days` · `weeks` · `months`	—	`time_frame` (required)	Unit of `offset`.
`facilityId`	`fac_…`	every facility on the EHR instance	any	Repeat or comma-separate. Facility-limited keys must pass it.
`providerIds`	`prv_…`	every provider	any	Comma-separated. Applied to the EHR’s answer: the finder always searches every provider.
`weekday`	`monday` … `sunday`	every day	any	Repeat or comma-separate (`weekday=monday&weekday=wednesday`). In the clinic’s local time.
`timeOfDay`	`anytime` · `morning` · `afternoon` · `evening`	`anytime`	any	Part of the day, as the EHR defines it.
`display`	`by_provider` · `by_time`	`by_provider`	any	The EHR’s result order. The slots are identical either way.
`durationMinutes`	int 5–480	the type’s default	any	Visit length.
`alternateDurations`	bool	`true`	any	Let the type’s alternate durations match, so one start can appear twice with two durations.
`allowOverride`	bool	`false`	any	Also return slots that need a staff override; they carry `overrideAllowed: true`.
`afterFirstAppointment`	bool	`false`	any	Pass-through, effect unverified. Sent to the EHR as is.
`bufferMinutes`	int 0–240	`0`	any	Pass-through, effect unverified. Presumably minutes kept free around booked appointments.

A mode’s own parameters are required, and another mode’s parameters are refused: timeFrame=specific_date&from=2026-11-02 is a 400 naming from.

Modes

On ModMed every mode returns at most 5 open days per provider. A capped group comes back with truncated: true. Unlike /schedule/slots, the finder makes no follow-up calls: move or narrow the window to see more.

first_available: each provider’s earliest openings, starting at that provider’s own first open day (which can be weeks out).

GET /v4/schedule/finder?appointmentTypeId=atp_9f1c2d3e4b5a46f78901234567890abc&timeFrame=first_available

specific_date: one clinic day. Never truncated.

GET /v4/schedule/finder?appointmentTypeId=atp_9f1c2d3e4b5a46f78901234567890abc&timeFrame=specific_date&date=2026-11-02&timeOfDay=morning

time_frame: like first_available, but starting offset offsetUnit from today.

GET /v4/schedule/finder?appointmentTypeId=atp_9f1c2d3e4b5a46f78901234567890abc&timeFrame=time_frame&offset=2&offsetUnit=weeks

date_range: every provider at the listed facilities between from and to.

GET /v4/schedule/finder?appointmentTypeId=atp_9f1c2d3e4b5a46f78901234567890abc&timeFrame=date_range&from=2026-11-02&to=2026-11-15&facilityId=fac_2706aaaa4bbbccccddddeeeeffff1111,fac_8811aaaa4bbbccccddddeeeeffff2222&weekday=monday&weekday=wednesday&timeOfDay=afternoon&durationMinutes=30&display=by_time

Response

{
  "success": true,
  "data": {
    "groups": [
      {
        "providerId": "prv_35103413aaaa4bbbccccddddeeeeffff",
        "facilityId": "fac_2706aaaa4bbbccccddddeeeeffff1111",
        "timezone": "America/Detroit",
        "truncated": false,
        "slots": [
          {
            "startsAt": "2026-11-02T13:15:00-05:00",
            "endsAt": "2026-11-02T13:30:00-05:00",
            "durationMinutes": 15,
            "remainingCapacity": 1,
            "totalCapacity": 2,
            "overrideAllowed": false
          }
        ]
      }
    ],
    "meta": {
      "sourceKind": "live_read",
      "strategy": "native",
      "generatedAt": "2026-11-01T14:00:00.000Z",
      "unmappedGroupCount": 0,
      "actingAs": "system",
      "resolvedBy": "facility_system_connector"
    }
  }
}

Field	Meaning
`groups[].timezone`	IANA zone of the facility. `startsAt` / `endsAt` carry that zone’s offset.
`groups[].truncated`	The EHR capped this group; more availability exists after its last slot.
`slots[].remainingCapacity`	Open seats as the EHR counts them. Max AI holds and pending bookings are not subtracted.
`slots[].totalCapacity`	Seats the practice defines at that time (overlapping calendar preferences add up).
`slots[].overrideAllowed`	Bookable only with a staff override. Only ever `true` when you passed `allowOverride=true`.
`meta.unmappedGroupCount`	Groups for a provider or facility Max AI has not mirrored yet. They are dropped, never returned with an EHR id. A non-zero count usually clears after the next directory sync.

The finder never returns EHR-internal ids or staff names.

Provider-location pairs: `GET /v4/schedule/finder/provider-locations`

GET /v4/schedule/finder/provider-locations?appointmentTypeId=atp_9f1c2d3e4b5a46f78901234567890abc

{
  "success": true,
  "data": {
    "pairs": [
      {
        "providerId": "prv_35103413aaaa4bbbccccddddeeeeffff",
        "facilityId": "fac_2706aaaa4bbbccccddddeeeeffff1111"
      }
    ],
    "ehrSearchThreshold": 300,
    "meta": {
      "unmappedPairCount": 0,
      "actingAs": "system",
      "resolvedBy": "org_system_connector"
    }
  }
}

facilityId (optional, repeatable or comma-separated) narrows the pairs.
Pairs are limited to the facilities your API key may see. Unlike the other two endpoints, a facility-limited key may omit facilityId here.
A pair is eligible, not necessarily open: a provider can take the type at a facility and still have no open slots.
ehrSearchThreshold is the EHR’s own value, passed through. Its meaning is unknown; do not build on it.

Acting as the logged-in user

Send the App Bridge token of the user who is using your app:

const token = await maxcare.appToken();
await fetch(`${API}/v4/schedule/slots?${query}`, {
  headers: { Authorization: `Bearer ${apiKey}`, "X-Session-Token": token },
});

Max AI verifies the token (signed for your app and this organization, valid for 120 seconds) and then picks the EHR login:

The user’s own EHR login (their personal connector), when it is live, has a session and is on the same EHR instance.
Otherwise the organization’s system connector, exactly as without a token.

Every response says which:

`meta.actingAs`	`meta.resolvedBy`	Login used
`user`	`personal_connector`	The user’s own EHR login
`system`	`facility_system_connector`	The system connector assigned to the facility
`system`	`org_system_connector`	The organization-wide system connector

No header: always the system connector. The API key creator’s login is never used.
A token that does not verify (bad signature, another app, another organization, expired): 401 authorizer_unverified. Mint a fresh token and retry; tokens are short-lived by design.
There is no user-id header. Only a verified token can name a user, so one app key cannot act as any user it chooses.

Holds and writes take the same header

POST /v4/schedule/holds, POST /v4/appointments, reschedule and cancel accept X-Session-Token with the same verification and the same rule. Their response meta carries actingAs and resolvedBy. The appointment resource carries writtenBy.resolvedBy: which EHR login wrote its last change. It is visible on GET /v4/appointments/{id} too.

While the write is queued, it is the login the write is intended for.
Once it lands, it is the login that actually wrote it.
If the user’s personal login stops working before the queued write runs (session expired, disconnected, no scheduling rights), Max AI writes through the system connector instead and writtenBy.resolvedBy changes to the system value.
It is null for appointments Max AI did not write.

Writes made through the user’s own login are attributed to that user in the EHR’s own history.

Holds

POST /v4/schedule/holds reserves a slot while the patient finishes booking. Pass the hold’s id as holdId when you create the appointment.

Holds are advisory (advisory: true): they stop two Max AI booking sessions from selling the same seat, but staff booking directly in the EHR can still take it.
On EHRs read live (ModMed) the hold first reads the slot’s open seats from the EHR, then subtracts bookings Max AI has accepted but not yet written and other active holds.
409 slot_unavailable: the EHR no longer shows the slot, or Max AI holds and pending bookings already use all its seats. Search again.
502 ehr_unavailable: the EHR could not be read in time. Nothing was held; safe to retry. Holds fail closed: without the EHR’s answer nothing guards the seat.

Booking on ModMed is checked the same way, with or without a holdId.

Errors and limits

Status	`code`	When
400	`bad_request`	Invalid parameter; a mode missing its parameters or carrying another mode’s; a window over 120 days; an id from another organization or EHR instance; a finder option the EHR does not honour (the message names the public parameter).
401	`authorizer_unverified`	`X-Session-Token` present but did not verify.
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	Missing `read:schedule` (or `write:appointments` for holds), or a facility-limited key that did not pass `facilityId` on `/slots` or `/finder`.
404	`not_found`	A `facilityId` outside a facility-limited key’s facilities. Answered as not-found so keys cannot probe ids.
409	`slot_unavailable`	Holds and bookings: the seat is gone.
429	`rate_limit_exceeded`	Your key’s rate limit.
501	`capability_unsupported`	The finder endpoints on an EHR without a finder (`appointmentFinder: false`).
502	`ehr_unavailable`	The EHR did not answer within 8 seconds, or answered with an error. Safe to retry.
503	`no_booking_identity`	The organization has no live system connector for this EHR instance. One is required even when the user has a personal login.
503	`ehr_unavailable`	The appointment type’s default duration could not be read. Pass `durationMinutes` explicitly, or retry.

Live searches run at interactive priority, ahead of background syncs.
A live search stops when your client disconnects, so abandoning a request does not keep loading the EHR.
There is no caching: each request asks the EHR.

Known unknowns

These are vendor behaviours not yet proven. Do not build on them.

afterFirstAppointment and bufferMinutes are accepted by ModMed but showed no effect on the test days available. Their meaning is unverified.
ehrSearchThreshold (300 on every tenant seen) has no known meaning.
Every slot observed with allowOverride=true still had overrideAllowed: false.
A finder slot does not identify the calendar template behind it, so templateIds is empty on ModMed slots.

Overview

Core Concepts

Working with Appointments

Working with Patients

Prescriptions

Patient Tracking

Building Apps

Availability & the appointment finder

Which EHRs support what

Bookable slots: `GET /v4/schedule/slots`

How ModMed slots are produced

Completeness

`nextAvailableByProvider`

The EHR’s view: `GET /v4/schedule/finder`

Parameters

Modes

Response

Provider-location pairs: `GET /v4/schedule/finder/provider-locations`

Acting as the logged-in user

Holds and writes take the same header

Holds

Errors and limits

Known unknowns

​Which EHRs support what

​Bookable slots: GET /v4/schedule/slots

​How ModMed slots are produced

​Completeness

​nextAvailableByProvider

​The EHR’s view: GET /v4/schedule/finder

​Parameters

​Modes

​Response

​Provider-location pairs: GET /v4/schedule/finder/provider-locations

​Acting as the logged-in user

​Holds and writes take the same header

​Holds

​Errors and limits

​Known unknowns

Which EHRs support what

Bookable slots: `GET /v4/schedule/slots`

How ModMed slots are produced

Completeness

`nextAvailableByProvider`

The EHR’s view: `GET /v4/schedule/finder`

Parameters

Modes

Response

Provider-location pairs: `GET /v4/schedule/finder/provider-locations`

Acting as the logged-in user

Holds and writes take the same header

Holds

Errors and limits

Known unknowns