Epic FHIR API Complete Guide — What Developers Actually Need to Know

Epic powers a majority of large US hospitals. If you're building anything in US healthcare that needs clinical data, sooner or later you'll integrate with Epic. The Epic FHIR API is the modern way to do that — but the documentation is scattered, the access process is bureaucratic, and the real-world implementation has more gotchas than the official guides admit.

This article walks through what the Epic FHIR API actually is, how to get access, what you can do with it, what you can't, what it costs, and how it compares to traditional HL7 v2 integrations with Epic. Written for developers and product leads who need real answers, not marketing. Backed by the engineers who deliver Mirth Connect support for US healthcare organizations.

Epic provides a FHIR R4 implementation conforming (more or less) to US Core. Through it, you can read clinical data — patients, encounters, observations, conditions, medications, allergies, and many other resources — programmatically, with proper authorization.

Some important things to understand up front:

• It's primarily read-only for most use cases. Write operations exist for some resources (Appointment, AllergyIntolerance, ServiceRequest in some contexts) but most Epic FHIR integration is one-way: out of Epic, into your application.
• Each Epic customer hosts their own endpoint.There's no “Epic FHIR endpoint” you connect to once. Every Epic-using organization (each hospital system, each clinic) has its own Epic instance and its own FHIR endpoint URL. Your application has to handle this multiplicity.
• The customer organization controls access.Even after Epic approves your app or integration, each specific Epic customer has to enable it on their instance. Multi-tenant access doesn't come automatically.
• Coverage varies by Epic version. Epic customers run different versions of the platform. Newer FHIR resources and operations may not be available on older versions until those customers upgrade.

Epic has two distinct developer programs for FHIR integration. The naming has changed over the years, but the two flavors persist.

Epic on FHIR is for patient-facing or clinician-facing applicationsthat launch within the Epic context — typically SMART on FHIR apps that launch from MyChart (patient-facing) or from Hyperspace/Haiku/Canto (clinician-facing). These apps run inside an Epic-provided context, get a launched OAuth token, and operate within the user's session.

Connection Hub (formerly Showroom, formerly Toolbox parts of the same program, and before that part of App Orchard) is for system-to-system integrations— backend services that need to read Epic data without a user-in-the-loop launch. Examples: a population health platform pulling daily Patient and Condition data, an analytics service ingesting Observation data, a third-party tool that needs ongoing access to a specific organization's clinical data.

Choose Epic on FHIR when:you're building an app users will launch from within Epic.

Choose Connection Hub when:you're building backend integration that runs server-to-server.

Some products use both — a SMART app for the user-facing component, a Connection Hub integration for the backend data flow. That's fine, but it's two separate registrations and two separate auth flows.

Names and program details change. Verify the current program names and policies on Epic's developer portal before publishing any architecture decisions. For deeper context on the Bridges/App Orchard heritage, see our Epic integration via Bridges and App Orchard post.

The high-level process for either flavor:

1. Register on Epic's developer portal. Create a developer account at fhir.epic.com (or the current developer portal URL). This is free.
2. Register your application.Provide application details — name, description, technical contacts, what FHIR resources you need, what scopes you need, redirect URIs (for SMART apps), and the auth flow you'll use.
3. Develop against the sandbox.Use Epic's public sandbox to build and test your integration. Sandbox access is generally available with developer account registration.
4. Pass Epic's review. For Connection Hub integrations and some Epic on FHIR apps, Epic reviews the application before it can be installed in production environments. The review covers technical conformance, security posture, and clinical workflow appropriateness.
5. Get installed at a specific Epic customer.Once approved by Epic, you still need each individual Epic-using organization that wants to use your app to enable it on their instance. This is typically handled by the customer's Epic technical team, not by Epic directly.

Timeline reality check:Steps 1–3 (sandbox development) can move quickly. Step 4 (Epic review) historically takes weeks to months. Step 5 (customer enablement) depends entirely on the customer organization's internal change management and can take additional weeks to months. Plan accordingly. End-to-end from “first line of code” to “running in production at the first customer” is often 6–12 months for backend integrations.

Epic uses SMART on FHIR for authentication, with some Epic-specific flavor.

For Epic on FHIR (user-facing apps):EHR Launch and Standalone Launch flows from the SMART App Launch Framework. The user's session inside Epic provides context (patient, encounter, user) that gets passed to your app.

For Connection Hub (backend integrations): SMART Backend Services flow — JWT-based authentication using a public/private key pair you register with Epic. No user-in-the-loop; the integration authenticates as itself.

Epic-specific notes:

• Epic supports both V1 and V2 of the SMART App Launch Framework. V2 is the current standard; use it for new integrations.
• Epic's OAuth implementation has historically had quirks around scope handling. Test your scope requests carefully against the Epic sandbox before assuming behavior.
• For backend services, Epic uses asymmetric (JWT) client authentication. Generate your key pair, register the public key with Epic, and sign JWTs with your private key for token requests.
• Tokens expire. Build refresh logic from day one. SMART user-launch tokens are typically short-lived; backend service tokens have configurable lifetimes.
• Production tokens are issued by each Epic customer's instance, not by a central Epic auth server. Your application has to handle multiple OAuth issuers.

Sample backend service token request structure (illustrative — verify against current Epic docs):

POST {epic_customer_token_endpoint}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={signed_jwt}

The JWT payload includes iss (your client ID), sub (your client ID), aud (Epic's token endpoint), jti (unique token ID), and exp (expiration timestamp).

Epic's FHIR R4 implementation covers most of US Core. Available resources typically include:

Well-supported resources:

• Patient
• Encounter
• Observation (laboratory and vital signs categories especially)
• Condition
• MedicationRequest
• MedicationStatement
• AllergyIntolerance
• Immunization
• Procedure
• DocumentReference
• DiagnosticReport
• CarePlan
• CareTeam
• Goal
• Practitioner
• PractitionerRole
• Location
• Organization

Partially supported or version-dependent resources:

• Appointment (read commonly available; write more limited)
• Coverage (insurance data — coverage varies)
• Claim and ExplanationOfBenefit (billing data — limited)
• Communication (notes/messages)
• ImagingStudy (radiology — varies)
• Specimen (lab specimen detail — varies)

Resources that often aren't available or are limited:

• Most administrative/financial resources beyond basic Coverage
• Detailed audit logs (AuditEvent)
• Many of the workflow-state resources
• Full bidirectional write support for clinical resources

Important:resource availability varies meaningfully by Epic version and by customer configuration. The same resource type may behave differently across two Epic customers. Don't assume; test against each specific customer's endpoint during onboarding.

The full current resource list is published on Epic's developer portal. Pull it directly when planning a specific integration. For the broader v2-to-R4 translation patterns that come into play when bridging legacy HL7 traffic into FHIR, see our HL7 v2 to FHIR R4 mapping reference.

Epic enforces rate limits on FHIR API calls. The specific limits depend on the customer's Epic configuration, your integration's negotiated quota, and the type of operation.

General guidance:

• Single-resource reads are usually generous. You can typically pull individual Patient or Observation resources at reasonable rates without hitting limits.
• Search operations can be more restricted, especially broad searches without specific patient identifiers. Operations that scan large data sets are throttled aggressively.
• Bulk Data Export has its own quota mechanism (see next section).
• Aggregate quotas — total calls per day or per hour — exist and vary by customer.

If you hit a rate limit, Epic returns an HTTP 429 with a Retry-After header. Respect it. Build exponential backoff into your client.

Practical advice:during early integration testing with a real customer, profile your actual call volume against their quotas before going to full production. We've seen integrations that worked fine in sandbox hit aggregate quota issues within hours of production deployment because the real call volume was 10× the test volume.

Epic provides a public sandbox at fhir.epic.com (or the current sandbox URL) with synthetic test patients. Use it heavily during development.

What sandbox tells you well:

• API surface and response shapes
• Authentication flow
• Resource structure
• Basic happy-path behavior

What sandbox doesn't tell you:

• Real customer rate limits
• How a specific customer's Epic configuration affects available data
• Edge cases in real-world clinical data (NULL values, unexpected codes, malformed-but-valid responses)
• Performance under real volume
• Behavior across Epic version differences

Onboarding to a real customer is itself a phased process. Most teams do:

1. Build and test entirely in sandbox.
2. Get connected to one pilot Epic customer's non-production environment.
3. Test against the customer's real (non-production) data.
4. Move to the customer's production environment after validation.

Skipping the customer's non-production step is a common mistake. Real data behaves differently from sandbox data in ways that only show up at scale.

For population-level data extraction, Epic supports the FHIR Bulk Data Access IG. This is how you efficiently pull large data sets — for example, every Patient and their related resources for an entire health system.

The flow:

1. Kick off an export with $export on the Patient or Group endpoint
2. Poll the operation status endpoint until the export completes
3. Download the resulting NDJSON files from the URLs Epic provides

Epic-specific bulk export notes:

• Bulk exports can take hours for large populations. Don't expect synchronous response.
• Quotas exist on bulk operations. Negotiate them during onboarding.
• The resources included in the export are configurable per customer.
• Output is NDJSON (newline-delimited JSON), one resource per line. Use streaming parsers — don't load full files into memory.
• Errors mid-export are common in real-world data. Build your ingestion to handle partial results and retry logic.

We've written a separate FHIR Bulk Data Implementation Guide that covers the IG in detail.

Five Epic FHIR use cases that are well-trodden and ship reliably:

• Patient access apps (SMART on FHIR).A patient-facing app that launches from MyChart, reads the patient's own data, and presents it in a custom UI. Well-trodden path with strong Epic support.
• Clinician-facing decision support apps. A SMART app that launches from Epic during patient care, reads relevant clinical data, applies decision logic, and presents recommendations to the clinician. Also well-supported.
• Population health data ingestion. A backend service that pulls Patient and Condition data for a defined population on a regular schedule. Works well with Bulk Data Export.
• Quality measure calculation. Reading Encounter, Condition, Observation, and Procedure data to calculate clinical quality measures. Generally works well within Epic FHIR limits.
• Patient outreach and engagement. Reading patient demographics and contact info to drive engagement campaigns. Simple, works well.

Five Epic FHIR use cases that consistently surprise teams in negative ways:

• Real-time clinical events. Epic FHIR API is a request-response API, not an event stream. If you need notification when something changes in Epic (a new admission, a new lab result), polling is your default option. FHIR Subscriptions are emerging but not yet widely deployed in Epic environments. For real-time use cases, HL7 v2 message subscription often remains the more practical path.
• Bidirectional clinical workflows.Reading from Epic is well-supported. Writing back to Epic in clinically meaningful ways (creating orders, documenting notes, updating problem lists) is much more constrained. Many “we'll just write back to Epic” integration designs run into limits that weren't apparent during planning.
• Large-scale historical data extraction. Bulk export works, but extracting years of historical data for a large population takes substantial time and is subject to quota constraints. Plan for a multi-week initial sync, not a one-day load.
• Cross-customer data aggregation.If your application aggregates data across multiple Epic customers, you're managing multiple FHIR endpoints, multiple OAuth flows, and multiple customer-specific configurations. The complexity scales linearly with customer count.
• Custom data fields.Epic supports a lot of customization that customers use heavily. If your customer has built custom workflows, those customizations may not be exposed through standard FHIR resources. Custom extensions exist but aren't standardized across customers.

Cost has several components that catch teams off-guard.

• Epic program fees. Connection Hub registration and Epic on FHIR app participation have fee structures published by Epic. These have changed over time and vary by program tier. Expect this to be a non-trivial line item — not free.
• Per-customer onboarding cost.Each Epic customer enabling your integration involves their internal Epic team's time, which they may or may not pass through as a fee. Even if no direct fee, there's calendar time and coordination cost.
• Your engineering time. Realistically, a production-grade Epic FHIR integration takes a senior engineer 3–6 months to build and stabilize. Cross-customer onboarding adds ongoing engineering time per customer.
• Ongoing maintenance. Epic releases new versions. Customers upgrade on different cadences. Your integration has to handle the version variation. Plan for ongoing maintenance work proportional to your customer count.
• Compliance and security overhead. HIPAA, BAAs with each Epic customer, security reviews, penetration tests — all real costs that scale with integration scope.

For a project-specific estimate, run our pricing calculatorand pick “EHR integration” with Epic selected. The numbers reflect what these projects actually cost.

Epic supports both FHIR and HL7 v2 integration. Choosing well matters.

Choose FHIR when:

• You're building a user-facing app that needs SMART launch context
• You're doing population-level data extraction (bulk export shines here)
• You need REST API semantics for your application architecture
• You're new to healthcare integration and want the more modern, better-documented path
• You need to support multiple Epic customers across many organizations

Choose HL7 v2 when:

• You need real-time event notification (ADT events, ORU results) — HL7 v2 subscription delivers events as they happen, not on polling
• You need to write data back to Epic (orders, results) — HL7 v2 has more mature bidirectional support
• You're integrating with on-premise systems where MLLP fits the existing infrastructure
• Your downstream consumers expect HL7 v2 format

Hybrid is common. Many real-world Epic integrations use HL7 v2 for real-time event flow and FHIR for query-based data access. We've built several integrations exactly this way. The integration engine (Mirth Connect) sits between Epic and your downstream systems, handling both protocols. See how to build an HL7 interface in Mirth Connect for the channel structure that anchors this pattern.

Ten failure modes we see in nearly every Epic FHIR project we audit:

• Pitfall 1 — Underestimating onboarding timeline. Plan 6–12 months from start to first production customer. Anything less in your estimate is wishful thinking.
• Pitfall 2 — Assuming sandbox behavior equals production behavior. Sandbox is synthetic and clean. Real Epic customers have real data, real customizations, real quota limits.
• Pitfall 3 — Hardcoding endpoint URLs. Each Epic customer has their own FHIR endpoint. Your application must support N endpoints, not one.
• Pitfall 4 — Hardcoding OAuth issuers. Same problem at the auth layer. Multiple issuers, each with their own keys and token endpoints.
• Pitfall 5 — Not handling Epic version differences.Code that assumes resource X has field Y may break against an older Epic version where that field doesn't exist. Test against multiple versions or be defensive in your parsing.
• Pitfall 6 — Ignoring rate limits during testing.Your test traffic is 10% of production traffic. You'll hit rate limits at production volume that you never saw in testing.
• Pitfall 7 — Treating FHIR as 100% standardized.US Core specifies a baseline. Each EHR — including Epic — has implementation variations. Don't assume conformance means equivalence.
• Pitfall 8 — Building real-time use cases on FHIR polling. If you need event-driven behavior, FHIR polling is the wrong tool. Use HL7 v2 messaging or FHIR Subscriptions where available.
• Pitfall 9 — Skipping the customer's non-production environment. Going straight from sandbox to production at a customer site is how you discover production-specific issues at the worst possible time.
• Pitfall 10 — Underestimating the multi-tenancy problem. If your product supports N Epic customers, you have N FHIR endpoints, N OAuth contexts, N configuration files, and N debugging contexts. Build for this from day one.

Building an Epic FHIR integration well is one of those problems where the API documentation describes the technical surface but doesn't tell you what production actually looks like. The gap between “works in sandbox” and “works in production at 5 customer sites” is where most of the real engineering time goes.

If you're building this from scratch and want a senior engineering team that's done it before, book a 30-minute scoping call.

Book a scoping call →

For broader context, see our FHIR Integration Guide pillar, our HL7 v2 to FHIR R4 Mapping Reference, our FHIR Bulk Data Implementation Guide 2026, and our Epic EHR Integration service page.

For integration with Cerner/Oracle Health, see our Cerner EHR Integration page and Cerner Oracle Health Integration post.

To estimate an Epic FHIR integration project, run our pricing calculator — select Epic as one of your target EHRs.

Prefer email? info@tactionsoft.com — we reply within 4 business hours.