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.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.