ModMed

What HealOS does in ModMed

AI Frontdesk

What the AI Frontdesk (AI Receptionist) can do in ModMed during a call:

Task	Available
Find the caller’s chart	Yes
Register a new patient	Yes
Find open slots	Yes
Book an appointment	Yes
Look up upcoming appointments	Yes
Cancel an appointment	Yes
Reschedule an appointment	Yes

Connect it from AI Frontdesk → Integrations → Connect an EHR (Connect your EHR).

AI Scribe

How a finished AI Scribe note gets into ModMed:

Route	Available
Sent from HealOS: the note is written to the patient’s chart through the EHR connection	On request
Filled by the HealOS Chrome extension into the ModMed note open in the clinician’s browser	—

Connection

Method: Official API (API credentials). How the methods compare. You provide

ModMed API credentials, which ModMed’s practice solutions team issues to your practice: username, password, your firm’s URL prefix and API key (optionally the provider’s NPI).
Enter them in AI Frontdesk → Integrations → Connect an EHR or Integrations (AI Scribe Integrations).

HealOS does

Uses ModMed’s official FHIR R4 and REST APIs with your firm’s own API key.
Reschedules by booking the new time first, then cancelling the old one.

Yes: works once the practice connects the EHR (or, for the Chrome extension, installs it).
On request: built; HealOS turns it on for a practice after a review with them.
Specific setups: built for particular practice configurations; ask us before relying on it.

A Yes means the workflow exists, not that every practice’s setup allows it: practice settings, user permissions and the EHR plan can still limit it, so confirm during onboarding.

API actions

This is a catalog of what HealOS can do in each EHR. Running these actions through the HealOS API is coming later. Listing them (GET /ehr/actions) and checking which EHRs your organization has connected (GET /ehr/connections), with the ehr:read scope, are rolling out: they work on staging but are not yet available on api.healos.ai. Every action runs against the practice’s live EHR, never a sandbox.

HealOS supports 8 actions in ModMed. Action names (modmed.<action>) are stable.

Action	Description	Effect	Inputs	Outputs
Search patients `modmed.search_patients`	Find an existing patient in the EHR by phone number, name, date of birth or email.	read	`phone`, `first_name`, `last_name`, `dob`, `email`	`found`, `patient_id`, `display_name`
Create patient `modmed.create_patient`	Register a new patient chart in the EHR. Some EHRs need extra fields (for example a mailing address on NextGen).	write	`phone`, `first_name`, `last_name`, `dob`, `gender`, `email`, `provider_id`, `address1`, `city`, `state`, `zip`	`patient_id`, `display_name`
Search appointment slots `modmed.search_slots`	List open appointment times, optionally narrowed to a window, provider, visit type or location.	read	`start_at_utc`, `end_at_utc`, `provider_id`, `appointment_type`, `location`, `patient_dob`	`slots`
Book appointment `modmed.book_appointment`	Book an appointment for an existing patient, from a slot returned by search_slots.	write	`patient_id`, `slot_id`, `start_at_utc`, `duration_minutes`, `provider_id`, `appointment_type`, `chief_complaint`, `notes`	`appointment_id`, `patient_id`, `start_at_utc`
List upcoming appointments `modmed.list_appointments`	List a patient’s upcoming appointments.	read	`patient_id`	`appointments`
Cancel appointment `modmed.cancel_appointment`	Cancel one of the patient’s appointments. Refused unless the appointment belongs to that patient.	write	`patient_id`, `appointment_id`	`appointment_id`, `status`
Reschedule appointment `modmed.reschedule_appointment`	Move one of the patient’s appointments to a new time. Refused unless the appointment belongs to that patient.	write	`patient_id`, `appointment_id`, `slot_id`, `start_at_utc`, `duration_minutes`	`appointment_id`, `start_at_utc`
Push clinical note `modmed.push_note`	Write a HealOS Scribe note into the patient’s chart in the EHR.	write	`session_id`, `content`	`status`, `job_id`

Search patients

modmed.search_patients · patients · version 1 Find an existing patient in the EHR by phone number, name, date of birth or email.

Safety

External effect: read
Writes to the EHR: No
Idempotent: Yes
Safe to retry: Yes
Dry run: Not supported
Touches the practice’s live EHR: Yes

Inputs Send at least one field.

Field	Type	Required	Description
`phone`	string	No	Phone number, E.164 preferred.
`first_name`	string	No	Patient first name.
`last_name`	string	No	Patient last name.
`dob`	string (date)	No	Date of birth (YYYY-MM-DD).
`email`	string (email)	No	Email address.

Outputs

Field	Type	Description
`found`	boolean	True on a match.
`patient_id`	string	The EHR’s patient id, as returned by search_patients or create_patient.
`display_name`	string	Patient display name. Null when the EHR does not return it.

Create patient

modmed.create_patient · patients · version 1 Register a new patient chart in the EHR. Some EHRs need extra fields (for example a mailing address on NextGen).

Safety

External effect: write
Writes to the EHR: Yes
Idempotent: No
Safe to retry: No. After a timeout or unclear result, check the EHR before trying again
Dry run: Not supported
Touches the practice’s live EHR: Yes
Duplicate check: not run by HealOS before creating

Inputs

Field	Type	Required	Description
`phone`	string	Yes	Phone number, E.164 preferred.
`first_name`	string	Yes	Patient first name.
`last_name`	string	Yes	Patient last name.
`dob`	string (date)	No	Date of birth (YYYY-MM-DD).
`gender`	string	No	Gender as the patient states it.
`email`	string (email)	No	Email address.
`provider_id`	string	No	EHR provider id to file the chart under, where the EHR assigns one at registration.
`address1`	string	No	Street address, for EHRs that require one.
`city`	string	No	City, for EHRs that require an address.
`state`	string	No	State, for EHRs that require an address.
`zip`	string	No	ZIP code, for EHRs that require an address.

Outputs

Field	Type	Description
`patient_id`	string	The EHR’s patient id, as returned by search_patients or create_patient.
`display_name`	string	Patient display name. Null when the EHR does not return it.

Search appointment slots

modmed.search_slots · scheduling · version 1 List open appointment times, optionally narrowed to a window, provider, visit type or location.

Safety

External effect: read
Writes to the EHR: No
Idempotent: Yes
Safe to retry: Yes
Dry run: Not supported
Touches the practice’s live EHR: Yes

Inputs

Field	Type	Required	Description
`start_at_utc`	string (date-time)	No	Window start (ISO 8601 UTC).
`end_at_utc`	string (date-time)	No	Window end (ISO 8601 UTC).
`provider_id`	string	No	EHR provider id.
`appointment_type`	string	No	Visit type id or name.
`location`	string	No	Location name or id, for multi-location practices.
`patient_dob`	string (date)	No	Patient date of birth (YYYY-MM-DD), used only to honour per-provider age limits.

Outputs

Field	Type	Description
`slots`	array of object

Each item in slots:

Field	Type	Description
`slot_id`	string	Opaque slot id from search_slots. Preferred over start_at_utc: it carries the provider, visit type and duration the EHR needs.
`start_at_utc`	string	Start (ISO 8601 UTC). Null when the EHR does not return it.
`date`	string	Date in the practice’s time zone (YYYY-MM-DD).
`time`	string	Time in the practice’s time zone.
`duration_minutes`	integer	Visit length in minutes.
`provider_id`	string	The EHR’s provider id. Null when the EHR does not return it.
`appointment_type`	string	Visit type. Null when the EHR does not return it.

Book appointment

modmed.book_appointment · scheduling · version 1 Book an appointment for an existing patient, from a slot returned by search_slots.

Safety

External effect: write
Writes to the EHR: Yes
Idempotent: No
Safe to retry: No. After a timeout or unclear result, check the EHR before trying again
Dry run: Not supported
Touches the practice’s live EHR: Yes

Inputs Send slot_id or start_at_utc.

Field	Type	Required	Description
`patient_id`	string	Yes	The EHR’s patient id, as returned by search_patients or create_patient.
`slot_id`	string	No	Opaque slot id from search_slots. Preferred over start_at_utc: it carries the provider, visit type and duration the EHR needs.
`start_at_utc`	string (date-time)	No	Appointment start as an ISO 8601 UTC instant.
`duration_minutes`	integer	No	Visit length in minutes.
`provider_id`	string	No	EHR provider id.
`appointment_type`	string	No	Visit type id or name.
`chief_complaint`	string	No	Reason for the visit.
`notes`	string	No	Free-text note stored on the appointment.

Outputs

Field	Type	Description
`appointment_id`	string	The EHR’s appointment id, as returned by list_appointments or book_appointment.
`patient_id`	string	The EHR’s patient id, as returned by search_patients or create_patient.
`start_at_utc`	string	Booked start (ISO 8601 UTC). Null when the EHR does not return it.

List upcoming appointments

modmed.list_appointments · scheduling · version 1 List a patient’s upcoming appointments.

Safety

External effect: read
Writes to the EHR: No
Idempotent: Yes
Safe to retry: Yes
Dry run: Not supported
Touches the practice’s live EHR: Yes

Inputs

Field	Type	Required	Description
`patient_id`	string	Yes	The EHR’s patient id, as returned by search_patients or create_patient.

Outputs

Field	Type	Description
`appointments`	array of object

Each item in appointments:

Field	Type	Description
`appointment_id`	string	The EHR’s appointment id, as returned by list_appointments or book_appointment.
`start_at_utc`	string	Start as an ISO 8601 UTC instant. Null when the EHR does not return it.
`end_at_utc`	string	End as an ISO 8601 UTC instant. Null when the EHR does not return it.
`date`	string	Start date in the practice’s time zone (YYYY-MM-DD).
`time`	string	Start time in the practice’s time zone.
`provider_id`	string	The EHR’s provider id. Null when the EHR does not return it.
`provider_name`	string	Provider display name. Null when the EHR does not return it.
`reason`	string	Visit reason or type. Null when the EHR does not return it.

Cancel appointment

modmed.cancel_appointment · scheduling · version 1 Cancel one of the patient’s appointments. Refused unless the appointment belongs to that patient.

Safety

External effect: write
Writes to the EHR: Yes
Idempotent: No
Safe to retry: No. After a timeout or unclear result, check the EHR before trying again
Dry run: Not supported
Touches the practice’s live EHR: Yes
Ownership check: the appointment must belong to the patient, or the action is refused

Inputs

Field	Type	Required	Description
`patient_id`	string	Yes	The EHR’s patient id, as returned by search_patients or create_patient.
`appointment_id`	string	Yes	The EHR’s appointment id, as returned by list_appointments or book_appointment.

Outputs

Field	Type	Description
`appointment_id`	string	The EHR’s appointment id, as returned by list_appointments or book_appointment.
`status`	string	The appointment’s new status.

Reschedule appointment

modmed.reschedule_appointment · scheduling · version 1 Move one of the patient’s appointments to a new time. Refused unless the appointment belongs to that patient.

Safety

External effect: write
Writes to the EHR: Yes
Idempotent: No
Safe to retry: No. After a timeout or unclear result, check the EHR before trying again
Dry run: Not supported
Touches the practice’s live EHR: Yes
Ownership check: the appointment must belong to the patient, or the action is refused

Inputs Send slot_id or start_at_utc.

Field	Type	Required	Description
`patient_id`	string	Yes	The EHR’s patient id, as returned by search_patients or create_patient.
`appointment_id`	string	Yes	The EHR’s appointment id, as returned by list_appointments or book_appointment.
`slot_id`	string	No	Opaque slot id from search_slots. Preferred over start_at_utc: it carries the provider, visit type and duration the EHR needs.
`start_at_utc`	string (date-time)	No	Appointment start as an ISO 8601 UTC instant.
`duration_minutes`	integer	No	Visit length in minutes.

Outputs

Field	Type	Description
`appointment_id`	string	The EHR’s appointment id, as returned by list_appointments or book_appointment.
`start_at_utc`	string	New start (ISO 8601 UTC). Null when the EHR does not return it.

Push clinical note

modmed.push_note · notes · version 1 Write a HealOS Scribe note into the patient’s chart in the EHR.

Safety

External effect: write
Writes to the EHR: Yes
Idempotent: No
Safe to retry: No. After a timeout or unclear result, check the EHR before trying again
Dry run: Not supported
Touches the practice’s live EHR: Yes

Synchronous: the result reports the saved note.

Inputs

Field	Type	Required	Description
`session_id`	string	Yes	HealOS session id the note belongs to.
`content`	string	Yes	Note text to write to the chart.

Outputs

Field	Type	Description
`status`	string	saved when the EHR stored the note; queued when the write runs asynchronously.
`job_id`	string	Job id when the write is queued. Null when the EHR does not return it.

Get Started

Recipes

Product Guides

Connections

EHR Integrations

Trust

Go Live

What HealOS does in ModMed

AI Frontdesk

AI Scribe

Connection

API actions

Search patients

Create patient

Search appointment slots

Book appointment

List upcoming appointments

Cancel appointment

Reschedule appointment

Push clinical note

​What HealOS does in ModMed

​AI Frontdesk

​AI Scribe

​Connection

​API actions

​Search patients

​Create patient

​Search appointment slots

​Book appointment

​List upcoming appointments

​Cancel appointment

​Reschedule appointment

​Push clinical note

What HealOS does in ModMed

AI Frontdesk

AI Scribe

Connection

API actions

Search patients

Create patient

Search appointment slots

Book appointment

List upcoming appointments

Cancel appointment

Reschedule appointment

Push clinical note