Skip to main content
This document covers advancedmd_list_open_slots, which finds bookable appointment slots in AdvancedMD.

​
Authentication

AdvancedMD tools use the existing AdvancedMD connector. Users configure:
  • office_code
  • username
  • password
The connector performs AdvancedMD’s two-step API login, discovers the tenant API base URL, caches the security token, and refreshes it when needed.

​
How availability is determined

AdvancedMD has no endpoint that returns open slots. Availability is derived from two calls:
  1. Scheduler columns — each column’s configured working hours, slot length, working-day mask and overbooking limit.
  2. The day’s booked visits — the time to subtract.
A slot is offered when the column is staffed that weekday and the slot has fewer bookings than the column’s per-slot limit.

​
Inputs

  • from (required): first date to search, YYYY-MM-DD.
  • to (required): last date to search, YYYY-MM-DD.
  • provider_id: restrict to one scheduler column, matched against its heading or name.
  • service_location: restrict to columns whose heading or name contains this. Note this matches the column heading, which on a per-provider scheduler is a provider name rather than a site.
  • limit: stop after this many slots.
There is deliberately no appointment-type or modality filter. Availability is derived from a column’s configured hours minus its booked visits, so a free slot carries neither attribute — both exist only on appointments already made. The range is capped internally; a very wide range is truncated rather than issuing an unbounded number of calls.

​
Outputs

The result carries from, to, count and slots. Each slot carries start_time, end_time, duration_minutes, provider_id, provider_name and service_location. hours_unconfirmed is present and true on a slot whenever its scheduler column returned no usable workweek mask, so the days it’s staffed could not be confirmed — the slot defaults to showing every day rather than none, and this is the signal that default was used. When one or more days could not be read, two more fields appear:
  • partial_results: true
  • failed_days — how many days were dropped
Treat their presence as “this range is incomplete.” A day whose visits could not be read is dropped rather than reported as free, so without these fields count: 0 means “no availability” and with them it means “no availability that we could confirm”. Retrying a narrower range usually resolves it.

​
Limits and behaviour worth knowing

  • A day whose visit lookup fails is dropped, not reported as free. Claiming availability that was never verified is worse than returning less of it, so a partial range is possible.
  • Columns hidden in AdvancedMD are never offered. A column outside its working-day mask produces nothing for that day.
  • Bookings are matched to columns by column heading, because AdvancedMD’s date-visit API rejects the numeric column id — it interpolates field names into SQL and fails the whole call on the reserved word Column. A visit with no heading cannot be attributed to a column, so it is counted against every column rather than ignored; that under-reports availability instead of inventing it.
  • A column whose slot length AdvancedMD reports as zero yields no slots. There is no default guess.
  • One call per day in the range, plus one for the columns. AdvancedMD rate limits, so keep ranges tight.
  • Availability is a snapshot, not a hold. Nothing is reserved, and a slot can be taken between reading it and booking it.

​
Expected errors