APIs & Interoperability Guide

Overview

Entheory.AI provides a comprehensive set of interfaces for data ingestion, clinical access, and system management. Our architecture is API-first, designed to interoperate seamlessly with existing hospital infrastructure (EMR, LIS, PACS) while providing modern RESTful endpoints for frontend applications.

---

1. Integration Standards

We support three primary integration patterns, powered by HAPI FHIR (Apache 2.0):

Standard	Protocol	Library	Use Case	Direction
REST API	HTTPS (JSON)	—	UI, Mobile Apps, Custom Integrations	Inbound/Outbound
FHIR R4	HTTPS (JSON)	HAPI FHIR	Interoperability with ABDM, PHR Apps	Outbound (Export)
HL7 v2	MLLP (TCP)	HAPI HL7v2	Legacy Hospital Systems (ADT, ORU)	Inbound (Ingest)

---

2. Authentication & Security

All API endpoints are secured using JWT (JSON Web Tokens).

Headers

Authorization: Bearer <token>
X-Hospital-ID: <hospital_id>

Authentication Flow

1. Login: POST /api/auth/login with credentials.
2. Receive Token: Server returns JWT (valid for 8 hours).
3. Use Token: Include in Authorization header for all subsequent requests.

Scopes & Permissions

• read:patient - View patient records
• write:patient - Update patient records (notes)
• ingest:data - Upload files/data (System accounts)
• admin:system - Manage users and config

---

3. Core REST API Reference

Patient Management

Get Patient List

GET /api/patients

Parameters: - page: Page number (default 1) - limit: Items per page (default 20) - search: Search by name or MRN - hasAlerts: Filter by active alerts (true/false)

Response:

{
  "data": [
    {
      "abhaId": "ABHA-1234",
      "name": "Priya Sharma",
      "age": 45,
      "diagnosis": "Breast Cancer",
      "lastVisit": "2024-12-01",
      "alerts": ["Critical Lab"]
    }
  ],
  "meta": { "total": 145, "page": 1 }
}

Get Patient Details (Canonical Bundle)

GET /api/patients/:abhaId

Returns the full longitudinal record.

Response:

{
  "patientId": "case_001",
  "demographics": { ... },
  "timeline": [ ... ],
  "labs": [ ... ]
}

Clinical Data Ingestion

Upload Document (OCR)

POST /api/upload/document

Content-Type: multipart/form-data

Body: - file: (Binary PDF/Image) - patientId: (String) - documentType: (String) "discharge_summary" | "lab_report"

Response:

{
  "jobId": "ocr_123",
  "status": "queued",
  "estimatedTime": "30s"
}

Upload Audio (ASR)

POST /api/upload/audio

Content-Type: multipart/form-data

Body: - file: (Binary MP3/WAV) - language: "hi-IN" | "en-IN"

---

4. FHIR R4 Interoperability

We provide an on-demand FHIR facade using HAPI FHIR that transforms our internal canonical bundles into standard FHIR resources.

Get Patient Bundle

GET /api/patients/:abhaId?format=fhir

Response: Bundle (type: collection) containing: - Patient - Condition (Diagnosis) - Observation (Labs, Vitals) - ImagingStudy - DiagnosticReport

Resource Mapping

Entheory Entity	FHIR Resource	Profile
Patient Info	Patient	ABDM Patient Profile
Lab Result	Observation	General Observation
Imaging	ImagingStudy	ImagingStudy
Clinical Note	DocumentReference	-
Medication	MedicationStatement	-

---

5. HL7 v2 Integration (Legacy)

For hospitals using legacy EMRs, we run a TCP MLLP Listener powered by HAPI HL7v2.

Port: 2575 (Default)

Supported Message Types

ADT (Admission, Discharge, Transfer)

• ADT^A01: Admit/Visit Notification (Creates/Updates Patient)
• ADT^A03: Discharge (Updates Timeline)
• ADT^A08: Update Patient Information

ORU (Observation Result)

• ORU^R01: Unsolicited transmission of an observation message (Lab Results)
• Segments Processed: MSH, PID, OBR, OBX

Example Flow: 1. LIS sends ORU^R01. 2. Listener parses PID to find Patient. 3. Listener parses OBX segments for Lab Values. 4. System updates Canonical Bundle. 5. Listener sends ACK.

---

6. Webhooks & Events

External systems can subscribe to events via webhooks.

Configuration

POST /api/webhooks

{
  "url": "https://hospital-emr.com/callback",
  "events": ["patient.updated", "alert.critical"]
}

Event Payloads

Critical Alert

{
  "event": "alert.critical",
  "timestamp": "2024-12-03T10:00:00Z",
  "data": {
    "patientId": "ABHA-1234",
    "alertType": "Critical Lab",
    "message": "Hemoglobin 6.5 g/dL"
  }
}

---

7. Error Handling

We use standard HTTP status codes.

Code	Meaning	Description
200	OK	Request succeeded.
202	Accepted	Async job started (Ingestion/OCR).
400	Bad Request	Invalid parameters or schema validation failed.
401	Unauthorized	Missing or invalid JWT.
403	Forbidden	Insufficient permissions.
404	Not Found	Patient or resource not found.
429	Too Many Requests	Rate limit exceeded.
500	Internal Error	Server-side failure.

Error Response Body:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid ABHA ID format",
    "details": ["Must be 14 digits"]
  }
}