Written and maintained by CASRAI Editorial Board
Last updated
The Heidi Health API and enterprise EHR connector suite enable hospitals, outpatient medical groups, and digital health platforms to embed Heidi Health‘s ambient AI clinical documentation engine directly inside existing Electronic Health Record (EHR) and telehealth workflows. Rather than requiring clinicians to manually copy and paste generated SOAP notes between browser tabs, a native Heidi Health integration automates patient schedule synchronization, encounter context retrieval, real-time audio transcription, and structured clinical note write-back using standardized healthcare interoperability protocols and RESTful developer endpoints.
How Does Heidi Health Integrate with Epic and EHR Systems?
Heidi Health supports three distinct integration tiers depending on whether an organization operates an enterprise health system EHR, an ambulatory cloud EHR, or a custom proprietary platform:
1. Epic Showroom Integration (Hyperspace and Haiku)
Listed in the Epic Showroom (formerly Epic App Orchard), Heidi Health integrates natively into both desktop Epic Hyperspace and mobile Epic Haiku workflows:
- Contextual Single Sign-On (SSO) Launch: Clinicians launch Heidi directly from an open patient encounter in Epic without secondary login prompts. The integration automatically binds the ambient recording session to the active patient MRN, encounter CSN, and provider identity.
- Mobile Capture via Epic Haiku: Physicians can initiate ambient encounter capture at the bedside or in the exam room using Epic Haiku on iOS or Android, then review and finalize the structured clinical note on their desktop workstation in Epic Hyperspace.
- Structured Note and SmartData Element Write-Back: Upon clinician sign-off, finalized clinical notes—formatted to match institutional H&P, SOAP, or specialty consult templates—are pushed back into the Epic chart as discrete clinical notes or mapped to specific Epic SmartData Elements (SDEs) and SmartLists.
2. athenahealth Marketplace Integration (athenaOne)
For ambulatory medical groups running athenaOne, Heidi Health provides a certified athenahealth Marketplace connector that compares favorably with other athenahealth AI scribe integrations:
- Automated Appointment Schedule Sync: Heidi automatically pulls the provider’s daily appointment schedule and patient demographics from athenaOne so clinicians can select the scheduled patient with a single click.
- Section-Level Encounter Push: Instead of dumping an unformatted block of text into a single field, the integration maps generated content directly into corresponding athenaOne encounter sections—including History of Present Illness (HPI), Review of Systems (ROS), Physical Exam, and Assessment & Plan.
3. Ambulatory, Allied Health, and Regional PMS Connectors
Beyond US enterprise EHRs, Heidi Health maintains native integrations and browser-assisted connectors for ambulatory and international practice management systems (PMS), including MEDITECH, Best Practice, MedicalDirector, Gentu (Magentus), Cliniko, and Halaxy, enabling automatic appointment list synchronization and one-click note filing.
What HL7 or FHIR Interfaces Does Heidi Health Support?
Enterprise health IT architects evaluating Heidi Health’s interoperability standards rely on Epic FHIR and standard HL7 FHIR API specifications alongside RESTful webhooks:
| Interface / Resource Type | Standard / Protocol | Clinical Data Flow & Function |
|---|---|---|
| App Launch & Auth | HL7 SMART on FHIR (OAuth 2.0 / OpenID Connect) | Authenticates the clinician and passes active patient, encounter, and practitioner context tokens into the Heidi session. |
| Demographics & Schedule | FHIR R4 Patient, Practitioner, Appointment, Encounter |
Read-only retrieval of patient identifiers, age/sex context, and daily clinic appointment lists. |
| Clinical Note Filing | FHIR R4 DocumentReference / HL7 v2 MDM^T02 |
Writes finalized, clinician-verified consultation notes, referral letters, and discharge summaries back into the patient chart. |
| Custom EHR & Telehealth | Heidi REST API & Embeddable Web Widget SDK (HTTPS/JSON + WebSockets) | Allows custom EHRs and telehealth platforms to authenticate via JWT, stream encounter audio, and retrieve structured JSON clinical notes. |
Heidi Health Developer API and Embeddable Widget Architecture
Digital health companies, proprietary EHR vendors, and telehealth platforms can integrate Heidi directly into their own clinical user interfaces using the Heidi Developer API and Embeddable Widget SDK:
- Server-to-Server JWT Authentication: The host EHR backend authenticates against the Heidi API using an organization API key to mint a short-lived, practitioner-scoped JSON Web Token (JWT). This prevents client-side exposure of master API credentials.
- Session Initialization and Context Seeding: Calling the session creation endpoint initializes a new clinical encounter and optionally passes pre-visit context notes (such as triage vitals, intake questionnaire responses, or prior visit summaries) to ground the AI generation.
- Real-Time Audio Streaming or Multi-Part Upload: The client application streams live microphone or WebRTC telehealth audio via secure WebSockets—or uploads a completed audio stream—for real-time speech-to-text diarization. In accordance with HIPAA-compliant AI medical scribe standards, audio is processed transiently in memory without persistent recording storage.
- Template-Driven Note Generation and
Ask HeidiRefinement: The host application requests structured output mapped to a specific clinical template ID (returning JSON sections for HPI, Exam, Impression, Plan, or patient instructions) and can invoke conversational refinement endpoints to generate referral letters or patient handouts from the same session transcript.
Security, HIPAA BAA, and Governance Checklists for API Deployment
- Execute a HIPAA Business Associate Agreement (BAA): Before connecting production EHR FHIR endpoints or transmitting live patient audio over the Heidi API, health systems must execute a HIPAA BAA (and regional equivalents such as a GDPR Data Processing Addendum) with Heidi Health.
- Enforce Least-Privilege FHIR Scopes: Configure SMART on FHIR client registrations in Epic or Oracle Health to grant only the minimum required scopes (e.g.,
launch,patient/Patient.read,patient/Encounter.read,patient/DocumentReference.write). - Mandate Human-in-the-Loop Attestation Before Final Sign-Off: Configure EHR write-back workflows so API-generated notes land in an ”In-Progress” or ”Unverified” status inside the EHR, requiring the treating clinician to review, edit, and electronically sign the note before it becomes part of the legal medical record.
Frequently Asked Questions
How does Heidi Health integrate with Epic and EHR systems?
Heidi Health integrates natively with Epic via the Epic Showroom (supporting both desktop Hyperspace and mobile Haiku workflows) and with athenaOne via the athenahealth Marketplace, as well as ambulatory systems like MEDITECH, Best Practice, Gentu, and Cliniko. These integrations synchronize daily appointment schedules, launch in context from the open patient chart, and push structured clinical notes directly back into the encounter record.
What HL7 or FHIR interfaces does Heidi Health support?
Heidi Health supports HL7 SMART on FHIR (OAuth 2.0 / OpenID Connect) for contextual EHR launch and authentication, along with FHIR R4 resources including Patient, Practitioner, Appointment, Encounter, and DocumentReference for reading schedule context and writing finalized clinical notes. For custom EHR and telehealth platforms, Heidi also provides a RESTful JSON API and embeddable Web Widget SDK.
