5 Hard Lessons from Building Epic FHIR Integrations
Epic dominates the US EHR market, covering over 305 million patient records. If you are building a digital health product, you will eventually integrate with Epic. Their FHIR API surface is broad and improving, but the gap between "it works in the sandbox" and "it's live at a health system" is where projects die.
Here are five lessons learned the hard way.
Lesson 1: The Sandbox Will Lie to You
Epic provides a public FHIR sandbox at fhir.epic.com. It is free, well-documented, and will give you false confidence. Here is why:
OID/MRN System Differences: In the sandbox, you can search patients using a specific OID system value like urn:oid:1.2.840.114350.1.13.0.1.7.5.737384.14. That OID will be different at every production site. Every health system has its own MRN system, and you need to discover it per-site.
Sparse Documentation and Periodic Resets: The sandbox is a great starting point, but developers frequently hit friction with sparse documentation and periodic environment resets that force you to rebuild test cases. Your carefully constructed test patient with the right combination of conditions, meds, and allergies? Gone after a reset.
Client ID Delays: If you register a new application and try to access the sandbox the same day, it might not work. Epic updates its client ID list nightly. Give it 24 hours. This is not mentioned prominently in the docs.
The Real Solution: Get access to a customer-specific test environment as early as possible. Reach out to health system partners and ask for their non-production sandbox. The earlier you test against real-world data patterns, the fewer surprises you will face in production.
Lesson 2: App Orchard Is a Gatekeeper, Not a Store
Epic's application marketplace (formerly App Orchard, now transitioning to Showroom via Connection Hub) is the gateway for third-party applications. Getting listed is not about distribution — it is about access and trust.
The Process
- Register as a vendor with Epic Vendor Services. This requires a membership agreement and often involves fees for proprietary API access.
- Develop against the sandbox. Build your integration, document your scope requests, and prepare for review.
- Submit for technical review. Epic's team evaluates your API usage, security posture, and scope justification. Simple read-only FHIR apps clear in weeks. Bidirectional integrations touching clinical workflows take months.
- Get listed in Connection Hub. Now health systems can discover and enable your app.
- Per-site activation. Each health system must individually enable your application, configure it, and often run their own security assessment.
What Surprises Teams
Per-site approval cycles repeat. Even after you are listed and certified, every new health system customer requires its own approval and configuration. Scaling from 1 health system to 10 means repeating validation steps, with each system's IT security team asking their own questions.
Proprietary APIs require Vendor Services membership. Standard FHIR APIs (R4, US Core) are available without a paid membership. But if you need Epic-specific functionality — certain write operations, CDS Hooks integrations, or real-time subscriptions — you need a Vendor Services agreement, which comes with costs and additional review.
Timeline expectation vs reality:
| Integration Type | Expected | Actual |
|---|---|---|
| Read-only FHIR app | 2-4 weeks | 4-8 weeks |
| Bidirectional clinical | 2-3 months | 6-14 months |
| Enterprise multi-site | 6 months | 12-18 months |
Lesson 3: Token Management Is Where the Devils Live
SMART on FHIR auth with Epic follows standard OAuth 2.0, but the operational details create headaches:
Short-lived access tokens. Epic access tokens typically expire in 5-15 minutes in production. Your application must implement robust token refresh logic. Proactive refresh (refreshing when the token has less than 2 minutes remaining rather than waiting for a 401) prevents API call failures.
Per-site client registration. Your sandbox client ID will not work in production. Each Epic customer site issues its own client credentials. If you have 5 health system customers, you manage 5 sets of credentials plus your sandbox credentials.
PKCE is mandatory. Use Authorization Code flow with PKCE for all user-facing applications. The implicit flow is deprecated and Epic will reject it.
Backend services auth uses asymmetric keys. For system-to-system integrations, you register a public key with Epic and sign JWT assertions with your private key. Key rotation and secure storage are your responsibility.
Token Management Checklist
- Use OS keystores or secrets managers for credential storage
- Implement proactive token refresh (before expiry, not after 401)
- Register separate client IDs per environment and per health system
- Implement exponential backoff for auth server errors
- Log token refresh failures with enough context to debug without exposing secrets
Lesson 4: USCDI Versions Create a Moving Target
The United States Core Data for Interoperability (USCDI) defines the minimum dataset EHRs must expose via FHIR. But there is a lag between what the federal government mandates and what any given Epic site actually supports.
USCDI version support depends on Epic release: USCDI v4 APIs are supported starting with the August 2024 Epic release. Earlier releases may only expose USCDI v1. ONC finalized USCDI v5 (allowed via SVAP 2025), but many sites are still running older versions.
What this means for your app: You cannot assume that every Epic site exposes the same data elements. A social determinants of health assessment might be available at one health system and absent at another, depending on their Epic version and USCDI compliance level.
The practical approach:
- Build your app against the USCDI v1 baseline — this is the floor that every certified EHR must support
- Detect available data via the CapabilityStatement
- Gracefully degrade when optional USCDI v3/v4 elements are not available
- Document per-site data availability for your implementation team
Lesson 5: Budget for the Long Tail
Most teams budget for the integration build. Few budget for what comes after.
Per-site deployment costs are real. Each health system requires configuration, testing, security review, and go-live support. Budget 2-4 weeks of engineering time per new health system deployment, not just the initial build.
Epic version upgrades break things. Epic releases updates quarterly. Each update can change API behavior, add new required scopes, or deprecate endpoints. You need a regression testing strategy and someone monitoring Epic's release notes.
Support overhead scales with sites. When you have 3 health system customers, support is manageable. At 15, you need dedicated integration support staff. Data mapping issues, auth token failures, and site-specific configuration bugs become a constant stream.
Cost benchmarks from the field:
| Phase | Cost Range |
|---|---|
| Initial integration build | $50K - $150K |
| App Orchard listing + review | $10K - $30K |
| Per-site deployment | $15K - $50K each |
| Annual maintenance | $30K - $80K |
| Enterprise scale (10+ sites) | $300K - $500K total first year |
The Bottom Line
Epic FHIR integration is achievable, but it requires respecting the complexity. Start testing against real customer environments early. Budget for per-site deployment costs. Build robust token management from day one. And plan for the reality that what works at one health system may not work identically at another.
Building an Epic integration or scaling an existing one? 1Putt Health has deep experience with Epic FHIR APIs, App Orchard/Showroom, and multi-site deployments. Book a Discovery Call to get a realistic assessment of your integration timeline and effort.