What we do
Tools
Industries
Department
How we workLet's talk →
Home/Epic/Epic FHIR API
Epic

Epic's FHIR API: What It Exposes, How Apps Launch, and What Each Hospital Switches On

Epic's FHIR API is a standards-based REST interface to the clinical record: Patient, Encounter, Observation, MedicationRequest, DocumentReference and many more resources. You register an app on fhir.epic.com, build against a sandbox of test patients, and authorize with SMART on FHIR. What it never gives you on its own is a live hospital. Every Epic organization decides whether to switch your client ID on, and which APIs it can reach.

The short version

Register: create an app on fhir.epic.com (Epic on FHIR). Registration gives you a non-production client ID for the sandbox and a production client ID that does nothing until a customer enables it.

Versions: resources are documented in R4, STU3 and DSTU2, each with its own Read, Search or Create interactions. New work targets R4.

Going live: mark the app ready for production, then each health system requests your client ID for its environment and turns on the APIs you need.

App Orchard? It's gone. Epic paused App Market, its later name, at the end of 2022. Developers now work through open.epic or Vendor Services. The story is on our App Orchard page.

Three shapes of Epic FHIR app

Pick the audience when you register. It sets the OAuth flow and what the health system has to build.

Who uses it How it authorizes What the health system does
Clinicians, opened from inside Epic SMART EHR launch: Epic opens your app with a launch token and an iss base URL, and your app trades them for an access token with patient and encounter context Adds your app to their Epic screens, activates your client ID, and decides which users see it.
Patients, signing in with MyChart SMART standalone launch: your app sends the patient to the organization's MyChart login and gets a token for that patient Enables your client ID. Epic offers extra distribution routes for some patient-authorized apps, covered in its patient-facing apps tutorial.
No user: a server or nightly job SMART backend services: your server signs a short-lived JWT with its private key, and Epic checks it against the public key you registered (a JWK Set URL or an upload) Activates the client and sets what it may read. Bulk FHIR exports use this route.

Epic's sandbox and a hospital's production are different places

Open to any developer

The fhir.epic.com sandbox

  • Uses your non-production client ID
  • A fixed base URL and a set of test patients and test logins
  • The APIs Epic documents, for testing
  • Proves your OAuth flow and parsing work
Their decision

A health system's Epic

  • Uses your production client ID, once they activate it
  • Their own FHIR base URL, which you discover per organization
  • Only the APIs they turn on, at the Epic version they run
  • Real records, with their own build, codes and gaps

Write your code against the sandbox, but don't hard-code anything you learned there: base URLs, patient IDs, codes or which fields arrive populated.

Reading the resource documentation

Epic documents each FHIR interaction as its own API, such as Patient.Read, Patient.Search or Observation.Search, per FHIR version. When you register, you choose the APIs your app calls, and those choices travel with the client ID. A call to anything you didn't select fails even if your token is valid.

Most resources are read and search only. Writes exist for a narrower set, and they often depend on the hospital's own build, such as where a recorded vital sign or a note is filed. Check the resource's page on fhir.epic.com for the exact interaction before you design a write.

Bulk FHIR is the population route. A backend app starts an asynchronous $export on a Group the health system has defined, polls a status URL, and downloads NDJSON files when they're ready. It suits reporting, analytics and research loads. It isn't meant for answering a question about one patient right now.

What to ask each health system's Epic team

Bring these to the first call with their analysts. The answers decide whether your sandbox code runs unchanged.

  • Which Epic version are you on?

    APIs arrive with Epic versions. One the sandbox has may not exist yet in an organization a release or two behind.

  • Will you activate our production client ID, and with which of the APIs we registered?

    They can approve less than you asked for. Your app needs to cope when a call it expected is refused.

  • What is your FHIR base URL for this app?

    Patient-facing endpoints are listed on open.epic. Clinician and backend apps usually get theirs from the organization's team.

  • For an EHR launch: where will the app appear, and for which users?

    Their team builds the launch point inside Epic. The app is invisible until that work is done.

  • For Bulk FHIR: which Group will we export?

    They define the patient population. Without a Group ID there's nothing to export.

  • Where will our writes be filed?

    Notes, vitals and results land in places their build decides. Agree it before you write a single resource.

Epic FHIR mistakes that only show at the first hospital

The sandbox client ID left in the config

How you'll know: Authorization fails at the hospital with an unknown or unauthorized client.

Fix: Production uses the other client ID. Keep both per environment, and per organization if you reach more than one.

Assuming every field is filled

How you'll know: Code that ran cleanly on test patients throws on real records with missing codes or extra extensions.

Fix: Treat every element FHIR marks optional as possibly missing, and log what each organization actually sends.

Requesting every API "just in case"

How you'll know: The health system's security review stalls on a list of APIs your product doesn't use.

Fix: Register only the interactions your app calls. A short list is faster to approve and easier to explain.

Questions people ask

What is FHIR?

FHIR (Fast Healthcare Interoperability Resources) is an HL7 standard for exchanging health data as structured resources like Patient, Observation and MedicationRequest over a REST API, using JSON or XML instead of older pipe-delimited messages.

Is Epic's FHIR API free to use?

Registering on fhir.epic.com and building against the sandbox costs nothing through open.epic. Production access is agreed with each health system, which may have its own contracting and security review. Vendor Services is an optional paid membership with extra support from Epic.

Do I need App Orchard to use Epic's FHIR API?

No. App Orchard was renamed App Market, and Epic paused App Market at the end of 2022. You register on fhir.epic.com, through open.epic or Vendor Services, and each health system enables your client ID. Our App Orchard page explains what replaced each part.

What's the difference between Epic's FHIR API and HL7 interfaces?

FHIR is request and response: your app asks for a resource when it needs it. HL7v2 interfaces push messages, such as admissions and results, as events happen, and still carry most high-volume feeds. Many products use both. Our Epic integration page helps choose between them.

What is Bulk FHIR used for with Epic?

Exporting data for a whole population in one asynchronous job, as NDJSON files, rather than calling one patient at a time. It runs through a backend app against a Group the health system defines, and fits reporting, analytics and research.

Where is Epic's FHIR sandbox?

On fhir.epic.com. Register an app to get a non-production client ID, then use the sandbox base URL with the test patients and logins Epic lists in its documentation.

What is SMART on FHIR in Epic?

The OAuth 2.0 profile Epic uses to authorize FHIR apps. It defines the EHR launch from inside Epic, the standalone launch where a patient signs in with MyChart, and backend services for server-to-server access.

Who builds Epic FHIR integrations for companies without an Epic team?

n-frames does. We build the SMART or backend client against the sandbox, prepare the API list and questions for each health system's analysts, and connect the FHIR data to your own product once they switch it on.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.