Look, I get it. You've been asked to build an integration with a hospital's EHR system, and you're staring at a wall of acronyms — FHIR, HL7 v2, CDA, CCDA, SMART on FHIR, ADT feeds — wondering where to even start. I've been there. We've built EHR integrations for health systems running Epic, Cerner (now Oracle Health), and MEDITECH, and I can tell you: the technology is actually the easy part. The hard part is navigating the ecosystem.
This guide is what I wish someone had handed me before our first EHR integration project. No vendor fluff, no architecture astronaut diagrams — just the practical stuff that determines whether your integration goes live or dies in a sandbox.
The EHR Landscape in 2026
Before we get into code, let's ground ourselves in reality. Three EHR vendors dominate the U.S. market:
| Vendor | Market Share (Acute Care) | Primary API Standard | Certification Program |
|---|---|---|---|
| Epic | ~38% | FHIR R4, HL7 v2 | Epic App Orchard / Showroom |
| Oracle Health (Cerner) | ~25% | FHIR R4, HL7 v2 | Oracle Health Marketplace |
| MEDITECH | ~16% | FHIR R4 (Expanse), HL7 v2 | MEDITECH Greenfield |
The remaining ~21% is fragmented across Allscripts, athenahealth, eClinicalWorks, and dozens of smaller players. If you're building a product that needs to work across health systems, you're almost certainly integrating with at least two of the Big Three.
At Of Ash and Fire, we're an Epic-certified integration partner, which means we've been through their technical review process and can deploy through Epic's App Orchard (now Showroom). I mention this not to brag, but because the certification process taught us things about EHR integration that you can't learn from documentation alone.
FHIR vs HL7 v2: Which One Are You Actually Using?
Here's the thing nobody tells you upfront: most production EHR integrations in 2026 still use HL7 v2 messages for real-time data flows. FHIR gets all the press — and rightly so, it's the future — but the reality on the ground is messier.
When You'll Use FHIR R4
- Patient-facing apps (patient portals, mobile health apps)
- Clinical decision support tools embedded in the EHR workflow
- Population health queries and bulk data export
- New integrations where the health system's IT team is forward-thinking
- 21st Century Cures Act compliance (patient access APIs)
When You'll Still Use HL7 v2
- ADT feeds (Admit/Discharge/Transfer notifications)
- Lab results (ORU messages)
- Order entry (ORM messages)
- Legacy integrations with ancillary systems
- Real-time, event-driven workflows where the hospital already has HL7 v2 interfaces running
The Hybrid Reality
Most of our projects use both. A typical integration might pull patient demographics via FHIR, subscribe to ADT events via HL7 v2, and write clinical notes back via FHIR's DocumentReference resource. Accept the hybrid reality early and architect for it.
SMART on FHIR Authentication: The Part That Trips Everyone Up
I can't tell you how many times I've seen development teams nail the FHIR queries but completely fumble authentication. SMART on FHIR is an OAuth2-based authorization framework specifically designed for healthcare apps, and it has quirks that will bite you if you're used to standard OAuth flows.
The Two Launch Contexts
EHR Launch — Your app is launched from within the EHR (embedded in Epic's sidebar, for example). The EHR passes you a launch context with the patient ID, practitioner ID, and encounter ID already set.
Standalone Launch — Your app runs independently and needs to authenticate against the EHR's authorization server. You get to pick the patient after authentication.
Common Authentication Pitfalls
1. Token expiration handling. EHR access tokens typically expire in 5-10 minutes. If your app makes a FHIR call with an expired token, you get a 401 — and if you don't handle refresh tokens correctly, the user has to re-launch your app from the EHR. Implement proactive token refresh before expiration.
2. Scope mismatches. You request scopes like patient/Observation.read and patient/MedicationRequest.read, but each EHR supports different scope syntax. Epic uses patient/Observation.rs (read + search) while Cerner uses patient/Observation.read. Test against each vendor's sandbox.
3. PKCE is mandatory. Every SMART on FHIR implementation in 2026 requires PKCE (Proof Key for Code Exchange). If your OAuth library doesn't support PKCE natively, you need to generate the code_verifier and code_challenge yourself.
4. Ignoring the fhirContext in token response. After the token exchange, the response includes context about the current patient and encounter. Don't ignore this — it's how you know which patient the clinician is looking at when they launched your app.
Vendor-Specific Gotchas
Epic
- Sandbox access requires registering through Epic's Showroom (formerly App Orchard). Budget 2-4 weeks for approval.
- Production deployment requires a full technical review. Epic will test your app against their security and usability standards. This process takes 4-8 weeks on average.
- MyChart integration (patient-facing) has separate requirements from Hyperspace integration (clinician-facing).
- Bulk FHIR export uses Epic's proprietary backend services endpoint, not the standard FHIR Bulk Data Access spec. Close, but not identical.
Oracle Health (Cerner)
- Ignite APIs are Cerner's FHIR implementation. They're solid but have some extensions that differ from standard FHIR R4.
- Millennium vs Expanse — make sure you know which platform your target health system is running. The API capabilities differ.
- Webhook support for real-time events is more mature than Epic's subscription model in some cases.
MEDITECH
- Expanse (their modern platform) has decent FHIR R4 support. Older MEDITECH versions (6.x and below) are HL7 v2 only.
- Integration testing requires working directly with the health system's IT team — MEDITECH doesn't have a public developer sandbox.
- Documentation is less comprehensive than Epic or Cerner. Plan for more discovery time.
Building the Integration Layer
Here's the architecture pattern we use for most EHR integration projects at Of Ash and Fire:
Key Design Decisions
1. Never talk to the EHR directly from your frontend. All EHR communication goes through your backend integration service. This gives you a place to handle token management, data transformation, error recovery, and audit logging.
2. Use a message queue for HL7 v2. HL7 v2 messages arrive over TCP (MLLP protocol) and need acknowledgment within seconds. If your processing logic is slow, you'll drop messages. Accept the message, ACK it, put it on a queue, and process asynchronously.
3. Build vendor-agnostic data models internally. Your app should have its own patient, encounter, and observation models. Map EHR-specific FHIR resources to your internal models in the integration layer. This way, supporting a second EHR vendor doesn't require rewriting your entire application.
4. Implement circuit breakers. EHR APIs go down for maintenance. When they do, your integration should fail gracefully — queue requests, alert your ops team, and resume when the API comes back. Don't let an EHR outage crash your entire application.
HIPAA Considerations for EHR Integrations
Every piece of data flowing through your integration is Protected Health Information (PHI). The 2026 HIPAA Security Rule updates make this even more critical:
- Encrypt everything in transit — TLS 1.3 minimum for FHIR calls, TLS for MLLP connections
- Encrypt at rest — AES-256 for any PHI stored in your database or cache
- Audit log every access — Who accessed what patient data, when, and why
- Minimum necessary — Only request FHIR scopes you actually need. Don't pull the entire patient record if you only need medications.
- BAA (Business Associate Agreement) — You need one with every health system you integrate with. Your legal team should have a template ready.
For a deeper dive into HIPAA technical requirements for medical app development, we've written a separate guide.
Timeline and Cost Expectations
Here's what a typical EHR integration project looks like at our shop:
| Phase | Duration | What Happens |
|---|---|---|
| Discovery & Scoping | 2-3 weeks | Identify data flows, map FHIR resources, define scope |
| Sandbox Development | 6-10 weeks | Build integration against vendor sandbox |
| Security Review | 2-4 weeks | Vendor security questionnaire, penetration testing |
| Vendor Certification | 4-8 weeks | Epic Showroom review, Cerner marketplace review |
| Health System Testing | 2-4 weeks | Test against the actual health system's EHR instance |
| Go-Live & Monitoring | 1-2 weeks | Deploy, monitor, tune |
Total timeline: 4-7 months for a single-vendor integration. Add 2-3 months for each additional vendor.
Cost range: $80-250K depending on complexity. Simple read-only integrations (pulling patient data) are on the low end. Bi-directional integrations with clinical workflows are on the high end.
The Certification Process Is Not Optional
If you're building a product (not a one-off interface for a single hospital), you need vendor certification. Epic won't let a health system deploy your app in production without Showroom certification. Cerner has similar requirements through their marketplace.
The certification process tests:
- Security — OAuth implementation, data encryption, vulnerability scanning
- Usability — Your app must meet the vendor's UX guidelines for embedded apps
- Performance — Response times, error handling, graceful degradation
- Compliance — HIPAA, 21st Century Cures Act, information blocking rules
We've been through this process multiple times as a certified Epic integration partner, and the biggest lesson I can share is: start the certification process early. Don't wait until your app is "done." Submit for review as soon as your core flows work in the sandbox.
Getting Started
If you're planning an EHR integration project, here's my honest advice:
-
Talk to the health system's IT team first. They'll tell you which interfaces they already support, what data they can expose, and what their review process looks like. This conversation saves months of guesswork.
-
Start with FHIR R4. Even if you end up needing HL7 v2 for some data flows, FHIR is the foundation for all new development. Build your FHIR client first.
-
Budget for the non-coding work. Certification, security reviews, BAAs, and health system testing consume 30-40% of most EHR integration projects. Don't quote just the development time.
-
Work with a team that's done it before. EHR integrations have a steep learning curve. The vendor documentation covers the API — it doesn't cover the institutional processes, the edge cases in real patient data, or the certification gotchas.
We build healthcare software that integrates with the systems clinicians actually use. If you're planning an EHR integration and want to talk through architecture, timelines, or certification strategy, reach out. No pitch — just a practical conversation about what your project actually needs.