Epic FHIR API: Integration Guide: Complete Patient Guide | W

Epic FHIR API: Integration Guide

Epic Systems is one of the largest EHR vendors in the United States. Their FHIR API enables developers to build applications that integrate with Epic instances at healthcare organizations.

Getting Started

1. Developer Registration

1. Visit Epic Developers
2. Create an account
3. Apply for API access
4. Complete verification process
5. Accept terms of use

2. Sandbox Access

After registration:

• Request access to the Epic sandbox
• Choose the appropriate module(s):
  • Epic Hyperspace (inpatient)
  • Epic Ambulatory (outpatient)
  • Epic MyChart (patient portal)
  • Epic Care Everywhere (interoperability)

Authentication

OAuth 2.0 Flow

Epic uses standard OAuth 2.0 with SMART on FHIR:

1. App redirects to Epic auth
   ↓
2. User authenticates with Epic credentials
   ↓
3. User grants consent
   ↓
4. Epic redirects with authorization code
   ↓
5. App exchanges code for access token
   ↓
6. App uses access token to call FHIR API

Token Endpoints

// Production token endpoint
POST https://{instance_id}.api.epic.com/oauth2/token

// Sandbox token endpoint
POST https://fhir.epic.com/interconnect-fhir-public/oauth2/token

Key Endpoints

Patient Demographics

# Get patient by ID
GET /Patient/{id}

# Search for patient
GET /Patient?given-name=John&family-name=Smith

# Get patient by identifier (MRN)
GET /Patient?identifier=MRN|123456

Conditions and Problems

# Get all conditions for a patient
GET /Condition?patient={patient_id}

# Get active conditions only
GET /Condition?patient={patient_id}&clinical-status=active

# Get conditions by code
GET /Condition?code=73211009  # Diabetes mellitus (SNOMED CT)

Medications

# Get medication statements
GET /MedicationStatement?patient={patient_id}

# Get medication orders
GET /MedicationRequest?patient={patient_id}

Lab Results

# Get observations (lab results)
GET /Observation?patient={patient_id}

# Get lab results by LOINC code
GET /Observation?patient={patient_id}&code=2093-3  # Glucose

# Get diagnostic reports
GET /DiagnosticReport?patient={patient_id}

Epic-Specific Features

FHIR Data Schema

Epic extends FHIR with custom extensions:

| Extension | Purpose | |-----------|---------| | http://epic.com/Fhir/StructureDefinition/patient-identification-extension | Patient identifiers | | http://epic.com/Fhir/StructureDefinition/encounter-reference-extension | Encounter references | | http://epic.com/Fhir/StructureDefinition/department-extension | Department information |

Bulk Data Export

Epic supports FHIR Bulk Data Export:

# Kick off bulk export
POST /Group/{id}/$export
Content-Type: application/fhir+json
Accept: application/fhir+json

# Output format
[patient.ndjson, condition.ndjson, observation.ndjson, ...]

Development Environment

Sandbox URL Structure

Base URL: https://fhir.epic.com/interconnect-fhir-public/api/FHIR/DSTU2/

Endpoints:
- /Patient
- /Condition
- /Observation
- /MedicationStatement
- /DiagnosticReport

Mock Data

The Epic sandbox provides:

• ~100 mock patients
• Complete clinical records
• Various clinical scenarios

Production Considerations

Instance URLs

Each organization has a unique base URL:

https://{instance_id}.api.epic.com/FHIR/DSTU2/
https://{instance_id}.api.epic.com/FHIR/R4/

Rate Limiting

| Plan | Requests/Minute | Requests/Day | |------|-----------------|--------------| | Sandbox | 10,000 | 1,000,000 | | Production | Varies by contract | Varies by contract |

Support Access

Production access requires:

• Signed business associate agreement (BAA)
• Configuration from organization's Epic administrator
• Network allowlisting of your servers

Best Practices

1. Handle Pagination

async function getAllObservations(patientId) {
  let observations = [];
  let url = `/Observation?patient=${patientId}&_count=50`;

  while (url) {
    const response = await fetch(url);
    const bundle = await response.json();
    observations.push(...bundle.entry);
    url = bundle.link?.find(l => l.relation === 'next')?.url;
  }

  return observations;
}

2. Implement Token Refresh

async function refreshToken(refreshToken) {
  const response = await fetch(tokenEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken
    })
  });
  return await response.json();
}

3. Error Handling

async function epicFetch(url, options) {
  const response = await fetch(url, options);

  if (response.status === 401) {
    // Token expired - refresh
    await refreshAccessToken();
    return await fetch(url, options);
  }

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.issue?.[0]?.details?.text || 'Unknown error');
  }

  return response;
}

Testing Tools

Epic Developer Tools

1. Epic Hyperspace Sandbox: Browser-based testing
2. Postman collections: Pre-configured API calls
3. Smart launcher: Test SMART on FHIR apps
4. Code samples: Available in multiple languages

Certifications

Epic offers two certification levels:

| Level | Name | Requirements | |-------|------|--------------| | 1 | Ambulatory | 40 test cases | | 2 | Inpatient | 40 test cases |

Benefits of certification:

• Preferred vendor status
• Direct organization access
• Marketing opportunities

Common Issues

Issue: Invalid Scope

Solution: Verify requested scopes against organization's authorization

Issue: Token Expired

Solution: Implement automatic token refresh before expiration

Issue: Resource Not Found

Solution: Verify resource ID and organization-specific extensions

Summary

Key takeaways:

• Start with sandbox for development
• Register with Epic Developers for access
• Use standard SMART on FHIR flow
• Consider certification for production
• Implement proper error handling and token refresh

Resources:

• Epic Developers
• Epic FHIR Documentation
• SMART on FHIR