# 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](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](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: ``` Finance: ``` API keys are managed in the HMIS Admin panel under **API Key Management**. Keys must be active, activated, and not expired. If authentication fails: ```json {"status": "error", "code": 401, "message": "Not a valid key"} ``` --- ## Endpoint ``` GET /api/inward/admissions ``` 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 ```bash curl -H "Finance: " \ https://hmis.example.com/api/inward/admissions ``` ### Search a patient's admission history by phone ```bash curl -H "Finance: " \ "https://hmis.example.com/api/inward/admissions?status=ANY_STATUS&phone=0771234567" ``` ### Search by MRN/PHN, including past (discharged) admissions ```bash curl -H "Finance: " \ "https://hmis.example.com/api/inward/admissions?status=ANY_STATUS&mrn=P00012345" ``` ### Filter by department and BHT prefix ```bash curl -H "Finance: " \ "https://hmis.example.com/api/inward/admissions?departmentId=42&bhtNo=BHT2026" ``` ### Paginate ```bash curl -H "Finance: " \ "https://hmis.example.com/api/inward/admissions?page=2&size=20" ``` `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 ```json { "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: ```json {"status": "error", "code": , "message": "
"} ``` --- ## 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](Inward-Online-Payment-API) — for payment-collection specific lookups (unpaid admissions, take payment) - [Inward Item Request API](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](Inward-Online-Payment-API) `/admissions` | | "Take a payment for this BHT" | [Inward Online Payment API](Inward-Online-Payment-API) `/payment` |