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

# Halaxy

> What AI Frontdesk and AI Scribe do in Halaxy, and its 5 API actions

## What HealOS does in Halaxy

### AI Frontdesk

What the AI Frontdesk (AI Receptionist) can do in Halaxy 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](https://docs.healos.ai/guides/receptionist/connect-your-ehr.md)).

### AI Scribe

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

### Connection

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

**You provide**

* Halaxy's API add-on. In Halaxy, Settings → Integrations → External → Create New Key, with Patient read/write, Appointment read/write and Slot read.
* Paste the Client ID, Client Secret and region (AU or EU) in **AI Frontdesk → Integrations → Connect an EHR**.

**HealOS does**

* Uses Halaxy's FHIR API (OAuth 2.0 client credentials) and renews the token as it expires.

**Limits**

* Halaxy allows about 500 API requests per minute per credential.

> [!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 5 actions in Halaxy. Action names (`halaxy.<action>`) are stable.

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

## Search patients

`halaxy.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

`halaxy.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

`halaxy.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

`halaxy.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

`halaxy.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. |


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