athenahealth

What HealOS does in athenahealth

AI Frontdesk

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

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

AI Scribe

How a finished AI Scribe note gets into athenahealth:

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 athenahealth note open in the clinician’s browser	Yes

Connection

Method: HealOS cloud browser, Official API (API credentials), Chrome extension. How the methods compare. You provide

For AI Frontdesk: a dedicated athenaOne user (username and password) and its authenticator (TOTP) secret, pasted as the base32 key, an otpauth:// link or the QR code image, in AI Frontdesk → Integrations → Connect an EHR.
For sending AI Scribe notes from HealOS (on request): athenahealth API credentials (Client ID, Client Secret and Practice ID) in Integrations (AI Scribe Integrations).

HealOS does

Checks the sign-in before saving anything: a login that fails is not stored.
Stores the credentials encrypted and signs in from a secure, US-based cloud browser.
Keeps one signed-in session per practice and renews it during business hours, so calls don’t wait for a login.
Generates the authenticator codes itself, so no one has to read codes to HealOS.

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 5 actions in athenahealth. Action names (athena.<action>) are stable.

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

Search patients

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

Runs in a cloud browser session against the EHR’s web app: expect several seconds per call and limited concurrency per practice.

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

athena.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: searches by last name and date of birth first, and links an exact single match instead of creating a chart

Runs in a cloud browser session against the EHR’s web app: expect several seconds per call and limited concurrency per practice.

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

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

Runs in a cloud browser session against the EHR’s web app: expect several seconds per call and limited concurrency per practice.

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

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

Runs in a cloud browser session against the EHR’s web app: expect several seconds per call and limited concurrency per practice.

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

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

Runs in a cloud browser session against the EHR’s web app: expect several seconds per call and limited concurrency per practice.

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.

Get Started

Recipes

Product Guides

Connections

EHR Integrations

Trust

Go Live

What HealOS does in athenahealth

AI Frontdesk

AI Scribe

Connection

API actions

Search patients

Create patient

Search appointment slots

Book appointment

List upcoming appointments

​What HealOS does in athenahealth

​AI Frontdesk

​AI Scribe

​Connection

​API actions

​Search patients

​Create patient

​Search appointment slots

​Book appointment

​List upcoming appointments

What HealOS does in athenahealth

AI Frontdesk

AI Scribe

Connection

API actions

Search patients

Create patient

Search appointment slots

Book appointment

List upcoming appointments