> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ModMed

> What AI Frontdesk and AI Scribe do in ModMed, and its 8 API actions

## 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](https://docs.healos.ai/guides/receptionist/connect-your-ehr.md)).

### 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](https://docs.healos.ai/guides/scribe/chrome-extension.md) into the ModMed note open in the clinician's browser | — |

### Connection

**Method:** Official API (API credentials). [How the methods compare](https://docs.healos.ai/connections/overview.md).

**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.

> [!NOTE]
>
> * **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

> [!WARNING]
>
> 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.

> [!NOTE]
>
> **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).

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **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.

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **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.

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.