Epic
Access
Section titled “Access”- Register a backend app through Epic’s developer programme, using SMART Backend Services with a
JWT signed by a key in your JWKS.
system/*.read-style scopes. - Each health system runs its own Epic instance with its own FHIR endpoint, and must activate your app in its environment. Your app working at one health system says nothing about the next.
- The token URL can be derived from the FHIR base: replace
/api/FHIR/R4with/oauth2/token. - Epic’s sandbox has a small, documented set of test patients — useful for proving the flow, not for volume testing.
Extraction approach
Section titled “Extraction approach”Patient-level search. Bulk $export needs a patient Group that the health system builds for
you, so in practice most quality-reporting integrations start from a patient list:
- Match each patient with
Patient?given=&family=&birthdate=, addingaddress-postalcodewhen you have a ZIP to tie-break. - Search the clinical resources for that patient, for example
Observation?patient=<id>&code=<comma-separated LOINCs>&date=<period>. - Follow
link.next— do not assume one page holds everything.
Known behaviour
Section titled “Known behaviour”Encounter search needs a patient
Section titled “Encounter search needs a patient”Epic rejects an Encounter search that filters only by date: it returns HTTP 400 unless the
request also names a patient or an _id. You cannot ask for “all encounters in the measurement
period” with patient-level search; the cohort has to come from a patient list, a Group export, or
another source.
Turning on Bulk can affect authentication
Section titled “Turning on Bulk can affect authentication”When bulk access was enabled on an existing app registration, token requests began failing with
invalid_client until the registration was corrected. If you change an app’s capabilities,
re-test authentication immediately.
Depression screening often lives in notes
Section titled “Depression screening often lives in notes”PHQ results may not be structured Observations. They can appear only inside clinical notes
(DocumentReference with an HTML attachment), which then has to be parsed.
Patient search can be flaky
Section titled “Patient search can be flaky”Intermittent failures on Patient search are common enough that a few retries with a short pause
are worth building in.