Skip to main content

Epic FHIR

Category: EHR & Practice Mgmt
Node id: epic-fhir

Standards: HIPAA, GDPR, SOC2

Integrates with Epic EHR via FHIR R4 and SMART on FHIR authentication for patient data retrieval

What it does​

  • SMART on FHIR OAuth2 client credentials authentication
  • FHIR R4 search with configurable parameters and pagination
  • Patient-specific search by name, birthdate, MRN, or identifier
  • $everything operation for complete patient data retrieval
  • Resource categorization by type from Bundle responses
  • Epic-specific MRN system identifier support

Use cases​

  • Sync patient demographics from Epic to a data warehouse
  • Retrieve complete patient records via $everything for analytics
  • Search Epic for patients by MRN in clinical integration pipelines
  • Feed Epic clinical data into FHIR-to-OMOP transformation nodes

Runtime​

  • Performance tier: variable

Input ports​

NameTypeRequiredDescription
search_paramsjsonNoFHIR search parameters
resource_idtextNoFHIR resource ID for read operation
patient_idtextNoPatient ID for patient_everything operation
family_nametextNoPatient family name (for patient_search)
given_nametextNoPatient given name (for patient_search)
birthdatetextNoPatient birthdate in YYYY-MM-DD format
identifiertextNoPatient identifier
mrntextNoMedical Record Number

Output ports​

NameTypeRequiredDescription
resultjsonNoMain result data from the Epic FHIR operation
metadatajsonNoResponse metadata including resource type, counts, and operation details
successbooleanNoWhether the operation succeeded

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Epic Base URLepic_base_urlstringYesEpic base URL (e.g., https://fhir.epic.com/interconnect-fhir-oauth)
OperationoperationenumNosearchsearch, read, patient_search, patient_everything, interactFHIR operation to perform
Resource Typeresource_typestringNoPatientFHIR resource type
InteractioninteractionenumNosearchread, search, history, operation, create, update, patch, deleteFHIR interaction for the 'interact' operation
FHIR Versionfhir_versionenumNoR4R4FHIR version path segment

Auth​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Client IDclient_idsecretNoEpic OAuth2 client ID
Client Secretclient_secretsecretNoEpic OAuth2 client secret
Auth Modeauth_modeenumNoclient_secretbackend_jwt, client_secret, injected_token, external_authHow to authenticate the 'interact' operation
External Auth Connection IDconnection_idstringNoUUID of the stored Epic connection in External Auth; the node mints the token from your stored cert (auth_mode=external_auth)
Bearer Tokenbearer_tokensecretNoPre-obtained access token for auth_mode=injected_token (or pass via the bearer_token input)
RS384 Private Key (PEM)private_key_pemsecretNoBackend Services signing key; delivered via secret reference, never logged
Key ID (kid)kidstringNoJWKS key id for the signing key
JWT Algorithmjwt_algenumNoRS384RS384, ES384Client-assertion signing algorithm
Token URLtoken_urlstringNoExplicit token endpoint (else discovered from iss/.well-known)
Issuer / BaseissstringNoIssuer base for .well-known endpoint discovery (defaults to epic_base_url)
SMARTv2 Scopesscope_v2booleanNofalseEmit granular SMARTv2 scopes (rs/cruds) instead of v1 (read/write)

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Resource IDresource_idstringNoFHIR resource ID (for read operation)
Patient IDpatient_idstringNoPatient ID (for patient_everything operation)
Search Parameterssearch_paramsjsonNoFHIR search parameters
CountcountnumberNoNumber of results to return
OffsetoffsetnumberNoOffset for pagination
MRN Systemmrn_systemstringNourn:oid:1.2.840.114350.1.13.0.1.7.5.737384.0Epic MRN system identifier
Start Datestart_datestringNoStart date for $everything operation (YYYY-MM-DD)
End Dateend_datestringNoEnd date for $everything operation (YYYY-MM-DD)
Resource IDinteraction_resource_idstringNoTarget id for read/history/operation interactions
Operation Nameoperation_namestringNosummary$operation name for interaction=operation. Epic R4 supports summary and match (NOT everything); use a Group $export for bulk
Max Pagesmax_pagesnumberNo1Max pages to follow for interaction=search
Dry Rundry_runbooleanNofalseFor write interactions: build the request but do not send it
Resource Bodyresource_bodyjsonNoFHIR resource payload for write interactions (preview only in this version)

Errors​

CodeDescription
EPIC_AUTH_FAILEDFailed to obtain OAuth2 token from Epic
EPIC_SEARCH_FAILEDEpic FHIR search returned an error
EPIC_READ_FAILEDEpic FHIR read returned an error
PATIENT_ID_REQUIREDpatient_id is required for patient_everything operation
RESOURCE_ID_REQUIREDresource_id is required for read operation
EPIC_WRITE_REQUIRES_APPROVALWrite interaction blocked: enable dry_run to preview; real writes require the clinical-safety gate
EPIC_UNSUPPORTED_OPERATIONThe requested interaction is not supported

Runtime notes​

  • Output has BOTH result and metadata as separate top-level keys — metadata is NOT inside result. Wire metadata for counts, result for data.
  • patient_search returns result.patients (extracted Patient resources array) in addition to result.bundle for convenience.
  • patient_everything returns result.resources categorized by resourceType, with a _counts key summarizing each type. Access like result.resources.Condition.
  • OAuth2 token is obtained automatically via client credentials flow on every execution — no manual token management needed.

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Something unclear? Send documentation feedback by email.