# Channelling API Overview 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. ## Audience This article is aimed at **system integrators, developers, and IT administrators** building or connecting external applications to HMIS channelling. ## API Documentation 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) ## Authentication All API requests require an API key, passed in the `Finance` request header: ``` Finance: ``` 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. ## Base URL ``` https:////api/ ``` All channelling endpoints are under `/api/` followed by the resource path (e.g., `/api/channel/sessions`). ## Key Endpoints ### Session Availability | 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 | ### Booking Management | 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 | ### Patient | Method | Endpoint | Description | |---|---|---| | GET | `/api/patients/search` | Search for existing patients | | POST | `/api/patients` | Register a new patient | ## Standard Response Format All API responses follow this envelope: ```json { "status": "success", "code": 200, "data": { ... } } ``` On error: ```json { "status": "error", "code": 400, "message": "Reason for failure" } ``` ## Date Format 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` ## Webhook / Real-Time Notifications 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:////ws/notify ``` Messages follow the format: ``` Online Booking Completed - Online Booking Cancelled - ``` ## Capabilities Discovery 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. ## Related Articles - [Mobile App Booking Integration](Mobile-App-Booking-Integration) - [Channelling Patient Portal](Channelling-Patient-Portal) - [Channelling Overview](Channelling-Overview)