REST API v2

AI EHR API Reference

FHIR R4+ REST API for clinical documentation, patient management, interoperability, and AI WFM workforce integration.

API Base & Authentication

All API endpoints follow the FHIR R4+ RESTful conventions. Rate limits are enforced per API key with automatic exponential backoff handling.

// Base URL
https://api.aiehr.net/fhir/R4

// Authentication: OAuth 2.0 / SMART on FHIR
Authorization: Bearer <access_token>

// API Key (server-to-server)
X-API-Key: <your_api_key>

// Content Type
Content-Type: application/fhir+json
1,000
Requests / Minute
10,000
Enterprise / Minute
∞
Webhooks / Minute
POST /fhir/R4/auth/token
Obtain access token via OAuth 2.0 Authorization Code flow for SMART on FHIR app launch.
GET /fhir/R4/metadata FHIR Conformance
Retrieve server capabilities (CapabilityStatement). Lists supported resources, interactions, and search parameters.

Patient Resources

CRUD operations on Patient, Patient Link, and Bundle resources

GET /fhir/R4/Patient required name identifier gender birthdate address
Search and retrieve patient records. Supports full-text search, fuzzy matching, and FHIR search parameters including _total and _count for pagination.
// Search patients by name and state GET /fhir/R4/Patient?name=Johnson&address-state=TN&_count=25 // Response: FHIR Bundle { "resourceType": "Bundle", "type": "searchset", "total": 47, "entry": [{ "resource": { "resourceType": "Patient", "id": "patient-20260001", "identifier": [{"system": "http://hl7.org/fhir/sid/us-mrn", "value": "20260001"}], "name": [{"family": "Johnson", "given": ["Maria"]}], "gender": "female", "birthDate": "1985-03-15" } }] }
POST /fhir/R4/Patient required Patient resource
Create a new patient record. Returns the created resource with assigned ID.
// Create patient POST /fhir/R4/Patient { "resourceType": "Patient", "name": [{"family": "Chen", "given": ["Wei"]}], "gender": "male", "birthDate": "1978-11-02", "identifier": [{"system": "http://hl7.org/fhir/sid/us-mrn", "value": "auto-assign"}] }

Clinical Resources

Composition, DiagnosticReport, Observation, Condition, and MedicationRequest

POST /fhir/R4/Composition required Composition resource
Create clinical document (SOAP note, consult, discharge summary). Returns FHIR Composition with section entries mapped to associated resources.
// Create SOAP note via Composition POST /fhir/R4/Composition { "resourceType": "Composition", "status": "preliminary", "type": {"coding": [{"code": "11488-4", "display": "Consultation note"}]}, "subject": {"reference": "Patient/patient-20260001"}, "date": "2026-09-10T10:30:00Z", "section": [{ "title": "Assessment & Plan", "text": {"status": "additional", "div": "<p>...SOAP content...</p>"} }] }
GET /fhir/R4/Observation?patient={id}&code=&status=final AI WFM Sync
Retrieve lab results, vital signs, and clinical observations. AI WFM sync flag triggers staffing ratio correlation when enabled.
// Get patient observations (labs + vitals) GET /fhir/R4/Observation?patient=patient-20260001&category=vital-signs,lab&_sort=-date // AI WFM enhanced query with staffing correlation GET /fhir/R4/Observation?patient=patient-20260001&aiwfm-sync=true

Interoperability & Bulk Export

FHIR Bulk Data, batch transactions, and AI WFM workforce sync

POST /fhir/R4/$bulkdata-export Bulk Export
Initiate FHIR Bulk Data Export (R4+ $export). Returns export job status URL. Supports Patient, Practitioner, and Encounter resource exports.
// Bulk export all patients POST /fhir/R4/$bulkdata-export Content-Type: application/json { "type": ["Patient", "Practitioner", "Encounter"], "_type": "Patient" } // Response: 202 Accepted Location: /fhir/R4/$bulkdata-export/status/12345
POST /api/v2/settings/wfm-integration AI WFM Sync
Configure bidirectional sync between AI EHR and AI WFM. Controls which data fields sync, sync interval, and HIPAA compliance settings.
// Enable AI WFM workforce integration POST /api/v2/settings/wfm-integration { "enabled": true, "aiwfm_api_url": "https://api.aiwfm.net/v2", "aiwfm_api_key": "aiwfm-xxxx-xxxx", "sync_interval": "5m", "hipaa_compliant": true }

AI WFM Workforce Resources

Provider shift assignments, nurse-to-patient ratios, and coverage alerts from AI WFM

GET /api/v2/wfm/provider-shifts?provider_id={id} AI WFM Source
Retrieve provider shift assignments from AI WFM. Used by EHR to determine which providers are on-duty for specific locations and shifts.
// Get Dr. Chen's shifts for this week GET /api/v2/wfm/provider-shifts?provider_id=practitioner-001 { "shifts": [ {"date": "2026-09-14", "type": "day", "start": "07:00", "end": "19:00", "location": "Main Campus", "coverage": "verified"} ] }
GET /api/v2/wfm/nurse-ratios?location_id={id}&shift={shift_type} AI WFM Source
Query real-time nurse-to-patient ratios from AI WFM. Integrates with EHR clinical documentation to ensure adequate staffing before note finalization.
// Check nurse ratios for ICU Day Shift GET /api/v2/wfm/nurse-ratios?location_id=loc-icu-01&shift=day { "location": "ICU - Main Campus", "shift": "Day (07:00-19:00)", "current_ratio": 1.0, "required_ratio": 1.0, "status": "compliant", "nurses_on_duty": 6, "patients": 6, "coverage_alerts": [] }

Webhooks & Events

Real-time event notifications for clinical events, staffing changes, and compliance alerts

POST /api/v2/webhooks/register
Register webhook endpoint for real-time event notifications including clinical document events, AI WFM workforce events, and compliance alerts.
// Register webhooks POST /api/v2/webhooks/register { "url": "https://your-app.com/webhooks/aiehr", "events": [ "composition.created", "observation.updated", "patient.linked", "wfm.shift.changed", "wfm.ratio.violation", "wfm.credential.expiring", "mips.measure.scored" ], "secret": "your_webhook_secret" }