Epic FHIR API integration · United States
We connect health tech products to Epic's FHIR R4 APIs: the reads your features need, the write-back Epic actually supports, Bulk FHIR for population data and backend services that hold up under each health system's security review. Built against the Epic sandbox, activated site by site, monitored after go-live.
The health system's own FHIR base URL. Epic has no central endpoint.
Client ID, scopes and, for backend apps, a signed JWT checked against your JWK Set URL.
The Epic API, its supported search parameters and the US Core profile it returns.
Pagination, write rules, throttling and the errors your product must survive.
The short answer
Epic FHIR API integration connects your product to the FHIR R4 APIs each Epic health system exposes. Nirmitee maps your features to specific Epic APIs, confirms which ones read and which ones write, registers the client on fhir.epic.com, builds the authorization, data mapping and error handling, and tests against the Epic sandbox before the first customer activates your client ID. Epic's USCDI APIs are read-only; write-back runs through a short list of dedicated create and update APIs, each with its own rules. We design around those rules from day one, so the integration that passes in the sandbox is the one that goes live at the hospital.
Epic API catalog
Epic's public catalog lists 714 APIs, 636 of them FHIR. Each customer licenses and enables its own subset, so the specification names the exact Epic API, not just the FHIR resource.
| API family | Epic APIs | Read or write | What we design for |
|---|---|---|---|
| USCDI clinical data | Patient, Encounter, Condition, AllergyIntolerance, MedicationRequest, Observation (labs and vitals), DiagnosticReport, Immunization, Procedure, DocumentReference | Read and search only. No USCDI-flagged Epic API is a create or update. | Supported search parameters per resource, pagination, and change detection without _lastUpdated, which Epic does not support in R4. |
| Vital signs | Observation.Create (Vital Signs) R4 | Write | An Encounter FHIR ID on every reading, one reading per call, a LOINC that maps to exactly one flowsheet row, and no writes to closed encounters or future appointments. |
| Clinical notes | DocumentReference.Create (Clinical Notes) R4 | Write | Plain-text notes to open or closed encounters. Rich-text documents go through an HL7 v2 MDM interface instead. |
| Problems and allergies | Condition.Create (Problems), AllergyIntolerance.Create R4 | Write to a review queue | Entries land in a holding area a clinician reconciles into the chart, so your product shows pending review rather than saved. |
| Patient registration | Patient.Create R4 | Write | Match-or-create logic against identifiers, demographics and the EMPI. Backend and clinician scopes only. |
| Population data | Bulk Data 1.0.1 Group $export | Asynchronous read | Group export only, no _since, one export per group per client every 24 hours by default, and files kept for 14 days. |
| Payer and prior authorization | CMS-0057-F incoming and outgoing APIs, MedicationRequest.Update and ServiceRequest.Update (Prior Auth) | Read and write | Da Vinci CRD, DTR and PAS flows scoped with the payer side. Epic has published more than 50 APIs and playbooks for CMS-0057-F. |
Catalog facts from fhir.epic.com Specifications, checked 25 September 2026. We confirm each API against the customer's Epic version and /metadata before architecture sign-off.
What we build
Each integration type carries different authorization, data and activation work. We scope it before the first estimate.
The clinical data behind your feature, mapped to your product model with source identifiers, status and dates preserved.
Patient · Encounter · Condition · Observation · MedicationRequest · DiagnosticReport · US Core 6.1.0 · USCDI v3
Epic SMART on FHIR app development →Vitals, plain-text notes, problems, allergies and registrations filed through the Epic APIs built for them, with duplicate and rejection handling.
Observation.Create (Vital Signs) · DocumentReference.Create (Clinical Notes) · Condition.Create · Patient.Create
HL7 integration services →Server-to-server access for sync jobs, analytics and AI pipelines, with key rotation and per-customer credentials.
SMART Backend Services · client_credentials · signed JWT (RS384) · JWK Set URL · separate prod and non-prod keys
FHIR integration services →Group exports for registries, quality programs and value-based care, landed in a warehouse with reconciliation.
Group/$export · _type · _typeFilter · includeAssociatedData · NDJSON
FHIR data platforms →Real-time admissions, results, documents and scheduling that Epic delivers as HL7 v2 through Bridges, merged with your FHIR data.
ADT^A01 to A08 · ORU^R01 · MDM^T02 · SIU^S12 · Epic Bridges
Mirth Connect integration services →One codebase, many health systems: per-site configuration, activation checklists and alerts when a customer's endpoint or credentials change.
479 R4 endpoints in Epic's public directory · non-prod then prod activation · 12-hour license sync
Integration monitoring and support →Buyer decisions
Most Epic integrations combine two of these. The choice follows the data freshness, volume and write path your feature needs.
| Option | Best for | Watch for | Who owns the work |
|---|---|---|---|
| Epic FHIR R4 APIs (direct) | On-demand patient and clinician reads, supported writes, app launches | No _lastUpdated, write rules per API, the health system's review of every API you list | Your team or ours, with per-site activation by the health system |
| HL7 v2 through Epic Bridges | Real-time event feeds: admissions, results, orders, documents, scheduling | Interfaces licensed per interface by the health system and built by its interface team | The hospital interface team plus your listener and mapping |
| Bulk FHIR export | One-time loads, monthly cohorts, registries around 1,000 patients or fewer | Group export only, no incremental _since, one export per group per day by default | Your data team, with group setup by the health system |
| CDS Hooks | Decision support at patient-view, order-select and order-sign | Card latency inside the clinician workflow and unsigned-order suggestions only | Your service, configured by the health system |
| Middleware or aggregator | Many EHRs behind one API, or a team without integration engineers | Coverage of the exact Epic APIs and writes you need, platform fees and exit cost | The platform vendor, or Interoply, our own integration platform |
Planning a clinician-facing app on top of these APIs? See Epic SMART on FHIR app development. Budgeting the whole program? See Epic Integration Cost Planning.
Integration boundaries
These dependencies sit with Epic or the health system. We name them in the plan and drive them from the first week.
Each Epic customer runs an independent instance and decides which apps connect. We collect the production FHIR base URL, Epic version and enabled APIs for every site.
Epic licenses its USCDI FHIR APIs to each health system under an open.epic API Subscription Agreement, priced in tiers by the organization's size. Public and standards-based APIs cost app developers nothing. These are the health system's fees and we list them as a customer dependency.
Once an app is marked Ready for Production, only redirect URIs and JWK Set URLs can change. We freeze the API list only when it matches production use, because every listed API is reviewed by each customer.
Starting with the May 2026 Epic version, backend OAuth 2.0 apps must publish a JWK Set URL instead of a static public key, with separate URLs for production and non-production. From August 2026 customers may alternatively upload a static key.
Epic publishes no per-second rate limit. Its developer guidelines ask apps to stay under 1% of operational database resources at peak hours and 5% off-peak, and to be able to throttle. We build the throttle in.
Epic ships quarterly versions in February, May, August and November, and customers often upgrade 3 to 12 months later. We check each API against the site's version, not the sandbox's.
Deliverables
Once paid, everything below is yours and lives in your repository, along with all of your data. We keep our reusable tools and open-source parts.
Each product feature mapped to the Epic API, operation, scope and US Core profile it needs, with the customer licensing it depends on.
The fhir.epic.com app record, production and non-production client IDs, redirect URIs, JWK Set URLs and the API list justified line by line.
Authorization, API clients, retries and throttling with automated tests against the Epic sandbox and recorded fixtures for its weekly reset.
Resource-to-model mapping with terminology (LOINC, SNOMED CT, RxNorm, ICD-10-CM), identifiers and the handling for data Epic does not return.
The steps for each new health system: endpoint, client download, key provisioning, non-production validation and production cutover.
Alerts for token failures, 4xx and 5xx rates and stalled exports, plus the escalation path with each health system's integration team.
Delivery phases
Engineering milestones are ours to hit. The first production site adds the health system's security review, build queue and change window, which we track as named dependencies.
Weeks 1 to 3
Feature-to-API matrix, write-back feasibility, customer dependency list and a fixed scope for the build.
Weeks 3 to 10
Working reads, writes and backend access against fhir.epic.com, with fixtures reseeded after the Sunday sandbox refresh.
Weeks 8 to 16, paced by the health system
Client download, key provisioning, non-production validation, security review answers and production cutover.
After the first go-live
A per-site checklist, monitoring and API change tracking as customers move to new Epic versions.
Cost drivers
We give a fixed scope after discovery. These are the factors that move it.
A read-only feature on five USCDI APIs is a smaller build than one that also files vitals, notes and problems through separate write APIs.
Patient-facing apps, clinician apps and backend services each need their own flows, key management and customer review.
Each site adds activation, credentials and validation. Reusable configuration keeps the second site smaller than the first.
Bulk exports, polling without _lastUpdated and HL7 v2 feeds for real-time events each add pipeline and reconciliation work.
Mapping into an existing product model with terminology normalization costs more than storing FHIR resources as they arrive.
The health system's API subscription, any Epic Vendor Services membership and middleware fees are separate from our engineering and listed in the estimate.
Proof
Client names are withheld; each item is a real engagement or a public repository you can inspect.
Our multi-EHR SMART app runs discovery, PKCE and token exchange against both vendors from one code path, reads the chart and files a vital-sign Observation that returns 201 and reads back. It records what differs: Epic granted the scopes on the registration (we asked for openid fhirUser and received 84), Oracle Health granted only the intersection, and Oracle access tokens lasted about 570 seconds.
A FHIR R4 server with SMART App Launch that passed 47 of 47 ONC (g)(10) SMART standalone patient tests in Inferno. It is the same authorization and launch contract Epic and Oracle Health implement.
View the repository on GitHub →Coverage Requirements Discovery over CDS Hooks, Documentation Templates and Rules, and Prior Authorization Support, tested with the Inferno kits. These are the flows behind Epic's CMS-0057-F payer APIs.
View the CRD server on GitHub →Scheduling, charts, care plans and billing on a FHIR R4 server with no private database. Clinicians sign in through a PKCE OAuth 2.0 flow and an OAuth token exchange bridges the organization's single sign-on to the FHIR server.
We are ISO 27001:2022 certified and sign Business Associate Agreements for work that touches patient data.
FAQ
It is connecting your product to the FHIR R4 APIs an Epic health system exposes, so your software can read patient and clinician data and, where Epic supports it, write data back. The work covers app registration on fhir.epic.com, OAuth 2.0 authorization, the specific Epic APIs your features call, data mapping and activation at each customer.
Epic makes its public and standards-based APIs available to app developers at no cost through open.epic and fhir.epic.com. Health systems license the USCDI FHIR APIs under an open.epic API Subscription Agreement priced in tiers by organization size. Epic Vendor Services is an optional paid annual membership that adds testing tools, a private API catalog and support.
Cost follows the number of Epic APIs and write operations, the authorization model, the number of health systems and how the data must be mapped. We give a fixed scope after a short discovery and list health-system fees and any Vendor Services membership separately from engineering.
A focused read integration is usually built and tested against the Epic sandbox in 6 to 10 weeks. The first production site then runs on the health system's timetable for security review, client activation and change windows, commonly several months. Later sites are faster because the code and runbook are reused.
Yes, through specific APIs: Observation.Create for vital signs, DocumentReference.Create for plain-text clinical notes, Condition.Create and AllergyIntolerance.Create into a clinician review queue, and Patient.Create for registration. Each has its own rules, such as an Encounter reference and one reading per call for vitals. Anything outside that list goes through HL7 v2 or CDS Hooks.
Epic publishes customer R4 endpoints in its public directory, which listed 479 on 25 September 2026, but the production base URL is confirmed with the health system. Its staff download your client ID, you provision keys for backend and confidential clients, and the app is activated in non-production before production.
From the May 2026 Epic version, backend OAuth 2.0 apps must use a JWK Set URL instead of a static public key, with different URLs for production and non-production. From August 2026 a customer may upload a static key instead. Key changes can take up to 12 hours to reach a health system, so rotation is planned rather than rushed.
Epic supports Bulk Data 1.0.1 Group export for R4 with _type, _typeFilter and includeAssociatedData. It does not support _since, allows one export per group per client every 24 hours by default and keeps files for 14 days. It suits one-time loads and monthly cohorts; ongoing warehouse sync needs a different design.
The API catalog, specifications and tutorials are on fhir.epic.com, and open.epic.com covers HL7 v2, X12 and other interface specifications plus the customer endpoint directory. Vendor Services members also get a self-service private API catalog. We read the specification for every API we plan to call, including its scopes and write rules.
No. Epic states that no special relationship is required to develop or deploy an app. Vendor Services adds tooling and support. Showroom listings are optional; the Connection Hub tier needs your product live with at least one Epic customer and carries an annual listing fee.
Use FHIR for on-demand reads and the supported writes, and HL7 v2 through Epic Bridges for real-time events such as admissions, results and documents. Many products need both. We design the two paths to share identifiers and reconcile against each other.
Yes. We sign Business Associate Agreements and are ISO 27001:2022 certified. Integrations keep PHI out of logs and support tickets, encrypt it in transit and at rest, and use per-customer credentials stored in a secrets manager.
Next step
In 30 minutes we map your features to Epic APIs, flag the write-back and licensing questions and outline the path to your first Epic customer.
Define the next step
Tell us the feature, the data it reads or writes and the health systems you are selling to. We reply with the Epic APIs involved and the next practical step.
Please do not include patient data or credentials.
Epic, MyChart and Hyperspace are trademarks of Epic Systems Corporation.
From our YouTube channel
Explore the workflows and decisions behind this service. Demonstrations and recorded discussions have the scope described in each video.
Epic public sandbox sign-in, chart reads and vital-sign write-back with synthetic test patients.
Epic sandbox note filing and verification. Drafting uses a fixed template with synthetic data; the lost reply is injected.
