Headless EHR

What is a headless EHR?

A headless EHR is a clinical record system delivered as APIs rather than as a fixed user interface: a core that stores patient data, enforces access and runs workflow, and exposes all of it through FHIR and service APIs. Clinician, patient and partner applications are built separately on top of that core.

The term comes from headless commerce and headless content systems, where one back end serves any front end through APIs. In an EHR the back end carries more weight: coded clinical data, consent, audit and the rules that decide who may open a chart.

A headless EHR is different from a traditional EHR with a FHIR API added. In a traditional EHR the vendor's own screens are the main way work gets done, and the API is a side door. In a headless design the API is the only door, and the team's own apps use it exactly as partners do.

What belongs in the headless core?

The core holds everything that must stay true whichever app is in front of it: the record, identity and access, workflow state, events and the audit trail. Anything that only concerns presentation stays out of it.

• Clinical data API: A FHIR R4 server that stores and returns resources such as Patient, Encounter, Observation, Condition and MedicationRequest, profiled to US Core so partners know what to expect.
• Authorization server: OAuth 2.0 and OpenID Connect with SMART on FHIR scopes, so each app, user and patient gets only the access its token grants.
• Workflow engine: Tasks, queues and state changes for work that spans people and time, such as intake review, referral handling or result follow-up, modeled with FHIR Task or a dedicated service.
• Events: Subscriptions or webhooks that tell apps when something changed, so screens do not have to poll the API.
• Terminology: Code systems and value sets such as SNOMED CT, LOINC and RxNorm, with validation when data is written.
• Audit and consent: A record of every read and write by user, app and patient, and consent rules enforced in the core rather than in each app.

Billing, scheduling, e-prescribing and messaging can live in the core or in separate services behind the same gateway. The test is whether two apps would need the same rule. If they would, the rule belongs below the API.

How do you build a headless EHR layer by layer?

A headless EHR has three layers: the API core at the bottom, a gateway and authorization layer in the middle, and the apps on top. Build them from the bottom up, and take one complete clinical workflow through every layer before widening any of them.

• 1. Data layer: Choose the FHIR server and the profiles it enforces, define the resources the first workflow needs, and set up the audit store beside it.
• 2. Services layer: Add the workflow engine, terminology service and event delivery, each behind its own API and each writing to the same audit trail.
• 3. Gateway and authorization: Put an API gateway and the SMART on FHIR authorization server in front of the core, with token checks, rate limits and scopes for each app.
• 4. First app: Build one clinician or care team app for one workflow, such as intake to visit to signed note, using only the public APIs.
• 5. Second app: Add a patient app on the same APIs, which tests whether scopes and consent rules hold for a different type of user.
• 6. Partner access: Open the APIs to an outside system, such as a lab or a payer, through SMART Backend Services, or through an HL7 v2 bridge where the partner cannot call FHIR.

Step 4 is the check on the whole design. If the first app needs a private shortcut into the database, the API is missing something, and every later app will ask for the same shortcut.

Keep the layers in separately deployable units. The core can then be released and tested without the apps, and each app can be released without touching the core.

Which standards should the core support?

The standards that make a headless core usable by outside parties are published by HL7 International and referenced by federal certification. Building to them from the start avoids writing a second API later.

• Certified API: 45 CFR 170.315(g)(10) defines a standardized read API for patient and population services, built on US Core, SMART App Launch and Bulk Data. A headless EHR that seeks certification must meet it, while write access remains a product decision.
• Authorization: HL7's SMART App Launch guide defines how apps obtain OAuth 2.0 authorization and launch context, and its Backend Services profile covers system-to-system access without a user.
• Data profiles: US Core profiles tell partners which fields each resource carries, so validate against them on write rather than discovering gaps when a partner connects.
• Population exports: A Bulk Data export lets analytics and payer partners pull large extracts as files instead of paging through the API one patient at a time.
• Decision support: A CDS Hooks endpoint lets outside services return advice at points in the team's own apps, such as opening a chart or signing an order.

Certification is needed for some products and not others. A product that clinicians use to meet CMS program requirements for certified EHR technology may need it; a specialty tool that sits beside a certified EHR may not.

Who owns safety and compliance when you own the screens?

The product team does. A packaged EHR ships its screens with the vendor's design and testing behind them, and a headless EHR moves that work to whoever builds the apps.

• Clinical display: Units, abnormal flags, allergy and medication warnings and patient identity banners must be designed and tested in every app that shows them.
• Usability testing: Every app needs task-based testing with real clinicians on the tasks where an error can harm a patient, and a product seeking certification has formal usability requirements for some clinical capabilities.
• Access control: The HIPAA Security Rule at 45 CFR 164.312 requires unique user identification, an emergency access procedure, audit controls and person or entity authentication, and the core must enforce them for every app.
• Hosting: A cloud provider that stores ePHI for the product is a business associate even if it cannot view the data, according to HHS guidance on HIPAA and cloud computing.
• Certification duties: If the product becomes certified health IT, its developer also takes on information blocking obligations, so make the certification decision early and design data access around it.

None of this is a reason to avoid a headless design. It is the price of control, and it belongs in the plan from the first sprint, not after the first clinical pilot.

What the core-to-app contract must define

Every app depends on the core behaving the same way tomorrow as today. A written contract, checked by automated tests, keeps that promise as both sides change.

• Versioning: How API versions are numbered, how long an old version stays available, and how app teams learn of a breaking change.
• Profiles: The FHIR profiles and extensions each resource must meet, enforced by validation on write so a faulty app cannot store a malformed record.
• Scopes: The SMART scopes each type of app may request, reviewed whenever an app adds a feature that reads or writes new data.
• Errors: One error format, such as FHIR OperationOutcome, with codes an app can act on instead of free-text messages.
• Events: Which changes raise events, what the payload contains, the delivery guarantee and the retry behavior.
• Limits: Rate limits, page sizes and supported search parameters, published so app teams design within them.
• Test data: A shared set of synthetic patients and a sandbox configured like production.

Publish the contract where every app team can read it, and run its tests on each core release. A change that fails them waits until the apps that depend on it are ready.

Where headless EHR projects go wrong

• Logic in one app: A rule such as who may sign a note lives in one front end, and the next app lets any user sign.
• Private database access: A reporting or admin tool reads tables directly, so audit and consent rules never apply to it.
• Custom shapes for standard data: Data that fits a standard FHIR resource gets a custom structure, and partners cannot read it.
• Polling instead of events: Apps poll the API on a timer, load grows with every user, and changes still arrive late.
• Screens without clinical review: A new app shows results without units or abnormal flags because no clinician reviewed the design.
• No version policy: A field rename in the core breaks the patient app on the day it ships.

Each of these starts as a shortcut taken to meet a release date. The contract and the rule that apps use only public APIs are what stop the shortcuts from becoming the architecture.

How Agnotic can help

A headless EHR means building both the core and the apps, and keeping the contract between them stable as both grow. Agnotic Technologies builds that for the client: FHIR R4 data APIs with US Core profiles, SMART on FHIR authorization, workflow and event services, audit and consent in the core, and the clinician and patient apps on top.

For teams that already run a core, Agnotic reviews the API contract and the failure points above before the next app is added.

Sources

• HL7 International: SMART App Launch, including Backend Services
• 45 CFR 170.315: certification criteria, including (g)(10) standardized API
• 45 CFR 164.312: HIPAA Security Rule technical safeguards
• HHS: Guidance on HIPAA and cloud computing