# Epic on FHIR

> 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.

App · 11 actions. Web page: https://docs.lodol.com/docs/integrations/epic-on-fhir

## Actions

### Get allergy

Get one allergy or intolerance with its substance, criticality and reactions.

**Inputs**

- Allergy ID (`allergy_id`, text, required): The Epic FHIR id of the allergy, from 'List allergies' or an earlier step.
- Include the full FHIR record (`include_full_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `allergy` (object): The allergy

**Example output**

```json
{
  "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_id`, text, required): The Epic FHIR id of the condition, from 'List conditions' or an earlier step.
- Include the full FHIR record (`include_full_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `condition` (object): The condition

**Example output**

```json
{
  "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_id`, text, required): The Epic FHIR id of the encounter, from 'List encounters' or an earlier step.
- Include the full FHIR record (`include_full_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `encounter` (object): The encounter

**Example output**

```json
{
  "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_id`, text, required): The Epic FHIR id of the observation, from 'List observations' or an earlier step.
- Include the full FHIR record (`include_full_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `observation` (object): The observation

**Example output**

```json
{
  "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_id`, text, required): The Epic FHIR id of the patient, from 'Search patients' or an earlier step.
- Include the full FHIR record (`include_full_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `patient` (object): The patient

**Example output**

```json
{
  "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_url` (text): The server's sign-in address, when it gives one
- `date` (text): The date
- `fhir_version` (text): The FHIR version the server speaks, 4.0.1 for R4
- `formats` (list): The formats the server answers in
- `publisher` (text): Who publishes the server
- `resources` (list): The record types the server supports
- `software_name` (text): The server software
- `software_version` (text): The server software's version
- `token_url` (text): The server's token address

**Example output**

```json
{
  "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_id`, text, required): The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- Status (`clinical_status`, text): Only active, inactive or resolved records. All if empty. One of: `active`, `inactive`, `resolved`.
- Page size (`limit`, number): 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_pages`, number): 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_url`, text): 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_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `allergies` (list): The allergies
- `count` (number): How many records this step returned
- `has_more` (true/false): True when Epic has more pages than were read
- `next_page` (text): Pass as 'Next page' to continue; empty on the last page
- `total` (number): How many Epic says match in all, when it says

**Example output**

```json
{
  "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_id`, text, required): The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- Category (`category`, text): 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_status`, text): Only active, inactive or resolved records. All if empty. One of: `active`, `inactive`, `resolved`.
- Page size (`limit`, number): 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_pages`, number): 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_url`, text): 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_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `conditions` (list): The conditions
- `count` (number): How many records this step returned
- `has_more` (true/false): True when Epic has more pages than were read
- `next_page` (text): Pass as 'Next page' to continue; empty on the last page
- `total` (number): How many Epic says match in all, when it says

**Example output**

```json
{
  "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_id`, text, required): The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- On or after (`from_date`, date): Only records dated on or after this day.
- On or before (`until_date`, date): Only records dated on or before this day.
- Page size (`limit`, number): 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_pages`, number): 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_url`, text): 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_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `count` (number): How many records this step returned
- `encounters` (list): The encounters
- `has_more` (true/false): True when Epic has more pages than were read
- `next_page` (text): Pass as 'Next page' to continue; empty on the last page
- `total` (number): How many Epic says match in all, when it says

**Example output**

```json
{
  "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_id`, text, required): The patient's Epic FHIR id, from 'Search patients' or an earlier step (the sandbox's Camila Lopez is erXuFYUfucBZaryVksYEcMg3).
- Category (`category`, text): 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 (`code`, text): 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_date`, date): Only records dated on or after this day.
- On or before (`until_date`, date): Only records dated on or before this day.
- Page size (`limit`, number): 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_pages`, number): 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_url`, text): 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_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `count` (number): How many records this step returned
- `has_more` (true/false): True when Epic has more pages than were read
- `next_page` (text): Pass as 'Next page' to continue; empty on the last page
- `observations` (list): The observations
- `total` (number): How many Epic says match in all, when it says

**Example output**

```json
{
  "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 (`family`, text): The patient's family name. Give at least one thing to search by.
- First name (`given`, text): The patient's given name.
- Date of birth (`birthdate`, date): The patient's date of birth.
- Gender (`gender`, text): The patient's administrative gender. One of: `male`, `female`, `other`, `unknown`.
- Identifier (`identifier`, text): An identifier such as a medical record number. Epic wants the system too: system|value.
- Phone number (`phone`, text): A phone number on the patient's record.
- Email address (`email`, text): An email address on the patient's record.
- Page size (`limit`, number): 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_pages`, number): 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_url`, text): 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_record`, true/false): Also return each untouched FHIR resource, under 'resource'. Off by default: the fields already returned cover most workflows. Default: `false`.

**Outputs**

- `count` (number): How many records this step returned
- `has_more` (true/false): True when Epic has more pages than were read
- `next_page` (text): Pass as 'Next page' to continue; empty on the last page
- `patients` (list): The matching patients
- `total` (number): How many Epic says match in all, when it says

**Example output**

```json
{
  "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
}
```
