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
| Name | Type | Required | Description |
|---|---|---|---|
search_params | json | No | FHIR search parameters |
resource_id | text | No | FHIR resource ID for read operation |
patient_id | text | No | Patient ID for patient_everything operation |
family_name | text | No | Patient family name (for patient_search) |
given_name | text | No | Patient given name (for patient_search) |
birthdate | text | No | Patient birthdate in YYYY-MM-DD format |
identifier | text | No | Patient identifier |
mrn | text | No | Medical Record Number |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | Main result data from the Epic FHIR operation |
metadata | json | No | Response metadata including resource type, counts, and operation details |
success | boolean | No | Whether the operation succeeded |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Epic Base URL | epic_base_url | string | Yes | Epic base URL (e.g., https://fhir.epic.com/interconnect-fhir-oauth) | ||
| Operation | operation | enum | No | search | search, read, patient_search, patient_everything, interact | FHIR operation to perform |
| Resource Type | resource_type | string | No | Patient | FHIR resource type | |
| Interaction | interaction | enum | No | search | read, search, history, operation, create, update, patch, delete | FHIR interaction for the 'interact' operation |
| FHIR Version | fhir_version | enum | No | R4 | R4 | FHIR version path segment |
Auth
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Client ID | client_id | secret | No | Epic OAuth2 client ID | ||
| Client Secret | client_secret | secret | No | Epic OAuth2 client secret | ||
| Auth Mode | auth_mode | enum | No | client_secret | backend_jwt, client_secret, injected_token, external_auth | How to authenticate the 'interact' operation |
| External Auth Connection ID | connection_id | string | No | UUID of the stored Epic connection in External Auth; the node mints the token from your stored cert (auth_mode=external_auth) | ||
| Bearer Token | bearer_token | secret | No | Pre-obtained access token for auth_mode=injected_token (or pass via the bearer_token input) | ||
| RS384 Private Key (PEM) | private_key_pem | secret | No | Backend Services signing key; delivered via secret reference, never logged | ||
| Key ID (kid) | kid | string | No | JWKS key id for the signing key | ||
| JWT Algorithm | jwt_alg | enum | No | RS384 | RS384, ES384 | Client-assertion signing algorithm |
| Token URL | token_url | string | No | Explicit token endpoint (else discovered from iss/.well-known) | ||
| Issuer / Base | iss | string | No | Issuer base for .well-known endpoint discovery (defaults to epic_base_url) | ||
| SMARTv2 Scopes | scope_v2 | boolean | No | false | Emit granular SMARTv2 scopes (rs/cruds) instead of v1 (read/write) |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Resource ID | resource_id | string | No | FHIR resource ID (for read operation) | ||
| Patient ID | patient_id | string | No | Patient ID (for patient_everything operation) | ||
| Search Parameters | search_params | json | No | FHIR search parameters | ||
| Count | count | number | No | Number of results to return | ||
| Offset | offset | number | No | Offset for pagination | ||
| MRN System | mrn_system | string | No | urn:oid:1.2.840.114350.1.13.0.1.7.5.737384.0 | Epic MRN system identifier | |
| Start Date | start_date | string | No | Start date for $everything operation (YYYY-MM-DD) | ||
| End Date | end_date | string | No | End date for $everything operation (YYYY-MM-DD) | ||
| Resource ID | interaction_resource_id | string | No | Target id for read/history/operation interactions | ||
| Operation Name | operation_name | string | No | summary | $operation name for interaction=operation. Epic R4 supports summary and match (NOT everything); use a Group $export for bulk | |
| Max Pages | max_pages | number | No | 1 | Max pages to follow for interaction=search | |
| Dry Run | dry_run | boolean | No | false | For write interactions: build the request but do not send it | |
| Resource Body | resource_body | json | No | FHIR resource payload for write interactions (preview only in this version) |
Errors
| Code | Description |
|---|---|
EPIC_AUTH_FAILED | Failed to obtain OAuth2 token from Epic |
EPIC_SEARCH_FAILED | Epic FHIR search returned an error |
EPIC_READ_FAILED | Epic FHIR read returned an error |
PATIENT_ID_REQUIRED | patient_id is required for patient_everything operation |
RESOURCE_ID_REQUIRED | resource_id is required for read operation |
EPIC_WRITE_REQUIRES_APPROVAL | Write interaction blocked: enable dry_run to preview; real writes require the clinical-safety gate |
EPIC_UNSUPPORTED_OPERATION | The 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.
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..