Epic on FHIR
App · 11 actions
Read patient records from Epic's FHIR APIs: find patients, then pull their labs and vitals, conditions, visits and allergies. Read-only, in Epic's sandbox or a hospital's own server.
Actions
| Action | What it does |
|---|---|
| Get allergy | Get one allergy or intolerance with its substance, criticality and reactions. |
| Get condition | Get one condition with its code, status, onset and severity. |
| Get encounter | Get one visit or stay with its class, type, dates, participants and locations. |
| Get observation | Get one observation with its value, unit, range and components. |
| Get patient | Get one patient's demographics, identifiers, contact details and primary care clinicians. |
| Get server capabilities | Read what the Epic server supports: its FHIR version, the record types it offers with what can be done to each, and its sign-in addresses. |
| List allergies | List a patient's allergies and intolerances, optionally by status. |
| List conditions | List a patient's problems and diagnoses, optionally by category (problem list, encounter diagnosis, health concern) and status. |
| List encounters | List a patient's visits and stays, optionally within a date range. |
| List observations | List a patient's lab results, vital signs, social history and other observations, by category or code and optionally a date range. |
| Search patients | Find patients by name, date of birth, gender, identifier, phone or email. |
Get allergy
Get one allergy or intolerance with its substance, criticality and reactions.
Inputs
- Allergy ID
allergy_idtextRequired - The Epic FHIR id of the allergy, from 'List allergies' or an earlier step.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
allergyobject- The allergy
Example output
{
"allergy": {
"categories": [],
"clinical_status": "Active",
"criticality": "high",
"id": "eFvPVFSu3VkgYqLq2dRZ6mA3",
"onset": "",
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"reactions": [
{
"description": "",
"manifestations": [],
"severity": ""
}
],
"recorded_date": "",
"resource": {},
"substance": "Penicillin",
"type": "",
"verification_status": ""
}
}Get condition
Get one condition with its code, status, onset and severity.
Inputs
- Condition ID
condition_idtextRequired - The Epic FHIR id of the condition, from 'List conditions' or an earlier step.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
conditionobject- The condition
Example output
{
"condition": {
"abatement": "",
"asserter": "",
"categories": [
"Problem List Item"
],
"clinical_status": "Active",
"code": "Hypertension",
"codes": [
{
"code": "",
"display": "",
"system": ""
}
],
"encounter_id": "",
"id": "eQ6UUuMfvgpDKDlbwxs1xyg3",
"onset": "2019-05-01",
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"recorded_date": "",
"resource": {},
"severity": "",
"verification_status": ""
}
}Get encounter
Get one visit or stay with its class, type, dates, participants and locations.
Inputs
- Encounter ID
encounter_idtextRequired - The Epic FHIR id of the encounter, from 'List encounters' or an earlier step.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
encounterobject- The encounter
Example output
{
"encounter": {
"class_code": "AMB",
"class_display": "Ambulatory",
"discharge_disposition": "",
"id": "eHX3-LDi3bAfKO8dBHAnJzA3",
"locations": [],
"participants": [
{
"id": "",
"name": "",
"role": ""
}
],
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"period_end": "2024-03-04T09:30:00Z",
"period_start": "2024-03-04T09:00:00Z",
"reasons": [],
"resource": {},
"service_provider": "",
"status": "finished",
"types": []
}
}Get observation
Get one observation with its value, unit, range and components.
Inputs
- Observation ID
observation_idtextRequired - The Epic FHIR id of the observation, from 'List observations' or an earlier step.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
observationobject- The observation
Example output
{
"observation": {
"categories": [
"Laboratory"
],
"code": "Cholesterol, total",
"codes": [
{
"code": "",
"display": "",
"system": ""
}
],
"components": [
{
"code": "",
"unit": "",
"value_number": 1,
"value_text": ""
}
],
"effective": "2024-03-04T10:15:00Z",
"encounter_id": "",
"id": "eD.LxhHcgBr3-2SBwHwIpPg3",
"interpretation": "",
"issued": "",
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"performers": [],
"reference_range": "",
"resource": {},
"status": "final",
"unit": "mg/dL",
"value_number": 180,
"value_text": "180 mg/dL"
}
}Get patient
Get one patient's demographics, identifiers, contact details and primary care clinicians.
Inputs
- Patient ID
patient_idtextRequired - The Epic FHIR id of the patient, from 'Search patients' or an earlier step.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
patientobject- The patient
Example output
{
"patient": {
"active": true,
"address": {
"city": "",
"country": "",
"line": "",
"postal_code": "",
"state": ""
},
"birth_date": "1987-09-12",
"deceased": false,
"deceased_date": "",
"email": "",
"family": "Lopez",
"gender": "female",
"general_practitioner_ids": [],
"given": [
"Camila",
"Maria"
],
"id": "erXuFYUfucBZaryVksYEcMg3",
"identifiers": [
{
"system": "",
"type": "",
"value": ""
}
],
"language": "",
"managing_organization": "",
"marital_status": "",
"mrn": "203713",
"name": "Camila Maria Lopez",
"phone": "469-555-5555",
"resource": {}
}
}Get server capabilities
Read what the Epic server supports: its FHIR version, the record types it offers with what can be done to each, and its sign-in addresses. A quick way to check the connection works.
Inputs
None.
Outputs
authorize_urltext- The server's sign-in address, when it gives one
datetext- The date
fhir_versiontext- The FHIR version the server speaks, 4.0.1 for R4
formatslist- The formats the server answers in
publishertext- Who publishes the server
resourceslist- The record types the server supports
software_nametext- The server software
software_versiontext- The server software's version
token_urltext- The server's token address
Example output
{
"authorize_url": "",
"date": "",
"fhir_version": "4.0.1",
"formats": [
"application/fhir+json"
],
"publisher": "",
"resources": [
{
"interactions": [
"read",
"search-type"
],
"type": "Patient"
}
],
"software_name": "Epic",
"software_version": "",
"token_url": ""
}List allergies
List a patient's allergies and intolerances, optionally by status.
Inputs
- Patient ID
patient_idtextRequired - The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- Status
clinical_statustext - Only active, inactive or resolved records. All if empty.One of:
active,inactive,resolved. - Page size
limitnumber - How many records Epic returns per page, 1 to 100. Epic's own default applies if empty.From 1 to 100.
- Pages to read
max_pagesnumber - How many pages to read and join, 1 to 10. Defaults to 1. If Epic has more, 'next_page' continues from where this stopped.From 1 to 10.
- Next page
page_urltext - The 'next_page' from an earlier run of this step, to carry on from there. The search fields are then ignored.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
allergieslist- The allergies
countnumber- How many records this step returned
has_moretrue/false- True when Epic has more pages than were read
next_pagetext- Pass as 'Next page' to continue; empty on the last page
totalnumber- How many Epic says match in all, when it says
Example output
{
"allergies": [
{
"categories": [],
"clinical_status": "Active",
"criticality": "high",
"id": "eFvPVFSu3VkgYqLq2dRZ6mA3",
"onset": "",
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"reactions": [
{
"description": "",
"manifestations": [],
"severity": ""
}
],
"recorded_date": "",
"resource": {},
"substance": "Penicillin",
"type": "",
"verification_status": ""
}
],
"count": 1,
"has_more": false,
"next_page": "",
"total": 1
}List conditions
List a patient's problems and diagnoses, optionally by category (problem list, encounter diagnosis, health concern) and status.
Inputs
- Patient ID
patient_idtextRequired - The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- Category
categorytext - Only this kind of condition. All if empty.One of:
problem-list-item(Problem list),encounter-diagnosis(Encounter diagnosis),health-concern(Health concern). - Status
clinical_statustext - Only active, inactive or resolved records. All if empty.One of:
active,inactive,resolved. - Page size
limitnumber - How many records Epic returns per page, 1 to 100. Epic's own default applies if empty.From 1 to 100.
- Pages to read
max_pagesnumber - How many pages to read and join, 1 to 10. Defaults to 1. If Epic has more, 'next_page' continues from where this stopped.From 1 to 10.
- Next page
page_urltext - The 'next_page' from an earlier run of this step, to carry on from there. The search fields are then ignored.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
conditionslist- The conditions
countnumber- How many records this step returned
has_moretrue/false- True when Epic has more pages than were read
next_pagetext- Pass as 'Next page' to continue; empty on the last page
totalnumber- How many Epic says match in all, when it says
Example output
{
"conditions": [
{
"abatement": "",
"asserter": "",
"categories": [
"Problem List Item"
],
"clinical_status": "Active",
"code": "Hypertension",
"codes": [
{
"code": "",
"display": "",
"system": ""
}
],
"encounter_id": "",
"id": "eQ6UUuMfvgpDKDlbwxs1xyg3",
"onset": "2019-05-01",
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"recorded_date": "",
"resource": {},
"severity": "",
"verification_status": ""
}
],
"count": 1,
"has_more": false,
"next_page": "",
"total": 1
}List encounters
List a patient's visits and stays, optionally within a date range.
Inputs
- Patient ID
patient_idtextRequired - The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- On or after
from_datedate - Only records dated on or after this day.
- On or before
until_datedate - Only records dated on or before this day.
- Page size
limitnumber - How many records Epic returns per page, 1 to 100. Epic's own default applies if empty.From 1 to 100.
- Pages to read
max_pagesnumber - How many pages to read and join, 1 to 10. Defaults to 1. If Epic has more, 'next_page' continues from where this stopped.From 1 to 10.
- Next page
page_urltext - The 'next_page' from an earlier run of this step, to carry on from there. The search fields are then ignored.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
countnumber- How many records this step returned
encounterslist- The encounters
has_moretrue/false- True when Epic has more pages than were read
next_pagetext- Pass as 'Next page' to continue; empty on the last page
totalnumber- How many Epic says match in all, when it says
Example output
{
"count": 1,
"encounters": [
{
"class_code": "AMB",
"class_display": "Ambulatory",
"discharge_disposition": "",
"id": "eHX3-LDi3bAfKO8dBHAnJzA3",
"locations": [],
"participants": [
{
"id": "",
"name": "",
"role": ""
}
],
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"period_end": "2024-03-04T09:30:00Z",
"period_start": "2024-03-04T09:00:00Z",
"reasons": [],
"resource": {},
"service_provider": "",
"status": "finished",
"types": []
}
],
"has_more": false,
"next_page": "",
"total": 1
}List observations
List a patient's lab results, vital signs, social history and other observations, by category or code and optionally a date range. Reads one page unless more are asked for.
Inputs
- Patient ID
patient_idtextRequired - The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- Category
categorytext - Which kind of observation. Choose this or give a code.One of:
laboratory(Lab results),vital-signs(Vital signs),social-history(Social history (such as smoking)),survey(Surveys and questionnaires),exam(Exam findings),imaging. - Code
codetext - A code to find, such as the LOINC code 2093-3 (total cholesterol) or system|code. Choose this or a category.
- On or after
from_datedate - Only records dated on or after this day.
- On or before
until_datedate - Only records dated on or before this day.
- Page size
limitnumber - How many records Epic returns per page, 1 to 100. Epic's own default applies if empty.From 1 to 100.
- Pages to read
max_pagesnumber - How many pages to read and join, 1 to 10. Defaults to 1. If Epic has more, 'next_page' continues from where this stopped.From 1 to 10.
- Next page
page_urltext - The 'next_page' from an earlier run of this step, to carry on from there. The search fields are then ignored.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
countnumber- How many records this step returned
has_moretrue/false- True when Epic has more pages than were read
next_pagetext- Pass as 'Next page' to continue; empty on the last page
observationslist- The observations
totalnumber- How many Epic says match in all, when it says
Example output
{
"count": 1,
"has_more": false,
"next_page": "",
"observations": [
{
"categories": [
"Laboratory"
],
"code": "Cholesterol, total",
"codes": [
{
"code": "",
"display": "",
"system": ""
}
],
"components": [
{
"code": "",
"unit": "",
"value_number": 1,
"value_text": ""
}
],
"effective": "2024-03-04T10:15:00Z",
"encounter_id": "",
"id": "eD.LxhHcgBr3-2SBwHwIpPg3",
"interpretation": "",
"issued": "",
"patient_id": "erXuFYUfucBZaryVksYEcMg3",
"performers": [],
"reference_range": "",
"resource": {},
"status": "final",
"unit": "mg/dL",
"value_number": 180,
"value_text": "180 mg/dL"
}
],
"total": 1
}Search patients
Find patients by name, date of birth, gender, identifier, phone or email. Give at least one; Epic does not list every patient, and a name search needs a date of birth too.
Inputs
- Last name
familytext - The patient's family name. Give at least one thing to search by.
- First name
giventext - The patient's given name.
- Date of birth
birthdatedate - The patient's date of birth.
- Gender
gendertext - The patient's administrative gender.One of:
male,female,other,unknown. - Identifier
identifiertext - An identifier such as a medical record number. Epic wants the system too: system|value.
- Phone number
phonetext - A phone number on the patient's record.
- Email address
emailtext - An email address on the patient's record.
- Page size
limitnumber - How many records Epic returns per page, 1 to 100. Epic's own default applies if empty.From 1 to 100.
- Pages to read
max_pagesnumber - How many pages to read and join, 1 to 10. Defaults to 1. If Epic has more, 'next_page' continues from where this stopped.From 1 to 10.
- Next page
page_urltext - The 'next_page' from an earlier run of this step, to carry on from there. The search fields are then ignored.
- Include the full FHIR record
include_full_recordtrue/false - Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows.Default:
false.
Outputs
countnumber- How many records this step returned
has_moretrue/false- True when Epic has more pages than were read
next_pagetext- Pass as 'Next page' to continue; empty on the last page
patientslist- The matching patients
totalnumber- How many Epic says match in all, when it says
Example output
{
"count": 1,
"has_more": false,
"next_page": "",
"patients": [
{
"active": true,
"address": {
"city": "",
"country": "",
"line": "",
"postal_code": "",
"state": ""
},
"birth_date": "1987-09-12",
"deceased": false,
"deceased_date": "",
"email": "",
"family": "Lopez",
"gender": "female",
"general_practitioner_ids": [],
"given": [
"Camila",
"Maria"
],
"id": "erXuFYUfucBZaryVksYEcMg3",
"identifiers": [
{
"system": "",
"type": "",
"value": ""
}
],
"language": "",
"managing_organization": "",
"marital_status": "",
"mrn": "203713",
"name": "Camila Maria Lopez",
"phone": "469-555-5555",
"resource": {}
}
],
"total": 1
}