Challenge
Over-scoped client IDs stall security review
Agnotic approach
We map every API on the client ID to a use case. Epic notes that customers review that list and may ask for a narrower client ID.
Epic FHIR capabilities
Epic FHIR Capabilities
You need to know what Epic's FHIR APIs allow before you commit a roadmap to them. This reference maps the APIs, scopes, auth models and limits from Epic's own developer documentation, and Agnotic Technologies builds and tests the integration against the Epic sandbox for you.
FHIR R4SMART v1 and v2 scopesBackend OAuth 2.0Bulk Data Group export
Trusted by global innovators
What are Epic FHIR capabilities?
Epic FHIR capabilities are the HL7 FHIR APIs, OAuth 2.0 launch and backend flows, Bulk Data export and CDS Hooks that Epic documents on fhir.epic.com for third-party apps. Agnotic Technologies uses that documentation to scope what your app can read, write and search, then builds and tests the integration for you.
This page is a developer reference. Our Epic integration services page covers how an engagement runs; here we list what the platform documents and where its limits sit.
Every capability below comes from Epic's published developer documentation. What a health system has licensed and switched on can be narrower, so we confirm it per customer before scoping.
Capability table
Which Epic FHIR capabilities can your app use?
Built only from Epic's developer documentation. Availability at a given Epic customer still depends on its version, licensing and configuration.
| Capability | What it does | Auth model | Notes from Epic's docs |
|---|---|---|---|
| SMART on FHIR EHR launch | Launches your app from Epic with patient context and single sign-on | OAuth 2.0 authorization code; PKCE with S256 only | Encounter context is returned only to apps with an STU3 or later app FHIR version |
| SMART standalone launch | Your app starts the login and the patient signs in with MyChart | OAuth 2.0 authorization code | Epic shows its Data Use Questionnaire to patients by default for MyChart apps |
| Backend Systems apps | Server-to-server FHIR calls, and HL7 v2 over HTTP(S) | JWT client assertion; RS256, RS384, RS512, or ES256 and ES384 with a JWK Set URL | A distinct public key or secret per customer and environment |
| FHIR R4 resource APIs | Per-API read, search and create, for example Patient.Search, Observation.Create, DocumentReference.Search | SMART v1 (.read, .write) or SMART v2 (c, r, u, d, s) scopes | Your client ID lists every API it may call; Epic advises scoping narrowly |
| Patient.$match | Finds a high-confidence patient match from demographics | Backend OAuth 2.0 for system-to-system lookups | Epic recommends it for patient lookup before querying records |
| Bulk Data export | Group export of FHIR resources for a defined patient group | Backend client authorized for the Bulk Data APIs and each resource's R4 Search API | Spec 1.0.1; no _since; files deleted after 14 days |
| CDS Hooks | Calls your service at patient-view, order-select and order-sign | Registered CDS service; prefetch must be scoped to your client | Prefetch resources must match the client's primary FHIR version |
| Patient.$summary (IPS) | Returns an International Patient Summary for a patient | Backend OAuth 2.0 recommended | Suited to query-based document exchange at the point of care |
Epic lists data warehouse synchronization and incremental loads as poor fits for Bulk Data, and suggests keeping registry cohorts to around 1,000 patients or fewer.
App records
How do Epic client IDs and app versions work?
Registering an app on fhir.epic.com creates an app record with a production and a non-production client ID. Draft changes can take up to an hour to reach the sandbox.
The app FHIR version chosen at creation changes launch behaviour, including the iss endpoint and the patient ID version returned. After an app is marked ready for production, technical changes other than redirect URIs and JWK Set URLs need a new app record.
Failure points
Where do Epic FHIR integrations break?
Each of these comes from Epic's own documentation or change log, and each one fails quietly if you do not design for it.
Challenge
Refresh tokens that stop working after an Epic upgrade
Agnotic approach
Tokens issued before the November 2025 sub-resource change lack the new sub-resource scopes, so we send the user back through authorization instead of retrying.
Challenge
Using Bulk Data as a sync engine
Agnotic approach
We use Bulk Data for one-time loads and small scheduled cohorts, and event feeds or targeted FHIR searches for ongoing sync.
Challenge
Wrong token endpoint at a customer
Agnotic approach
Discovery reads the SMART configuration or metadata endpoint with the Epic-Client-ID header, because a customer can override endpoints per client ID.
Challenge
FHIR IDs longer than your database expects
Agnotic approach
Some Epic FHIR IDs exceed 64 characters. We size ID columns for that or choose the 64-character option on new clients before go-live.
Challenge
Needing to edit an app after activation
Agnotic approach
We finish sandbox testing before an app is marked ready, and version app records on purpose, since later technical changes mean a new app.
How we work
How do you take an Epic FHIR app from sandbox to a live customer?
Four steps, with a fixed first release agreed before any code is written.
1.
Scope the APIs
We list the APIs, launch type and user context your use case needs, and leave out anything added just in case, in line with Epic's scoping guidance.
Narrow scope
2.
Register and test in the sandbox
We create the app record, pick the FHIR and SMART scope versions, and test with Epic's sandbox patients. Epic sandboxes take synthetic data only.
Synthetic data
3.
Activate and provision per customer
The app is marked ready for production, the health system downloads the client ID, and we register a distinct key or secret for each customer and environment.
Per-customer keys
4.
Go live and monitor
We watch token errors, API failures and Epic's API change log, and plan each customer's upgrades so integrations keep working.
Monitored
Scope drivers
What drives the cost of an Epic FHIR integration?
We do not quote a price before scoping. These are the factors that move effort on an Epic build, and we size each one on the call.
Launch type and users
Patient-facing, clinician-facing and backend apps differ in auth, testing and customer review. Many products need two of them.
Read only or write back
Search and read is the smaller build. Filing Observations adds mapping, flowsheet IDs from each health system and more testing.
Number of Epic customers
Each customer downloads the client ID, gets its own keys and may configure APIs differently, so rollout effort grows per site.
API licensing at the customer
Epic licenses its APIs to healthcare organizations based on production usage. A narrow client ID keeps the customer's licensing review short.
Bulk Data and CDS Hooks
Population exports need a group the health system sets up. CDS Hooks need a fast service and analyst configuration at each site.
Startup or established product
Startups often need the data model built with the integration. Established products mostly need mapping and hardening.
Who builds on Epic
Who builds on Epic FHIR APIs?
The same documented capabilities, used by very different products.
Health tech startups
Products that need chart data from Epic customers from the first pilot.
Clinician-facing apps
Tools launched inside the clinician workflow with SMART on FHIR EHR launch and single sign-on.
Patient apps
Apps patients connect with their MyChart login through standalone launch.
RPM and device programs
Readings filed to flowsheets with Observation.Create or an HL7 v2 interface.
Decision support vendors
CDS Hooks services that return cards at patient-view or order-sign.
Registries and analytics
Scheduled extracts for small, defined cohorts through Bulk Data.
Compliance as engineering
How do we keep PHI safe on an Epic FHIR integration?
The HIPAA Security Rule applies to your product as well as the health system. We turn it into concrete design decisions.
Business associate agreements
Agnotic signs a BAA before any PHI is shared. Development and testing use Epic's sandbox and synthetic patients only.
Least-privilege scopes
Each client ID carries only the APIs its use case needs, which also keeps customer security review focused.
Key handling
Signing keys live in a secrets manager. We prefer JWK Set URLs, as Epic recommends, so keys can rotate without a new app.
Audit logging
Every FHIR call is logged with user, patient, purpose and time, so the health system can answer access questions.
Compliance-First Healthcare App Development Services Backed by Global Standards
01
HIPAA
Health Insurance Portability and Accountability Act
Protect PHI with privacy-first architecture, encrypted storage and transmission, strict access controls, and traceable audit logs.
02
GDPR
General Data Protection Regulation
Implement lawful consent flows, data minimization, retention controls, and secure processing for sensitive health data.
03
FHIR
Fast Healthcare Interoperability Resources
Enable standardized health data exchange across apps, care teams, and systems through standards-based FHIR APIs.
04
HL7
Health Level Seven International
Support enterprise-grade interoperability with HL7-based integrations for records, events, and clinical messaging workflows.
05
HITRUST
Health Information Trust Alliance
Align security programs to healthcare-specific control and risk management practices trusted by providers and ecosystem partners.
06
HITECH
Health Information Technology for Economic and Clinical Health Act
Design with breach notification readiness, digital record safeguards, and operational controls that support regulated care programs.
07
SaMD
FDA Software as a Medical Device
Plan software quality, traceability, and documentation pathways for products that may require SaMD review and submission.
08
MDR (EU)
Medical Device Regulation (European Union)
Prepare EU market-ready processes for risk classification, evidence tracking, and lifecycle governance under MDR expectations.
09
SAMHSA
Substance Abuse and Mental Health Services Administration
Apply confidentiality controls and consent-aware sharing models for behavioral and mental health data experiences.
Standards in scope
Standards on Epic's FHIR surface
FHIR R4SMARTOAuth 2.0Bulk DataCDS HooksHL7 v2
Facts and sources
Which facts from Epic's documentation shape this page?
Short facts we design around, each linked to Epic's own developer documentation.
Epic supports version 1.0.1 of the FHIR Bulk Data Access specification for R4 resources, with some 1.1.0 features. It supports only the Group export operation, does not support _since, and deletes request data 14 days after kick-off.
Source: Epic on FHIR, FHIR Bulk Data Access TutorialEpic supports PKCE with the S256 code challenge method only. Confidential and backend clients sign their JWTs with RS256, RS384 or RS512, or with ES256 or ES384 when the client registers a JWK Set URL.
Source: Epic on FHIR, OAuth 2.0 SpecificationIn Epic, SMART v1 scopes use .read and .write actions, while SMART v2 scopes use create, read, update, delete and search actions; an app selects its SMART scope version in its settings.
Source: Epic on FHIR, CMS Prior Auth Playbook (app settings)Once an Epic app is marked ready for production, neither the developer nor Epic can update it; apart from adding redirect URIs and changing JWK Set URLs, technical changes need a new app record.
Source: Epic on FHIR, App Creation and Request Process OverviewEpic licenses its industry-standard and Public APIs directly to healthcare organizations, not to app developers. Fees are based on production usage, and the APIs on a client ID decide which licenses a customer may need.
Source: Epic on FHIR, App Creation and Request Process Overview
Frequently Asked Questions
Epic recommends an app FHIR version of STU3 or later, because DSTU2 lacks functionality the later versions support. We build new apps on R4 resources. Choosing an app FHIR version does not stop the app calling APIs of other FHIR versions.
Epic licenses its industry-standard and Public APIs to healthcare organizations, not to app developers, and says fees are based on production usage. We do not set or quote those fees. We keep your client ID narrow so the customer's licensing estimate is clear, and we scope our own build separately.
Yes, for development. Epic states that direct access to its software is not needed to develop and test, and its sandbox is available to registered developers. Going live needs a health system that downloads your client ID and has signed the open.epic API Subscription Agreement.
Usually not. Epic lists data warehouse synchronization and incremental loads as poor fits, supports Group export only and does not support _since. We use it for one-time loads and small scheduled cohorts, and other interfaces for ongoing sync.
It depends on scope; we agree a fixed first release on the scoping call. A read-only SMART app for one health system is a smaller release than a backend integration that writes data across many customers.
Yes. Agnotic signs a business associate agreement before any PHI is shared. Epic's sandbox takes only synthetic data, so development and testing never use real patients.
Engineers use AI tools for drafts and test generation, then review every change. AI tools never see real patient data, and every mapping is tested against sandbox data before it reaches a customer.