Inward Admission Search API

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:

Finance: <your-api-key>

API keys are managed in the HMIS Admin panel under API Key Management. Keys must be active, activated, and not expired.

If authentication fails:

{"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

curl -H "Finance: <api-key>" \
  https://hmis.example.com/api/inward/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

curl -H "Finance: <api-key>" \
  "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

{
  "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:

{"status": "error", "code": <status>, "message": "<details>"}

---

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