Epic FHIR API Integration: What the Sandbox Doesn’t Tell You
Key Takeaways
- Epic’s sandbox is free and generous along with 750+ no-cost APIs and USCDI v3 data which is exactly why it misleads you. Test patients are clean, complete and consistent in ways no real chart ever is.
- Epic supports FHIR R4 for new work, but STU3 and DSTU2 are still live in the wild, so “the hospital runs Epic” tells you almost nothing about which resources you will actually get.
- App Orchard is gone. Registration, OAuth 2.0 client IDs and sandbox access now live in Epic Connection Hub; Showroom is the customer-facing gallery where health systems find “Integration Ready” apps.
- SMART on FHIR v2.2.0 settles authorization and launch context. It does not settle whose patient is selected, which department context applies, or what happens when a clinician launches your app from the wrong workspace.
- Your schedule is not set by Epic. It is set by each customer hospital’s IT queue, and every new customer is a fresh security review, a fresh build request and a fresh go-live.
Every Epic FHIR API guide stops at the same place. You registered an app, you got a token back from the sandbox, you pulled a Patient resource, and the tutorial declares victory. Then you connect to a real health system and discover that the interesting part has not started yet.
The gap between a working sandbox call and a working production integration is where most of the budget goes, and almost nobody writes about it. Practitioners we talked to are very blunt about this. One developer specifically warned that the Epic sandbox can give you “false confidence.” A patient-monitoring vendor explained the difference more simply. With most other EMR vendors, you get a few technical contacts, connect the systems, test them, and go live. However, Epic does not work that way.
This guide is written for teams who already know how to integrate EHR into healthcare apps in the general case and now need the Epic specifics. It assumes you have read Epic’s documentation and want to know what the documentation does not tell you.
If you are still deciding which EHR to build against first, the Epic vs Cerner comparison is the earlier decision.
What Does the Epic FHIR API Actually Give You?
Epic on FHIR is Epic’s public developer program, and it is genuinely free. There is no registration fee or sandbox fee. Epic also reports more than 750 free APIs covering the USCDI v3 data set, with a stated commitment to supporting USCDI v5. Epic’s public APIs carry roughly 311 billion web service transactions a year, so this is not a token gesture toward interoperability.
What the marketing does not foreground is the shape of the access.
Read is broad, write is narrow. You can search and read Patient, Observation, Encounter, Condition, MedicationRequest, DocumentReference and dozens more. Writing back is a different conversation. It needs a smaller set of resources, tighter scopes, and in many cases a per-customer decision rather than a platform capability. Design assuming that you will read far more than you write.
Three FHIR versions are live at once. R4 is where new development belongs and where Epic’s coverage is deepest. STU3 and DSTU2 remain supported because real hospitals are still on them. The difference between HL7 v2 and FHIR gets all the attention, but the version spread inside FHIR causes more day-to-day pain, because it stays invisible until you hit a customer who does not have the resource you built against.
Patient-facing and provider-facing are different products. Patient-facing apps work on federal API access requirements and clear the lowest bar. On the other hand, provider-facing and backend integrations go through more scrutiny and can involve vendor program participation. Decide which one you are before you design anything, because the answer changes your auth model, your review path and also your commercial terms.
Why the Epic FHIR Sandbox Gives You False Confidence
The sandbox does what it is designed to do. It helps to prove that your OAuth flow works and your parser handles well formed resources. The problem is that developers read a green test run as evidence that the integration works. But the sandbox does not show many of the issues that can cause problems in a real production environment.
| What the sandbox shows you | What production does instead |
|---|---|
| Test patients with tidy, complete demographics | Duplicate MRNs, missing fields, patients merged across facilities, names that break your validation |
| A consistent, current resource set | Whatever that customer’s Epic version and build actually expose, which may be less |
| Instant token issuance, no gatekeeper | A security review, a signed agreement, and a build request in someone else’s queue |
| Predictable, small result sets | Charts with thousands of Observations, pagination you did not plan for, and timeouts |
| One environment, one configuration | Per-customer configuration, per-customer endpoints, per-customer surprises |
| Clean coded values | Local codes, free text where you expected structure, and terminology that maps imperfectly |
The most expensive line in that table is the last one. FHIR standardizes the envelope, not the contents. Two hospitals can both return a perfectly valid Observation resource and populate it in ways that force you to write different handling for each. A vendor integration engineer described the tax precisely which is about 80% and is the same between vendors, and the remaining 20% needs conditionals, and it never feels finished.
Budget for the 20% as engineering work, not as a bug backlog. This is the single most common reason an Epic FHIR API integration ships late.
Why Version Fragmentation Breaks Epic FHIR API Assumptions
Sandbox proof of concept usually takes up a few weeks. Production hardening runs considerably longer. For the first customer activation is dominated by their security review and validation window, and not by your engineering. Later customers can be onboarded faster, but the process will still take some time.
Why Version Fragmentation Breaks Epic FHIR API Assumptions
There is a question that comes up on r/healthIT constantly, in some form. If two hospitals are both on Epic, so why do they still fax each other?
Because “runs Epic” is not a specification. Each health system runs its own Epic version on its own upgrade cycle, with its own build. It has its own configured fields, its own local codes, its own security rules about which data leaves the system and under what consent. Epic is the platform whereas the build is the product, and the build is different everywhere.
For your integration this has three consequences:
- You cannot write one integration and resell it unchanged. You can write one core and expect per-customer configuration.
- Resource availability is a per-customer fact. Confirm which resources and versions a specific customer exposes before you promise a feature that depends on them.
- An upgrade at the customer can change your behaviour. New fields appear, coded values shift, and nobody tells you in advance.
Teams that treat the first Epic customer as the template and the second as a copy-paste are the ones who end up rewriting. Treat customer one as a prototype for your configuration layer instead. It is the same discipline that governs medical device integration with EHR, where per-site variance is assumed rather than finding it later.
What SMART on FHIR Fixes in an Epic Integration, and What It Doesn't
SMART App Launch, currently v2.2.0 from HL7, is a genuinely good specification, and Epic implements it properly. It defines two launch patterns, and the distinction matters more than most teams realize.
EHR launch starts your app from inside Epic. The user is already authenticated, already has a patient open, and your app receives that launch context. Standalone launch starts outside Epic, and the user picks context at launch time.
The spec handles the hard security problem cleanly. The authorization codes are exchanged for access tokens over OAuth 2.0, with scopes that spell out exactly what you may touch, for example, user/Encounter.rs for what an authorized user can read, system/Encounter.rs for backend services with no user in the loop. Read the SMART App Launch specification directly rather than a summary of it since the scope grammar rewards attention.
What SMART does not solve is workflow. A developer on r/healthIT has captured it exactly.SMART technically solves the token and auth problem, but clinical workflow integration is still hard because every system interprets patient context differently.
Concretely, the questions SMART hands back to you are:
- What happens when the clinician launches your app with no patient in context?
- What if the encounter context is present but stale, or points at a different department?
- Does your app need the user’s identity, the patient’s, the organization’s, or all three?
- What does your app do when a scope you requested was not granted. Does it degrade, or refuses to load?
Answer the above questions in design. Finding these problems during the customer’s validation period can turn a two-week go-live into a two-month process.
How Do You Get an Epic FHIR App Into Production?
These are build effort ranges for a focused team, not Epic fees, and they consider the app is already built and only the integration is in question. The line that surprises people is the last one. For every customer cost stays meaningfully above zero forever. Any business case that assumes marginal cost approaches zero after customer three has not modelled the security reviews.
Most budget overruns come from the same problem we see in the general EHR integration budget. The estimate covers the coding work but leaves out things like terminology mapping, per customer differences, and the time spent waiting for the same..
Epic FHIR API Integration Mistakes That Cost a Release Cycle
- Treating sandbox success as integration success. The sandbox validates your client. It says nothing about a customer’s build.
- Hard-coding a single endpoint and FHIR version. Works for customer one, breaks on customer two, and the fix is architectural.
- Assuming coded values are consistent. Local codes and free text in structured fields are normal, not exceptional. Build the mapping layer up front.
- Designing for write access you will not get. Confirm write scopes per customer before a feature depends on them.
- Ignoring launch context edge cases. No patient selected, stale encounter, wrong department, partially granted scopes: all of these reach production.
- Forgetting that PHI in logs is still PHI. Debug logging that captures request and response bodies during a go-live is a breach waiting to be found. This is standard HIPAA-compliant software development discipline and it gets skipped under go-live pressure more than any other control.
- Modelling one review and repeating it mentally. Every customer’s security review is new, and their timeline is theirs.
None of this makes Epic FHIR API integration a bad investment. Epic is used by a large share of US patients, and an app that works inside those systems is worth building. It just is not the project the sandbox makes it look like. Treat it as healthcare software development work with a configuration layer, a terminology map and a customer onboarding runbook, rather than as an API client with a token. Then, the second customer will cost a fraction of what the first one did.
Frequently Asked Questions
Epic on FHIR is Epic's free public developer program at fhir.epic.com. It provides API specifications, a testing sandbox with example patient data, and the registration path for apps that will connect to Epic running health systems. Registration and sandbox use carry no charge.
Yes, there is. Epic exposes over 750 no-cost public APIs built on HL7 FHIR, covering the USCDI v3 data set. The APIs and sandbox are free. Provider facing and backend integrations may involve vendor program participation costs, which Epic quotes directly. Patient facing apps generally face less barriers because federal rules require that access.
Two things have replaced Epic App Orchard.. First is Epic Connection Hub that handles the technical side. This includes product registration, OAuth 2.0 client IDs and sandbox access. Second is Epic Showroom which includes the customer facing gallery where health systems discover apps marked "Integration Ready." Any guide still routing you to App Orchard is out of date.
R4 is the current standard and should be the target for new development. STU3 and DSTU2 are still supported because some health systems continue to use them. The version available can vary by customer, so check with each organisation instead of making assumptions.
Each health system runs its own Epic version, upgrade cycle and build, with its own configured fields, local codes and has data sharing rules. The platform is shared, however, the configuration is not. That is also why an integration built for one Epic customer needs configuration work for the next.
Sandbox proof of concept typically takes a few weeks. Production hardening runs considerably longer. The first customer activation is dominated by their security review and validation window rather than by your engineering. Subsequent customers get faster but never become instant.
