Inward Admission Search API¶
Overview¶
The Admission Search API (/api/inward/admissions) is a general-purpose lookup for inpatient admissions. It mirrors the staff-facing Admissions Search page (Inpatient → Search → Admissions, see Inpatient — Admissions Search) but is available for external systems and the AI Chat assistant to call directly.
Use this API to:
- List all currently active (not-discharged) admissions
- Search past or current admissions by phone number or MRN/PHN
- Filter by BHT number, patient name, NIC, admission type, institution, or department
- Page through large result sets
This is different from the Inward Online Payment API (/api/apiInward/*), which is scoped specifically to admissions with money owed (a payment-collection worklist, capped at 20 rows). This API has no such scoping or row cap — it returns whatever matches your filters, paginated.
Authentication¶
All requests require an API key in the Finance HTTP header:
API keys are managed in the HMIS Admin panel under API Key Management. Keys must be active, activated, and not expired.
If authentication fails:
Endpoint¶
All query parameters are optional.
| Parameter | Type | Description |
|---|---|---|
status |
string | ADMITTED_BUT_NOT_DISCHARGED (default), DISCHARGED_BUT_FINAL_BILL_NOT_COMPLETED, DISCHARGED_AND_FINAL_BILL_COMPLETED, or ANY_STATUS |
bhtNo |
string | Bed Head Ticket number (partial match) |
patientName |
string | Patient name (partial match) |
mrn |
string | Patient MRN/PHN or patient code (exact match) |
phone |
string | Patient's or guardian's phone/mobile number (exact match) |
nic |
string | Patient NIC/passport number (exact match) |
admissionTypeId |
long | Numeric Admission Type ID |
institutionId |
long | Numeric Institution ID |
departmentId |
long | Numeric Department ID |
fromDate / toDate |
string | Admission date range, yyyy-MM-dd HH:mm:ss — must be supplied together |
page |
int | Page number, default 1 |
size |
int | Page size, default 50, max 200 |
Omitting every filter returns currently active (not-discharged) admissions, newest first — no date range is required (unlike the staff search page, where From/To Date is mandatory).
Examples¶
List currently active admissions¶
Search a patient's admission history by phone¶
curl -H "Finance: <api-key>" \
"https://hmis.example.com/api/inward/admissions?status=ANY_STATUS&phone=0771234567"
Search by MRN/PHN, including past (discharged) admissions¶
curl -H "Finance: <api-key>" \
"https://hmis.example.com/api/inward/admissions?status=ANY_STATUS&mrn=P00012345"
Filter by department and BHT prefix¶
curl -H "Finance: <api-key>" \
"https://hmis.example.com/api/inward/admissions?departmentId=42&bhtNo=BHT2026"
Paginate¶
page starts at 1. The response's totalCount is the full matching count regardless of page, so you can compute the total number of pages as ceil(totalCount / size).
Response¶
{
"status": "success",
"code": 200,
"data": {
"admissions": [
{
"patientEncounterId": 384021,
"bhtNo": "BHT2026001",
"patientMrn": "P00012345",
"patientCode": "PC00123",
"patientName": "K. G. Perera",
"patientPhone": "0112345678",
"patientMobile": "0771234567",
"patientNic": "901234567V",
"patientAddress": "12 Main St, Galle",
"patientArea": "Galle",
"referringDoctor": "Dr. J. Silva",
"admissionType": "Ward Admission",
"institution": "Ruhunu Hospital",
"department": "Medical Ward 1",
"currentRoom": "Ward 1 - Bed 4",
"dateOfAdmission": "2026-08-01 10:15:00",
"dateOfDischarge": null,
"discharged": false,
"paymentFinalized": false,
"netTotal": 45000.0,
"paidAmount": 20000.0,
"balance": 25000.0
}
],
"page": 1,
"size": 50,
"totalCount": 128
}
}
netTotal, paidAmount, and balance are only present once a final bill exists for the admission. Fields tied to an empty relationship (e.g. no currentPatientRoom, no referringDoctor) are omitted or null.
Error Responses¶
| Condition | HTTP Status | Message |
|---|---|---|
Missing or invalid Finance key |
401 | Not a valid key |
Unknown status value |
400 | Invalid status. Valid values: ADMITTED_BUT_NOT_DISCHARGED, DISCHARGED_BUT_FINAL_BILL_NOT_COMPLETED, DISCHARGED_AND_FINAL_BILL_COMPLETED, ANY_STATUS |
fromDate given without toDate (or vice versa) |
400 | fromDate and toDate must both be supplied together. |
Unparseable fromDate/toDate |
400 | Invalid fromDate/toDate format. Expected: yyyy-MM-dd HH:mm:ss |
Non-numeric admissionTypeId/institutionId/departmentId |
400 | Invalid admissionTypeId/institutionId/departmentId value. Must be numeric. |
Non-numeric page/size |
400 | Invalid page value. / Invalid size value. |
| Unexpected server error | 500 | An error occurred while searching admissions. (details are logged server-side only) |
All error responses use the same envelope:
Integration Notes¶
AI Chat integration¶
This endpoint is also exposed to the in-app AI Chat assistant as the search_admissions tool, so staff can ask things like "show me all patients currently admitted in Ward 1" or "find John Perera's past admissions by his phone number" directly in chat.
Related APIs¶
- Inward Online Payment API — for payment-collection specific lookups (unpaid admissions, take payment)
- Inward Item Request API — for external item/service requests against a BHT
When to use this vs. the Online Payment API¶
| Need | Use |
|---|---|
| "Who is currently admitted?" | This API, default status |
| "Find this patient's admission history" | This API, status=ANY_STATUS + phone or mrn |
| "Which admitted patients still owe money?" | Inward Online Payment API /admissions |
| "Take a payment for this BHT" | Inward Online Payment API /payment |