Katixo/API DocumentationBeta

IPD (Inpatient Department)

Manage inpatient admissions, ward and bed allocation, treatment notes, bed transfers, and patient discharge. The IPD module tracks a patient's entire inpatient journey — from admission through treatment to final discharge with follow-up instructions. All endpoints require JWT Bearer token authentication.

Base URL

https://hospital.katixo.com/api/v1

Endpoints

POST/api/v1/ipd/admissions

GET/api/v1/ipd/admissions

GET/api/v1/ipd/admissions/{admissionId}

GET/api/v1/ipd/wards

PUT/api/v1/ipd/admissions/{admissionId}/transfer

POST/api/v1/ipd/admissions/{admissionId}/treatment-notes

PUT/api/v1/ipd/admissions/{admissionId}/discharge

Authentication: All endpoints require a valid JWT Bearer token in the Authorization header. All IDs are UUIDs.

The AdmissionResponse object

{
  "success": true,
  "message": "Admission retrieved successfully",
  "data": {
    "id": "b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c",
    "admissionNumber": "ADM-2026-00001",
    "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "patientName": "Rajesh Kumar Sharma",
    "patientUhid": "UHID-2026-004821",
    "doctorName": "Dr. Priya Mehta",
    "departmentName": "Cardiology",
    "wardName": "Ward A - Cardiac Care",
    "bedNumber": "A-204",
    "admissionDate": "2026-06-10T09:30:00Z",
    "admissionReason": "Acute myocardial infarction - chest pain and elevated troponin levels",
    "status": "ADMITTED",
    "insuranceDetails": {
      "policyNumber": "STAR-HC-98234710",
      "providerName": "Star Health Insurance",
      "preAuthAmount": 250000.00
    },
    "treatmentNotes": [
      {
        "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
        "noteType": "PROGRESS",
        "content": "Patient stable post-angioplasty. Vitals: BP 130/80, HR 72, SpO2 98%. Continuing dual antiplatelet therapy.",
        "doctorName": "Dr. Priya Mehta",
        "createdAt": "2026-06-11T08:15:00Z"
      },
      {
        "id": "d9e0f1a2-3b4c-5d6e-7f8a-9b0c1d2e3f4a",
        "noteType": "NURSING",
        "content": "IV fluids running. Patient took oral feed. No complaints of chest pain. Wound dressing at catheter site clean and dry.",
        "doctorName": "Sr. Nurse Kavitha",
        "createdAt": "2026-06-11T14:00:00Z"
      }
    ],
    "dischargeDate": null,
    "dischargeSummary": null,
    "createdAt": "2026-06-10T09:30:00Z"
  },
  "errors": null
}

Admission statuses

Status	Description
`ADMITTED`	Patient is currently admitted and occupying a bed.
`TRANSFERRED`	Patient has been transferred to a different ward or bed.
`DISCHARGED`	Patient has been discharged with a discharge summary and follow-up instructions.

Ward types

Type	Description
`GENERAL`	General ward with shared rooms and basic facilities.
`SEMI_PRIVATE`	Semi-private room shared between two patients.
`PRIVATE`	Private single-occupancy room with attached washroom.
`ICU`	Intensive Care Unit for critically ill patients requiring continuous monitoring.
`NICU`	Neonatal Intensive Care Unit for newborns requiring specialized care.
`PICU`	Paediatric Intensive Care Unit for critically ill children.

Admit a patient

POST/api/v1/ipd/admissions

Creates a new inpatient admission. The specified bed is marked as occupied and the patient status changes to ADMITTED. Returns 201 Created on success.

Request body

Field	Type	Required	Description
`patientId`	UUID	Yes	ID of the registered patient.
`doctorId`	UUID	Yes	ID of the admitting/treating doctor.
`departmentId`	UUID	Yes	ID of the clinical department (e.g. Cardiology, Orthopaedics).
`wardId`	UUID	Yes	ID of the ward where the patient will be admitted.
`bedId`	UUID	Yes	ID of the specific bed to assign.
`admissionDate`	DateTime	Yes	Date and time of admission (ISO 8601).
`admissionReason`	String	Yes	Clinical reason for admission.
`referredBy`	String	No	Name of the referring doctor or hospital.
`estimatedStayDays`	int	No	Estimated number of days the patient will stay.
`insuranceDetails`	Object	No	Insurance information. Contains `policyNumber` (String), `providerName` (String), and `preAuthAmount` (BigDecimal).

Example: admit a patient to Fortis Memorial, Gurugram

curl -X POST https://hospital.katixo.com/api/v1/ipd/admissions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "doctorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "departmentId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "wardId": "d4e5f6a7-b8c9-0123-def0-234567890123",
    "bedId": "e5f6a7b8-c9d0-1234-ef01-345678901234",
    "admissionDate": "2026-06-10T09:30:00Z",
    "admissionReason": "Acute myocardial infarction - chest pain and elevated troponin levels",
    "referredBy": "Dr. Anil Gupta, City Heart Clinic, Gurgaon",
    "estimatedStayDays": 5,
    "insuranceDetails": {
      "policyNumber": "STAR-HC-98234710",
      "providerName": "Star Health Insurance",
      "preAuthAmount": 250000.00
    }
  }'

# Response (201 Created)
{
  "success": true,
  "message": "Patient admitted successfully",
  "data": {
    "id": "b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c",
    "admissionNumber": "ADM-2026-00001",
    "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "patientName": "Rajesh Kumar Sharma",
    "patientUhid": "UHID-2026-004821",
    "doctorName": "Dr. Priya Mehta",
    "departmentName": "Cardiology",
    "wardName": "Ward A - Cardiac Care",
    "bedNumber": "A-204",
    "admissionDate": "2026-06-10T09:30:00Z",
    "admissionReason": "Acute myocardial infarction - chest pain and elevated troponin levels",
    "status": "ADMITTED",
    "insuranceDetails": {
      "policyNumber": "STAR-HC-98234710",
      "providerName": "Star Health Insurance",
      "preAuthAmount": 250000.00
    },
    "treatmentNotes": [],
    "dischargeDate": null,
    "dischargeSummary": null,
    "createdAt": "2026-06-10T09:30:00Z"
  },
  "errors": null
}

List admissions

GET/api/v1/ipd/admissions

Returns a paginated list of admissions. The response is wrapped in ApiResponse<PagedResponse<AdmissionResponse>>.

Query parameters

Parameter	Type	Description
`status`	String	Filter by status: `ADMITTED`, `DISCHARGED`, `TRANSFERRED`.
`wardId`	UUID	Filter by ward.
`doctorId`	UUID	Filter by treating doctor.
`page`	int	Page number (zero-based, default: 0).
`size`	int	Results per page (default: 20).

curl https://hospital.katixo.com/api/v1/ipd/admissions?status=ADMITTED&page=0&size=10 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Admissions retrieved successfully",
  "data": {
    "content": [
      {
        "id": "b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c",
        "admissionNumber": "ADM-2026-00001",
        "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "patientName": "Rajesh Kumar Sharma",
        "patientUhid": "UHID-2026-004821",
        "doctorName": "Dr. Priya Mehta",
        "departmentName": "Cardiology",
        "wardName": "Ward A - Cardiac Care",
        "bedNumber": "A-204",
        "admissionDate": "2026-06-10T09:30:00Z",
        "admissionReason": "Acute myocardial infarction - chest pain and elevated troponin levels",
        "status": "ADMITTED",
        "insuranceDetails": {
          "policyNumber": "STAR-HC-98234710",
          "providerName": "Star Health Insurance",
          "preAuthAmount": 250000.00
        },
        "treatmentNotes": [...],
        "dischargeDate": null,
        "dischargeSummary": null,
        "createdAt": "2026-06-10T09:30:00Z"
      },
      {
        "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
        "admissionNumber": "ADM-2026-00002",
        "patientId": "d9e0f1a2-3b4c-5d6e-7f8a-9b0c1d2e3f4a",
        "patientName": "Sunita Devi Verma",
        "patientUhid": "UHID-2026-004822",
        "doctorName": "Dr. Rakesh Agarwal",
        "departmentName": "Orthopaedics",
        "wardName": "Ward C - Ortho",
        "bedNumber": "C-112",
        "admissionDate": "2026-06-10T14:15:00Z",
        "admissionReason": "Fracture of right femur following road traffic accident",
        "status": "ADMITTED",
        "insuranceDetails": null,
        "treatmentNotes": [...],
        "dischargeDate": null,
        "dischargeSummary": null,
        "createdAt": "2026-06-10T14:15:00Z"
      }
    ],
    "page": 0,
    "size": 10,
    "totalElements": 34,
    "totalPages": 4,
    "last": false
  },
  "errors": null
}

Get admission details

GET/api/v1/ipd/admissions/{admissionId}

Retrieves a single admission by its UUID, including the current bed assignment, full treatment history, and discharge details (if discharged). Returns ApiResponse<AdmissionResponse>.

curl https://hospital.katixo.com/api/v1/ipd/admissions/b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

List wards with bed availability

GET/api/v1/ipd/wards

Returns all wards in the hospital with real-time bed availability counts. Use this to check available beds before creating an admission or initiating a transfer.

curl https://hospital.katixo.com/api/v1/ipd/wards \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Wards retrieved successfully",
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "wardName": "Ward A - Cardiac Care",
      "wardType": "SEMI_PRIVATE",
      "totalBeds": 20,
      "occupiedBeds": 14,
      "availableBeds": 6
    },
    {
      "id": "e5f6a7b8-c9d0-2345-ef01-345678901234",
      "wardName": "Ward B - General Medicine",
      "wardType": "GENERAL",
      "totalBeds": 40,
      "occupiedBeds": 31,
      "availableBeds": 9
    },
    {
      "id": "f6a7b8c9-d0e1-3456-f012-456789012345",
      "wardName": "Ward C - Ortho",
      "wardType": "SEMI_PRIVATE",
      "totalBeds": 16,
      "occupiedBeds": 12,
      "availableBeds": 4
    },
    {
      "id": "a7b8c9d0-e1f2-4567-0123-567890123456",
      "wardName": "ICU - Main",
      "wardType": "ICU",
      "totalBeds": 12,
      "occupiedBeds": 10,
      "availableBeds": 2
    },
    {
      "id": "b8c9d0e1-f2a3-5678-1234-678901234567",
      "wardName": "NICU",
      "wardType": "NICU",
      "totalBeds": 8,
      "occupiedBeds": 5,
      "availableBeds": 3
    },
    {
      "id": "c9d0e1f2-a3b4-6789-2345-789012345678",
      "wardName": "Deluxe Suites - Private",
      "wardType": "PRIVATE",
      "totalBeds": 10,
      "occupiedBeds": 7,
      "availableBeds": 3
    }
  ],
  "errors": null
}

Transfer patient

PUT/api/v1/ipd/admissions/{admissionId}/transfer

Transfers a patient to a different bed or ward. The previous bed is freed and the new bed is marked as occupied. A transfer record is logged in the admission history.

Request body

Field	Type	Required	Description
`newWardId`	UUID	Yes	ID of the destination ward.
`newBedId`	UUID	Yes	ID of the destination bed.
`reason`	String	Yes	Reason for the transfer.

Example: transfer to ICU at AIIMS Delhi

curl -X PUT https://hospital.katixo.com/api/v1/ipd/admissions/b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c/transfer \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "newWardId": "a7b8c9d0-e1f2-4567-0123-567890123456",
    "newBedId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
    "reason": "Patient condition deteriorated - requires continuous cardiac monitoring and ventilator support"
  }'

# Response
{
  "success": true,
  "message": "Patient transferred successfully",
  "data": {
    "id": "b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c",
    "admissionNumber": "ADM-2026-00001",
    "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "patientName": "Rajesh Kumar Sharma",
    "patientUhid": "UHID-2026-004821",
    "doctorName": "Dr. Priya Mehta",
    "departmentName": "Cardiology",
    "wardName": "ICU - Main",
    "bedNumber": "ICU-03",
    "admissionDate": "2026-06-10T09:30:00Z",
    "admissionReason": "Acute myocardial infarction - chest pain and elevated troponin levels",
    "status": "ADMITTED",
    "insuranceDetails": {
      "policyNumber": "STAR-HC-98234710",
      "providerName": "Star Health Insurance",
      "preAuthAmount": 250000.00
    },
    "treatmentNotes": [...],
    "dischargeDate": null,
    "dischargeSummary": null,
    "createdAt": "2026-06-10T09:30:00Z"
  },
  "errors": null
}

Add treatment note

POST/api/v1/ipd/admissions/{admissionId}/treatment-notes

Appends a treatment note to the admission record. Treatment notes form the patient's clinical chart and include progress updates, nursing observations, medication logs, and dietary instructions. Returns 201 Created on success.

Request body

Field	Type	Required	Description
`noteType`	String	Yes	Type of note: `PROGRESS`, `NURSING`, `MEDICATION`, or `DIET`.
`content`	String	Yes	The clinical note content.
`doctorId`	UUID	Yes	ID of the doctor or nurse adding the note.

Note types

Type	Description
`PROGRESS`	Doctor's progress note with clinical observations and plan of care.
`NURSING`	Nursing observations including vitals, intake/output, and patient comfort.
`MEDICATION`	Medication administration record with drug, dose, route, and time.
`DIET`	Dietary instructions and meal plan for the patient.

Example: add a medication note

curl -X POST https://hospital.katixo.com/api/v1/ipd/admissions/b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c/treatment-notes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "noteType": "MEDICATION",
    "content": "Administered Inj. Enoxaparin 60mg SC. Tab Clopidogrel 75mg + Tab Aspirin 75mg given orally. Tab Atorvastatin 40mg given at bedtime. Vitals stable post-medication.",
    "doctorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'

# Response (201 Created)
{
  "success": true,
  "message": "Treatment note added successfully",
  "data": {
    "id": "e0f1a2b3-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "noteType": "MEDICATION",
    "content": "Administered Inj. Enoxaparin 60mg SC. Tab Clopidogrel 75mg + Tab Aspirin 75mg given orally. Tab Atorvastatin 40mg given at bedtime. Vitals stable post-medication.",
    "doctorName": "Dr. Priya Mehta",
    "createdAt": "2026-06-11T20:30:00Z"
  },
  "errors": null
}

Discharge patient

PUT/api/v1/ipd/admissions/{admissionId}/discharge

Discharges a patient from the hospital. The assigned bed is freed, the admission status changes to DISCHARGED, and a discharge summary with follow-up instructions is recorded. This action is irreversible.

Request body

Field	Type	Required	Description
`dischargeDate`	DateTime	Yes	Date and time of discharge (ISO 8601).
`dischargeSummary`	String	Yes	Clinical discharge summary describing diagnosis, treatment, and outcome.
`followUpDate`	LocalDate	No	Date for the follow-up visit (YYYY-MM-DD).
`followUpInstructions`	String	No	Instructions for the patient to follow after discharge.
`dischargeMedications`	String[]	No	Array of medications prescribed at discharge.

Example: discharge from Narayana Health, Bangalore

curl -X PUT https://hospital.katixo.com/api/v1/ipd/admissions/b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c/discharge \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "dischargeDate": "2026-06-15T11:00:00Z",
    "dischargeSummary": "Patient admitted with acute MI on 10/06/2026. Underwent successful PTCA with stent placement to LAD on 11/06/2026. Post-procedure recovery uneventful. Patient is hemodynamically stable, afebrile, and mobilizing independently. ECG shows normal sinus rhythm. Echo shows LVEF 50%. Discharged in satisfactory condition.",
    "followUpDate": "2026-06-22",
    "followUpInstructions": "Review in OPD Cardiology after 1 week. Avoid heavy lifting for 4 weeks. Report immediately if chest pain, breathlessness, or bleeding from puncture site. Strict salt-restricted diet. Walk 20 minutes daily.",
    "dischargeMedications": [
      "Tab Clopidogrel 75mg OD x 12 months",
      "Tab Aspirin 75mg OD x lifelong",
      "Tab Atorvastatin 40mg HS x lifelong",
      "Tab Metoprolol 25mg BD x 3 months",
      "Tab Ramipril 2.5mg OD x 3 months",
      "Tab Pantoprazole 40mg OD x 1 month"
    ]
  }'

# Response
{
  "success": true,
  "message": "Patient discharged successfully",
  "data": {
    "id": "b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c",
    "admissionNumber": "ADM-2026-00001",
    "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "patientName": "Rajesh Kumar Sharma",
    "patientUhid": "UHID-2026-004821",
    "doctorName": "Dr. Priya Mehta",
    "departmentName": "Cardiology",
    "wardName": "ICU - Main",
    "bedNumber": "ICU-03",
    "admissionDate": "2026-06-10T09:30:00Z",
    "admissionReason": "Acute myocardial infarction - chest pain and elevated troponin levels",
    "status": "DISCHARGED",
    "insuranceDetails": {
      "policyNumber": "STAR-HC-98234710",
      "providerName": "Star Health Insurance",
      "preAuthAmount": 250000.00
    },
    "treatmentNotes": [
      {
        "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
        "noteType": "PROGRESS",
        "content": "Patient stable post-angioplasty. Vitals: BP 130/80, HR 72, SpO2 98%. Continuing dual antiplatelet therapy.",
        "doctorName": "Dr. Priya Mehta",
        "createdAt": "2026-06-11T08:15:00Z"
      },
      {
        "id": "d9e0f1a2-3b4c-5d6e-7f8a-9b0c1d2e3f4a",
        "noteType": "NURSING",
        "content": "IV fluids running. Patient took oral feed. No complaints of chest pain. Wound dressing at catheter site clean and dry.",
        "doctorName": "Sr. Nurse Kavitha",
        "createdAt": "2026-06-11T14:00:00Z"
      },
      {
        "id": "e0f1a2b3-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
        "noteType": "MEDICATION",
        "content": "Administered Inj. Enoxaparin 60mg SC. Tab Clopidogrel 75mg + Tab Aspirin 75mg given orally. Tab Atorvastatin 40mg given at bedtime. Vitals stable post-medication.",
        "doctorName": "Dr. Priya Mehta",
        "createdAt": "2026-06-11T20:30:00Z"
      }
    ],
    "dischargeDate": "2026-06-15T11:00:00Z",
    "dischargeSummary": "Patient admitted with acute MI on 10/06/2026. Underwent successful PTCA with stent placement to LAD on 11/06/2026. Post-procedure recovery uneventful. Patient is hemodynamically stable, afebrile, and mobilizing independently. ECG shows normal sinus rhythm. Echo shows LVEF 50%. Discharged in satisfactory condition.",
    "createdAt": "2026-06-10T09:30:00Z"
  },
  "errors": null
}

Error handling

All error responses follow the standard ApiResponse wrapper with success: false and details in the errors array.

# 400 Bad Request — validation error
{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    "patientId: must not be null",
    "bedId: must not be null",
    "admissionReason: must not be blank"
  ]
}

# 404 Not Found
{
  "success": false,
  "message": "Admission not found",
  "data": null,
  "errors": ["No admission found with id: b7e4c1a2-3d5f-4e8a-9b1c-2d3e4f5a6b7c"]
}

# 409 Conflict — bed already occupied
{
  "success": false,
  "message": "Bed unavailable",
  "data": null,
  "errors": ["Bed A-204 in Ward A - Cardiac Care is already occupied by another patient"]
}

# 422 Unprocessable Entity — invalid state transition
{
  "success": false,
  "message": "Invalid operation",
  "data": null,
  "errors": ["Cannot discharge patient: admission is already in DISCHARGED status"]
}