Acuity Scheduling

What HealOS does in Acuity Scheduling

AI Frontdesk

What the AI Frontdesk (AI Receptionist) can do in Acuity Scheduling 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

AI Scribe notes cannot be sent to Acuity Scheduling yet; copy the note from HealOS.

Connection

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

Sign in to Acuity in the OAuth window from AI Frontdesk → Integrations → Connect an EHR.
Or paste your Acuity User ID and API key (Acuity: Settings → Integrations → API). API keys need an Acuity plan that includes API access.

HealOS does

Uses Acuity’s official scheduling API with your authorization.
Connecting with one method replaces the other.

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 7 actions in Acuity Scheduling. Action names (acuity.<action>) are stable.

Action	Description	Effect	Inputs	Outputs
Search patients `acuity.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 `acuity.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 `acuity.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 `acuity.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 `acuity.list_appointments`	List a patient’s upcoming appointments.	read	`patient_id`	`appointments`
Cancel appointment `acuity.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 `acuity.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`

Search patients

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

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

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

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

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

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

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

Get Started

Recipes

Product Guides

Connections

EHR Integrations

Trust

Go Live

What HealOS does in Acuity Scheduling

AI Frontdesk

AI Scribe

Connection

API actions

Search patients

Create patient

Search appointment slots

Book appointment

List upcoming appointments

Cancel appointment

Reschedule appointment

​What HealOS does in Acuity Scheduling

​AI Frontdesk

​AI Scribe

​Connection

​API actions

​Search patients

​Create patient

​Search appointment slots

​Book appointment

​List upcoming appointments

​Cancel appointment

​Reschedule appointment

What HealOS does in Acuity Scheduling

AI Frontdesk

AI Scribe

Connection

API actions

Search patients

Create patient

Search appointment slots

Book appointment

List upcoming appointments

Cancel appointment

Reschedule appointment