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¶

Login: POST /api/auth/login with credentials.
Receive Token: Server returns JWT (valid for 8 hours).
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:

LIS sends ORU^R01.
Listener parses PID to find Patient.
Listener parses OBX segments for Lab Values.
System updates Canonical Bundle.
Listener sends ACK.

4.4 National Standards Alignment: The NRC/ABDM Framework¶

Entheory.AI's interoperability engine is strictly aligned with the standards finalized by the National Resource Centre for EHR Standards (NRC) for India.

The 7 Available Care Contexts¶

Our platform supports the mandatory classification of clinical data into India's core Care Contexts for record linkage: 1. OPD: Outpatient consultations and summaries. 2. IPD: Inpatient admission and discharge records. 3. Diagnostic: Laboratory and imaging reports. 4. Immunization: Vaccination records and certificates. 5. Prescription: Digital medication and treatment orders. 6. Wellness: Telemetry, wearable, and fitness data. 7. Pharmacy: Medication purchase and billing invoices.

The Unique ABHA Constraint¶

To ensure national-scale data integrity, Entheory.AI enforces the Unique ABHA Number constraint: - Single ID Persistence: Multiple ABHA numbers are not possible for a single individual. The ABHA serves as the unique, immutable primary key for patient discovery across the ecosystem. - De-duplication: Our de-duplication engines prioritize the ABHA number as the ultimate source of truth for record consolidation.

Mandatory FHIR R4 Mandate¶

To ensure integration readiness with the ABDM Health Information Exchange (HIE): - Standard: All internal clinical resources are mapped to HL7 FHIR R4. - NRC Compliance: We adhere to the FHIR Profiles and Implementation Guides (IGs) finalized by NRCeS for the Indian context. - Resource Modeling: Every data point—from a blood pressure reading to a pathology find—is treated as a "Digital Resource" with a unique identifier, subject, and context, following the ABDM resource body definition.

Facility-Specific Interoperability Paths¶

Entheory.AI recognizes that healthcare facilities have varying levels of digital maturity. Our platform supports specific integration paths to ensure inclusivity: - Tier-1 Enterprise Systems: Full-fledged HL7 FHIR R4 integration for hospitals with established EMRs. - Lightweight EMR Connectors: Specialized connectors for micro-EMR and lightweight platforms (e.g., eSushrut, eKa Care). These paths prioritize essential ABDM compliance (Care Context linking, ABHA discovery) while minimizing implementation complexity for small and medium facilities. - Fiduciary Responsibility Interface: A dedicated clinical interface to ensure that even without a complex EMR, the hospital (as the fiduciary) can accurately populate clinical records for patient retrieval via the national HIE.

Transactional Discovery & Ephemeral Records¶

In alignment with the national shift toward a discovery-led PHR model (the "Google Pay" for Health architecture), Entheory.AI's interoperability engine prioritizes transactional efficiency over monolithic storage: - Discovery Orchestration: Our engine focuses on the secure routing and discovery of data across the ABDM nodes, rather than assuming all clinical blocks must reside in a central cloud locker. - Ephemeral Record Management: To respect the 1GB storage constraints of platforms like DigiLocker, our connector handles heavy clinical assets (e.g., DICOM images, large IPD summaries) as "Fetched Transactions"—optimizing for real-time access and viewing rather than persistent duplication into a patient's limited cloud storage. - Semantic Continuity: Even when data is handled transitionally, we maintain the searchability and semantic tagging of the record to ensure the patient's longitudinal view remains complete without exhausting their storage quota.

Governance & Legal Compliance¶

Entheory.AI's engine is built to enforce the latest national mandates on data longevity and rights: - Retention Guardrails: We implement automated lifecycle management aligned with the NHA Health Data Retention Policy. These guardrails ensure that clinical records are retained in accordance with national mandates before being securely purged or archived. - DPDP Consent Revocation: Our consent manager is designed for granular withdrawal. If a patient exercises their right to withdraw consent under the DPDP Act, the system immediately updates the discovery layer to halt any further transactions of that specific data block, while maintaining the necessary audit logs for clinical and medico-legal resilience.

Population Health & Federated Resilience¶

Entheory.AI's architecture is designed for the decentralized reality of the national backbone: - Federated Node Resilience: Our connector operates as an autonomous node within the ABDM Federated Architecture. This ensures that the facility's digital services are isolated from failures in other parts of the ecosystem, maintaining local uptime and data availability even during broader network ripples. - Privacy-Preserving Research Exports: We provide specialized engines for the export of anonymized, aggregated datasets for population health research, stripping all PII in accordance with national guidelines. - Sovereign Gateway Alignment: We maintain technical readiness for the evolving International Portability landscape. Our gateway is designed to align with sovereign-level exchange protocols and cross-border FHIR profiling as bilateral government agreements are formalized. - Preventive-First Priority: Our data ingestion and alert engines are being tuned to prioritize Preventive and Lifestyle indicators. By emphasizing early signals in the "Wellness" care context, the connector supports the national shift from curative-only to a preventive-first clinical model.

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"]
  }
}

8. Implementation Challenges & Gaps¶

Real-world interoperability involves navigating technical and operational "frictions" that extend beyond standard specifications.

8.1 The Standards Paradox (HL7 Versioning)¶

A frequent challenge in hospital integrations is the Versioning Mismatch between systems. - Problem: A modern EMR may use HL7 v3 (XML-based) or FHIR, while a legacy Lab Information System (LIS) uses HL7 v2.7 (Pipe-delimited). - Impact: Mapping fields between v2.x and v3/FHIR can lead to data truncation or loss of semantic nuance (e.g., specific clinical flags not being mapped correctly). - Solution: Our architecture implements an Intermediate Mapping Layer that normalizes disparate HL7 versions into a canonical internal format before downstream processing.

8.2 The "Sync Lag" & Manual Reality¶

Despite "Scan & Share" front-ends, backend processes often involve Operational Friction: - Manual Data Entry: Even with QR-code based registration (ABDM), some hospital workflows still require staff to manually re-enter data from the digital scan into legacy HIS fields, leading to "Sync Lag" where the live record is only updated overnight. - Routing Inefficiency: In large multi-specialty hospitals, a digital scan identifies the patient but may fail to correctly Route the patient to the specific consultant or department without manual intervention.

8.3 Federated Data Ownership¶

Under the ABDM framework, Hospitals remain the Data Owners. - Institutional Custody: The clinical data resides on institutional servers. - The Digital Locker (PHR): Platforms like Entheory.AI or PHR apps serve as the "Locker" or gateway that provides the patient access to their own records, but they do not "own" the primary medical source of truth.