OpenEMR (openemr/openemr)

OpenEMR

https://github.com/openemr/openemr
Admin
OpenEMR is a free and open-source electronic health records and medical practice management...

Tokens:235,991
Snippets:3,059
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# OpenEMR

OpenEMR is a free and open source electronic health records (EHR) and medical practice management application. It provides fully integrated electronic health records, practice management, scheduling, electronic billing, internationalization support, and comprehensive REST/FHIR APIs for healthcare application integration. OpenEMR is ONC certified and compliant with HIPAA, US Core 8.0, SMART on FHIR v2.2.0, and FHIR R4 standards.

The platform supports multiple deployment options including Docker-based development environments and runs on Windows, Linux, and Mac OS X. OpenEMR provides two primary API interfaces: a Standard REST API for native OpenEMR operations and a FHIR R4 API for healthcare interoperability. Both APIs use OAuth 2.0 with OpenID Connect for authentication and support granular scope-based access control for secure patient data access.

## OAuth 2.0 Client Registration

Register your application to obtain OAuth 2.0 credentials for API access. All API requests require authentication via Bearer tokens obtained through the OAuth 2.0 authorization flow.

```bash
# Register a new OAuth 2.0 client application
curl -X POST -k -H 'Content-Type: application/json' \
  https://localhost:9300/oauth2/default/registration \
  --data '{
    "application_type": "private",
    "redirect_uris": ["https://client.example.org/callback"],
    "post_logout_redirect_uris": ["https://client.example.org/logout/callback"],
    "client_name": "My Healthcare App",
    "token_endpoint_auth_method": "client_secret_post",
    "contacts": ["admin@example.org"],
    "scope": "openid offline_access api:oemr api:fhir user/Patient.read user/Observation.read"
  }'

# Response contains client credentials (save securely):
# {
#   "client_id": "LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA",
#   "client_secret": "j21ecvLmFi9HPc_Hv0t7Ptmf1pVcZQLtHjIdU7U9tkS9WAjFJwVM...",
#   "registration_access_token": "uiDSXx2GNSvYy5n8eW50aGrJz0HjaGpUdrGf07Agv_Q",
#   "client_id_issued_at": 1604767861,
#   "scope": "openid offline_access api:oemr api:fhir user/Patient.read..."
# }
```

## Authorization Code Grant Flow

The recommended OAuth 2.0 flow for web and mobile applications. Redirects users to OpenEMR for authentication, then exchanges the authorization code for access tokens.

```bash
# Step 1: Redirect user to authorization endpoint (construct URL in your app)
# GET https://localhost:9300/oauth2/default/authorize?
#   response_type=code&
#   client_id=YOUR_CLIENT_ID&
#   redirect_uri=https://client.example.org/callback&
#   scope=openid%20offline_access%20patient/Patient.read%20patient/Observation.read&
#   state=RANDOM_STATE_STRING&
#   aud=https://localhost:9300/apis/default/fhir

# Step 2: After user approves, exchange authorization code for tokens
curl -X POST -k \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  https://localhost:9300/oauth2/default/token \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'redirect_uri=https://client.example.org/callback' \
  --data-urlencode 'code=def50200a8f...'

# Response:
# {
#   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
#   "refresh_token": "def5020017b484b0add020bf3491a8a537fa04eda12...",
#   "scope": "openid offline_access patient/Patient.read patient/Observation.read"
# }
```

## Refresh Token Grant

Obtain new access tokens without re-authentication using the refresh token (requires `offline_access` scope in original authorization).

```bash
# Refresh access token when it expires
curl -X POST -k \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  https://localhost:9300/oauth2/default/token \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'refresh_token=def5020017b484b0add020bf3491a8a537fa04eda12...'

# Response includes new access_token and refresh_token:
# {
#   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
#   "refresh_token": "def5020089a766d16..."
# }
```

## Client Credentials Grant (Backend Services)

For backend services and bulk data operations using asymmetric authentication with JWKS. Required for system-level scopes.

```bash
# Create signed JWT assertion (RS384 algorithm required)
# JWT Header: {"alg": "RS384", "kid": "my-key-1", "typ": "JWT"}
# JWT Claims: {
#   "iss": "YOUR_CLIENT_ID",
#   "sub": "YOUR_CLIENT_ID",
#   "aud": "https://localhost:9300/oauth2/default/token",
#   "exp": 1609459200,
#   "jti": "unique-jwt-id-12345",
#   "iat": 1609455600
# }

# Request token using client assertion
curl -X POST -k \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  https://localhost:9300/oauth2/default/token \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=eyJhbGciOiJSUzM4NCIsImtpZCI6Im15LWtleS0xIiwidHlwIjoiSldUIn0...' \
  --data-urlencode 'scope=system/Patient.read system/Group.$export'

# Response (short-lived 60-second token):
# {
#   "token_type": "Bearer",
#   "expires_in": 60,
#   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
#   "scope": "system/Patient.read system/Patient.$export"
# }
```

## FHIR Capability Statement

Discover the FHIR server's capabilities, supported resources, and operations. No authentication required.

```bash
# Get FHIR server capability statement
curl -X GET 'https://localhost:9300/apis/default/fhir/metadata' \
  -H 'Accept: application/fhir+json'

# Response excerpt showing supported resources and operations:
# {
#   "resourceType": "CapabilityStatement",
#   "status": "active",
#   "fhirVersion": "4.0.1",
#   "software": {"name": "OpenEMR", "version": "7.0.4"},
#   "rest": [{
#     "mode": "server",
#     "resource": [{
#       "type": "Patient",
#       "interaction": [{"code": "create"}, {"code": "read"}, {"code": "search-type"}],
#       "searchParam": [
#         {"name": "_id", "type": "token"},
#         {"name": "name", "type": "string"},
#         {"name": "birthdate", "type": "date"}
#       ]
#     }]
#   }]
# }
```

## FHIR Patient Resource

Read and search patient demographics using the FHIR R4 Patient resource. Compliant with US Core Patient profile.

```bash
# Get single patient by ID
curl -X GET 'https://localhost:9300/apis/default/fhir/Patient/123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Search patients by name and birthdate
curl -X GET 'https://localhost:9300/apis/default/fhir/Patient?name=Smith&birthdate=1980-01-15' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Search with multiple parameters
curl -X GET 'https://localhost:9300/apis/default/fhir/Patient?family=Smith&given=John&address-city=Boston' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Response:
# {
#   "resourceType": "Patient",
#   "id": "123",
#   "name": [{"family": "Smith", "given": ["John"]}],
#   "birthDate": "1980-01-15",
#   "gender": "male",
#   "address": [{"city": "Boston", "state": "MA", "postalCode": "12345"}]
# }
```

## FHIR Observation Resource

Access clinical observations including vital signs, lab results, and social history data.

```bash
# Get vital signs for a patient
curl -X GET 'https://localhost:9300/apis/default/fhir/Observation?patient=123&category=vital-signs' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Get laboratory results
curl -X GET 'https://localhost:9300/apis/default/fhir/Observation?patient=123&category=laboratory' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Get observations with date filter and provenance
curl -X GET 'https://localhost:9300/apis/default/fhir/Observation?patient=123&category=vital-signs&date=ge2024-01-01&_revinclude=Provenance:target' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Response (vital sign example):
# {
#   "resourceType": "Observation",
#   "id": "456",
#   "status": "final",
#   "category": [{"coding": [{"code": "vital-signs"}]}],
#   "code": {"coding": [{"system": "http://loinc.org", "code": "8867-4", "display": "Heart rate"}]},
#   "subject": {"reference": "Patient/123"},
#   "valueQuantity": {"value": 72, "unit": "beats/minute"}
# }
```

## FHIR Condition Resource

Manage patient conditions including problem list items, health concerns, and diagnoses.

```bash
# Get active problems for a patient
curl -X GET 'https://localhost:9300/apis/default/fhir/Condition?patient=123&clinical-status=active' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Get problem list items
curl -X GET 'https://localhost:9300/apis/default/fhir/Condition?patient=123&category=problem-list-item' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Get health concerns
curl -X GET 'https://localhost:9300/apis/default/fhir/Condition?patient=123&category=health-concern' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Response:
# {
#   "resourceType": "Condition",
#   "id": "789",
#   "clinicalStatus": {"coding": [{"code": "active"}]},
#   "category": [{"coding": [{"code": "problem-list-item"}]}],
#   "code": {"coding": [{"system": "http://snomed.info/sct", "code": "44054006", "display": "Diabetes mellitus type 2"}]},
#   "subject": {"reference": "Patient/123"},
#   "onsetDateTime": "2020-03-15"
# }
```

## FHIR MedicationRequest Resource

Access patient medication orders and prescriptions.

```bash
# Get active medications for a patient
curl -X GET 'https://localhost:9300/apis/default/fhir/MedicationRequest?patient=123&status=active' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Get all medications
curl -X GET 'https://localhost:9300/apis/default/fhir/MedicationRequest?patient=123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Response:
# {
#   "resourceType": "MedicationRequest",
#   "id": "101",
#   "status": "active",
#   "intent": "order",
#   "medicationCodeableConcept": {"coding": [{"display": "Metformin 500mg"}]},
#   "subject": {"reference": "Patient/123"},
#   "dosageInstruction": [{"text": "Take 1 tablet twice daily"}]
# }
```

## FHIR AllergyIntolerance Resource

Access patient allergy and intolerance information.

```bash
# Get all allergies for a patient
curl -X GET 'https://localhost:9300/apis/default/fhir/AllergyIntolerance?patient=123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Response:
# {
#   "resourceType": "AllergyIntolerance",
#   "id": "201",
#   "clinicalStatus": {"coding": [{"code": "active"}]},
#   "code": {"coding": [{"display": "Penicillin"}]},
#   "patient": {"reference": "Patient/123"},
#   "reaction": [{"manifestation": [{"coding": [{"display": "Hives"}]}], "severity": "severe"}]
# }
```

## FHIR Encounter Resource

Access patient encounters and visits.

```bash
# Get encounters for a patient
curl -X GET 'https://localhost:9300/apis/default/fhir/Encounter?patient=123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Get encounters within date range
curl -X GET 'https://localhost:9300/apis/default/fhir/Encounter?patient=123&date=ge2024-01-01&date=le2024-03-31' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json'

# Response:
# {
#   "resourceType": "Encounter",
#   "id": "301",
#   "status": "finished",
#   "class": {"code": "AMB", "display": "ambulatory"},
#   "subject": {"reference": "Patient/123"},
#   "period": {"start": "2024-01-15T09:00:00Z", "end": "2024-01-15T09:30:00Z"}
# }
```

## FHIR DocumentReference $docref Operation

Generate Continuity of Care Documents (CCD) on demand for patient data exchange.

```bash
# Generate CCD for a patient
curl -X POST 'https://localhost:9300/apis/default/fhir/DocumentReference/$docref' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/fhir+json' \
  --data '{
    "resourceType": "Parameters",
    "parameter": [
      {"name": "patient", "valueId": "123"}
    ]
  }'

# Generate CCD for specific date range
curl -X POST 'https://localhost:9300/apis/default/fhir/DocumentReference/$docref' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/fhir+json' \
  --data '{
    "resourceType": "Parameters",
    "parameter": [
      {"name": "patient", "valueId": "123"},
      {"name": "start", "valueDate": "2024-01-01"},
      {"name": "end", "valueDate": "2024-12-31"}
    ]
  }'

# Response returns DocumentReference with Binary URL to download CCD XML:
# {
#   "resourceType": "Bundle",
#   "type": "searchset",
#   "entry": [{
#     "resource": {
#       "resourceType": "DocumentReference",
#       "content": [{"attachment": {"contentType": "application/xml", "url": "https://localhost:9300/apis/default/fhir/Binary/98765"}}]
#     }
#   }]
# }

# Download the CCD XML file
curl -X GET 'https://localhost:9300/apis/default/fhir/Binary/98765' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -o patient-ccd.xml
```

## Bulk FHIR Export

Export large datasets for analytics and population health using the FHIR Bulk Data specification.

```bash
# Initiate Patient compartment bulk export
curl -X GET 'https://localhost:9300/apis/default/fhir/Patient/$export' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json' \
  -H 'Prefer: respond-async'
# Response: HTTP 202 Accepted with Content-Location header for status polling

# Initiate Group export (patients for specific practitioner)
curl -X GET 'https://localhost:9300/apis/default/fhir/Group/1/$export' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json' \
  -H 'Prefer: respond-async'

# Filter by resource type and date
curl -X GET 'https://localhost:9300/apis/default/fhir/Patient/$export?_type=Patient,Observation,Condition&_since=2024-01-01T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/fhir+json' \
  -H 'Prefer: respond-async'

# Check export status (poll Content-Location URL)
curl -X GET 'https://localhost:9300/apis/default/fhir/$bulkdata-status?job=92a94c00-77d6-4dfc-ae3b' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# When complete, download NDJSON files from output URLs:
# {"output": [{"type": "Patient", "url": "https://localhost:9300/apis/default/fhir/Binary/97552"}]}
curl -X GET 'https://localhost:9300/apis/default/fhir/Binary/97552' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -o patients.ndjson
```

## Standard REST API - Patient Management

Create and manage patients using the OpenEMR Standard REST API for native operations.

```bash
# Create a new patient
curl -X POST 'https://localhost:9300/apis/default/api/patient' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "title": "Mr",
    "fname": "John",
    "lname": "Smith",
    "DOB": "1980-01-15",
    "sex": "Male",
    "street": "123 Main St",
    "city": "Boston",
    "state": "MA",
    "postal_code": "12345",
    "phone_home": "555-1234",
    "email": "john.smith@example.com"
  }'

# Search patients
curl -X GET 'https://localhost:9300/apis/default/api/patient?lname=Smith&city=Boston' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# Get patient by UUID
curl -X GET 'https://localhost:9300/apis/default/api/patient/90cde167-7b9b-4ed1-bd55-533925cb2605' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# Response format:
# {
#   "validationErrors": [],
#   "internalErrors": [],
#   "data": {"id": "1", "uuid": "90cde167-7b9b-4ed1-bd55-533925cb2605", "fname": "John", "lname": "Smith"}
# }
```

## Standard REST API - Encounters and Clinical Data

Manage patient encounters, vitals, allergies, and other clinical data.

```bash
# Get patient encounters
curl -X GET 'https://localhost:9300/apis/default/api/patient/90cde167-7b9b-4ed1-bd55-533925cb2605/encounter' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# Add allergy to patient
curl -X POST 'https://localhost:9300/apis/default/api/patient/90cde167-7b9b-4ed1-bd55-533925cb2605/allergy' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "title": "Penicillin",
    "begdate": "2020-01-15",
    "diagnosis": "Allergy to penicillin",
    "severity_al": "severe",
    "reaction": "Hives"
  }'

# Record patient vitals
curl -X POST 'https://localhost:9300/apis/default/api/patient/90cde167-7b9b-4ed1-bd55-533925cb2605/vital' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "date": "2024-01-15",
    "bps": "120",
    "bpd": "80",
    "weight": "180",
    "height": "70",
    "temperature": "98.6",
    "pulse": "72",
    "respiration": "16"
  }'

# Upload patient document
curl -X POST 'https://localhost:9300/apis/default/api/patient/90cde167-7b9b-4ed1-bd55-533925cb2605/document' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -F 'file=@/path/to/lab-results.pdf' \
  -F 'path=Lab Reports' \
  -F 'date=2024-01-15'
```

## Standard REST API - Appointments

Create and manage patient appointments.

```bash
# Create appointment
curl -X POST 'https://localhost:9300/apis/default/api/appointment' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "pc_catid": "5",
    "pc_title": "Annual Physical",
    "pc_duration": "1800",
    "pc_eventDate": "2024-02-15",
    "pc_startTime": "09:00:00",
    "pc_facility": "1",
    "pid": "1"
  }'

# Get appointments
curl -X GET 'https://localhost:9300/apis/default/api/appointment' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

## Token Introspection

Validate token status and inspect token metadata for audit and compliance purposes.

```bash
# Introspect access token
curl -X POST -k \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic BASE64(client_id:client_secret)' \
  https://localhost:9300/oauth2/default/introspect \
  --data-urlencode 'token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...'

# Response for active token:
# {
#   "active": true,
#   "scope": "openid patient/Patient.read patient/Observation.read",
#   "client_id": "LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA",
#   "token_type": "Bearer",
#   "exp": 1640000000,
#   "sub": "user-uuid-12345"
# }

# Response for inactive/expired token:
# {"active": false}
```

## Summary

OpenEMR provides comprehensive REST and FHIR APIs for healthcare application integration. The FHIR R4 API supports 30+ resources including Patient, Observation, Condition, MedicationRequest, AllergyIntolerance, Encounter, and more, with full compliance to US Core 8.0 and SMART on FHIR v2.2.0 standards. Key operations include bulk data export for population health analytics, CCD document generation via the $docref operation, and granular scope-based access control. The Standard REST API provides direct access to OpenEMR's native data structures for administrative functions and legacy integrations.

Integration patterns typically involve registering an OAuth 2.0 client, implementing the authorization code grant flow for user-facing applications or client credentials for backend services, and then accessing FHIR resources with appropriate scopes. For new healthcare applications, the FHIR API is recommended for better interoperability, while the Standard API serves OpenEMR-specific workflows and administrative tasks. All APIs require HTTPS/TLS and support interactive testing via the built-in Swagger UI at `/swagger/`.