API Reference

Developer documentation for the ClinicalHIS REST API. Integrate your external systems or build custom clients.

Authentication

The API uses Bearer Token authentication. Include the JWT token returned from the login endpoint in the Authorization header of your requests.

Authorization: Bearer <your_jwt_token>

Base URL

All API requests should be prefixed with:

/api

Endpoints

GET/emr/patients

Retrieve a list of patients. Supports pagination and searching.

Parameters

  • page (number): Page number
  • limit (number): Items per page
  • search (string): Search by name or ID
POST/telemedicine/sessions

Create a new telemedicine session.

Body

{
  "patient_id": "uuid",
  "doctor_id": "uuid",
  "scheduled_at": "ISO-8601 string"
}
GET/fhir/…FHIR R4 · read-only

A HL7 FHIR R4 read API for interoperability: discovery, search and read across five resource types. All responses use application/fhir+json; lists return a FHIR Bundle (type: searchset); errors return an OperationOutcome. This version is read-only.

Discovery

GET /api/v1/fhir/metadata      → CapabilityStatement (fhirVersion 4.0.1)

Resources & search parameters

  • Patient — identifier (UHID), name, active; read by id
  • Encounter — patient, status, date; read by id
  • Observation — patient, category (laboratory | vital-signs), status
  • DiagnosticReport — patient, category (LAB | RAD), status
  • MedicationRequest — patient, encounter, status (internal values: active/dispensed/cancelled)
  • All searches: _count (default 50, max 200), _offset, _lastUpdated

Access requirements

  • Bearer JWT like the REST API; requests always resolve to the caller's tenant (superadmins must send X-Tenant-ID)
  • The tenant's plan must include the HL7 / FHIR API Gateway capability (apiAccess ≥ read) — configured in the superadmin plan editor
  • Standard RBAC still applies (e.g. patient.view for Patient, lab.view for laboratory results, radiology.view for imaging reports)
  • Every request is written to the tenant's audit trail (fhir_api_read)

Example

GET /api/v1/fhir/Patient?identifier=UHID-12345&_count=5

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [{
    "fullUrl": "Patient/9f8b…",
    "resource": {
      "resourceType": "Patient",
      "id": "9f8b…",
      "identifier": [{ "use": "official", "value": "UHID-12345" }],
      "name": [{ "family": "Mensah", "given": ["Ama"] }]
    }
  }]
}

Note: the legacy per-patient format GET /patients/:id?format=fhir still works and is unchanged.

GET/analytics/ai/risk-scoreAI Beta

Calculate real-time clinical risk scores (e.g., Sepsis, Readmission).

Parameters

  • patient_id (uuid): Target patient
  • risk_type (string): 'SEPSIS' | 'READMISSION'