Channelling API Overview - hmislk/hmis GitHub Wiki
HMIS exposes a REST API for channelling operations, enabling external systems â mobile apps, patient portals, call-centre platforms, and third-party booking channels â to query available sessions, create bookings, check statuses, and receive notifications.
This article is aimed at system integrators, developers, and IT administrators building or connecting external applications to HMIS channelling.
The channelling API is documented via Swagger/OpenAPI. The live API specification is accessible at:
Your HMIS installation's Swagger endpoint â typically available under the base API URL. Contact your system administrator for the exact URL for your deployment (internal reference: DOC990).
The Swagger UI allows you to:
- Browse all available endpoints
- View request/response schemas
- Execute test calls directly from the browser (with authentication)
All API requests require an API key, passed in the Finance request header:
Finance: <your-api-key>
API keys are managed by the system administrator. Each key:
- Is associated with a specific API user / application
- Has an expiry date
- Can be activated or retired
Contact your administrator to obtain or rotate an API key.
https://<your-hmis-host>/<context-root>/api/
All channelling endpoints are under /api/ followed by the resource path (e.g., /api/channel/sessions).
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/channel/specialities |
List available specialities |
| GET | /api/channel/consultants |
List consultants (filter by speciality) |
| GET | /api/channel/sessions |
List available session instances (filter by consultant, date range) |
| GET | /api/channel/sessions/{id} |
Get details of a specific session instance |
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/channel/bookings |
Create a new channel booking |
| GET | /api/channel/bookings/{id} |
Get booking details by ID |
| GET | /api/channel/bookings/patient/{patientId} |
Get all bookings for a patient |
| PUT | /api/channel/bookings/{id}/cancel |
Cancel a booking |
| PUT | /api/channel/bookings/{id}/reschedule |
Reschedule a booking |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/patients/search |
Search for existing patients |
| POST | /api/patients |
Register a new patient |
All API responses follow this envelope:
{
"status": "success",
"code": 200,
"data": { ... }
}On error:
{
"status": "error",
"code": 400,
"message": "Reason for failure"
}All dates and times in API requests and responses use the format:
yyyy-MM-dd HH:mm:ss
Example: 2026-05-18 09:30:00
The system supports WebSocket-based real-time notifications for events such as:
- New online booking received in a session
- Booking cancellation from the online channel
The WebSocket endpoint is:
wss://<host>/<context-root>/ws/notify
Messages follow the format:
Online Booking Completed - <sessionId>
Online Booking Cancelled - <sessionId>
To programmatically discover which API modules and tools are available on a given HMIS deployment:
GET /api/capabilities
This returns the CapabilityStatement listing all registered API resources.