EHR integration in practice: Epic, Oracle Health and athenahealth APIs, HL7 feeds and timelines
An engineer’s map of the real access paths into an EHR: FHIR R4 and SMART on FHIR, HL7 v2 feeds, C-CDA documents, bulk export and network routes, then how Epic, Oracle Health and athenahealth actually hand out access, and which steps gate a project.
Ala Ben Aicha
Direct answer
EHR integration means picking one or more access paths into the record system: a FHIR R4 API authorized with SMART on FHIR, an HL7 v2 feed through an interface engine, C-CDA documents, bulk FHIR export, a vendor's proprietary API, or a network route such as an HIE or TEFCA. The vendor decides how you get credentials, but each customer organization decides whether your app is switched on in its environment. That per-site activation step, more than the code, sets the timeline.
The access paths at a glance
| Path | What moves | Direction | Typical use | Who must say yes |
|---|---|---|---|---|
| FHIR R4 REST + SMART on FHIR | JSON resources (Patient, Encounter, Observation…) | Mostly read; writes vary by vendor and resource | Patient apps, clinician apps launched from the chart, backend sync | Vendor registration plus each customer organization |
| HL7 v2 feed | Pipe-delimited event messages (ADT, ORM/OML, ORU, SIU, MDM) | Push from the EHR, and inbound results or orders | Real-time events, lab and imaging results | The site's interface team; interface engine on one or both sides |
| C-CDA documents | CDA XML (CCD, discharge summary, referral note) | Both | Transitions of care, document exchange | The site, sometimes through an HIE |
| Bulk FHIR export | NDJSON files per resource type | Read | Population analytics, registries, payer and quality feeds | Customer organization, backend client |
| Proprietary vendor API | Vendor-specific REST or web services | Read and write | Scheduling, billing, workflows the certified FHIR API does not cover | Vendor program plus customer |
| HIE / TEFCA | Documents and, increasingly, FHIR | Query and push | Cross-organization records | Network participation agreements |
FHIR R4 and SMART on FHIR: the default for new apps
In the US, certified EHRs must expose a FHIR R4 API under the §170.315(g)(10) criterion: single-patient and multi-patient read services, SMART authorization, US Core data elements, and a group-level bulk export. Since 1 January 2026, US Core 3.1.1, US Core 4.0.0 and SMART App Launch 1.0.0 are no longer accepted options for certification, so current certified products target US Core 6.1.0 and SMART v2. That is the floor you can count on. Anything above it is vendor-specific.
SMART App Launch 2.2.0 gives you three shapes of app: an EHR launch from inside the clinician's chart, a standalone launch (patient or clinician signs in from your app), and Backend Services for headless jobs with no user present. The launch details are in the SMART on FHIR app launch walkthrough.
Backend Services uses a signed JWT client assertion instead of a shared secret. The spec requires clients to support RS384 and ES384 and caps the assertion exp at five minutes (asymmetric client authentication). A generic token request looks like this:
POST /oauth2/token HTTP/1.1
Host: auth.example-ehr.org
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&scope=system/Patient.rs system/Observation.rs
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzM4NCIsImtpZCI6ImtleS0xIn0.example.signature
Read expires_in from the response and refresh ahead of it. Do not hard-code a lifetime: vendors and individual sites configure them differently.
HL7 v2 feeds through an interface engine
FHIR has not replaced HL7 v2 inside hospitals. Admissions, transfers, orders and results still move as v2 events, and a site will usually offer you an outbound ADT feed long before it offers write access over FHIR. A feed comes from the site's interface engine (or straight from the EHR) over MLLP/TCP or a VPN-backed channel, and you acknowledge each message with an ACK.
MSH|^~\&|ADT_SRC|NORTH_CAMPUS|YOUR_APP|YOUR_ORG|20261006091500||ADT^A01^ADT_A01|MSG00017|P|2.5.1
EVN|A01|20261006091500
PID|1||MRN000123^^^NORTH_CAMPUS^MR||DOE^JANE^Q||19800214|F
PV1|1|I|4W^412^B^NORTH_CAMPUS||||1234567890^SMITH^ALEX
Two things decide whether a v2 interface works: the site's interface specification (which segments and fields it actually populates, Z-segments included) and your engine's handling of retries, ordering and duplicates. Engine choice is covered in HL7 interface engines compared, and you can inspect a sample message in the in-browser HL7 parser.
C-CDA, bulk export and network routes
C-CDA is still the payload for many transitions of care, Direct messages and HIE document queries. If your product needs the record as a document, plan for CDA XML even when the EHR also offers FHIR. Mapping it to FHIR is its own job, described in C-CDA to FHIR document exchange.
Bulk FHIR (Bulk Data Access, now at v3.0.0) is an asynchronous export: kick off, poll, download NDJSON.
GET /fhir/r4/Group/example-cohort-01/$export?_type=Patient,Encounter,Observation HTTP/1.1
Host: fhir.example-ehr.org
Accept: application/fhir+json
Prefer: respond-async
Authorization: Bearer <access_token>
The server answers 202 Accepted with a Content-Location status URL. The group itself is usually defined by the customer, so a bulk project starts with a conversation about who builds and maintains that cohort.
HIE and TEFCA routes matter when you need records from organizations you have no contract with. Epic, for example, operates Epic Nexus as a TEFCA QHIN. Participation is a legal and governance track as much as a technical one; see US Core and TEFCA implementation.
Epic: open.epic, Vendor Services and Showroom
Epic's names have changed several times, which confuses search results. App Orchard is gone. Today:
- open.epic publishes Epic's no-cost APIs and interface documentation, and Epic on FHIR is where you register an app, get non-production and production client IDs, and test against a sandbox.
- Vendor Services is the optional paid program: additional documentation, an expanded testing sandbox and access to Epic support.
- Showroom is the customer-facing catalog. Epic launched Connection Hub in it for vendors to list products that interoperate with Epic; Toolbox and Workshop are the more curated tiers.
App audience changes the path. Per Epic's OAuth 2.0 documentation, apps that meet its auto-sync criteria are distributed to customer environments once a client secret or public key is provisioned; in practice that covers patient-facing apps using the certified FHIR APIs. Clinician-facing and backend apps are configured and activated organization by organization, with the customer's analysts doing the build on their side. For backend JWTs, Epic's documentation names RS384 as the preferred algorithm. The startup-level view is in Epic FHIR for HealthTech startups.
Oracle Health (Cerner): Millennium FHIR R4 and code Console
Oracle documents the FHIR R4 APIs for Oracle Health Millennium Platform; the DSTU 2 APIs are no longer supported. You register apps in code Console, which requires a CernerCare account. The service root URLs include an open, unauthenticated read-only sandbox and a secure sandbox under the public tenant:
https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/
https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/
https://fhir-myrecord.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/
Going live is a customer action. In Oracle's FHIR application provisioning flow, you give the customer your application ID and client ID, the customer obtains its tenant ID and logs service requests to provision your app against it, and some production cases need an approval form. Self-service provisioning does not apply to shared-domain customers. How the two vendors differ in culture and tooling is in Epic vs Cerner.
athenahealth: athenaOne APIs and certified FHIR R4
athenahealth runs two API families on one platform, documented on its developer portal: the certified FHIR R4 APIs (mainly read and search, aligned with US Core and described in the athenahealth FHIR implementation guide) and the proprietary athenaOne REST APIs, scoped by practice under paths such as /v1/{practiceid}/. Scheduling, document posting and most write workflows live in the proprietary family. Distribution to practices goes through the athenahealth Marketplace partner program, and each practice still authorizes your app.
Other EHRs, briefly
MEDITECH offers Greenfield Workspace for testing against a real Expanse system with US Core FHIR R4 and scheduling APIs. NextGen runs a developer program with separate tracks for patient access, client-built apps and distributed vendor apps.
Project phases and what gates them
No credible public source gives a single duration for "an EHR integration", and anyone quoting one without knowing the site is guessing. What is predictable is the order of the gates:
| Phase | What happens | What gates it |
|---|---|---|
| Scoping | Data elements, direction, workflow trigger, path per use case | A named clinical or operational owner at the site |
| Vendor enrollment and security review | App registration, program membership if needed, customer security questionnaire, BAA | The customer's security and legal queues |
| Sandbox build | Code against vendor sandbox data | Your team only; usually the fastest phase |
| Site configuration | Client ID activation, interface build, user and scope setup | The customer's analysts and change calendar |
| Validation with the site | Testing on the customer's non-production environment with realistic data | Test patients, test users and clinician time |
| Go-live | Production credentials, cutover, first live messages | Change-control approval, downtime windows |
| Monitoring | Error queues, token failures, volume and latency alerts | An agreed support model with the site's interface team |
Pitfalls that appear after the sandbox
- Per-site configuration. Two hospitals on the same EHR version populate different fields, use different identifier systems and expose different scopes. Build an onboarding checklist per site, not per vendor.
- Patient matching. MRNs are local. Use the identifier system the site gives you, keep demographics for matching, and use
$matchonly where the server supports it. The master patient index guide covers the failure modes. - Write-back limits. Certified FHIR APIs guarantee reads. Writes exist for a subset of resources and often need extra approval; results and notes frequently go back over HL7 v2 instead.
- Rate limits. Vendors throttle, and not all publish numbers. Batch, cache and back off on
429. - Token lifetimes. Access tokens are short-lived and refresh tokens differ by app type and site policy. Under (g)(10), a certified EHR must issue confidential patient-access apps a refresh token valid for at least three months. That floor says nothing about clinician or backend apps.
- Sandbox vs production data. Sandbox patients are tidy. Production has merged records, missing codes, free-text results and local code systems. Budget validation time for that gap.
EMR vs EHR integration
The terms are used interchangeably in search and in contracts. The ONC's original distinction is that an EMR is the digital chart inside one practice, while an EHR is designed to share information beyond the organization that collected it. In integration work the difference shows up in what the system exposes: a small practice EMR may offer only a proprietary API or a document export, while a certified EHR must offer the FHIR R4 API described above.
Choosing a path
Start from the workflow. If a clinician needs your app inside the chart, use SMART on FHIR. If you need to react to admissions or results as they happen, ask for an HL7 v2 feed. If you need the whole record for a cohort, use bulk export. If the use case writes scheduling or billing data, expect the vendor's proprietary API and its partner program. Most production integrations combine two of these.
If you are planning one of these integrations and want a second pair of eyes on the path, the gates or the site checklist, see EHR and EMR integration services.