Katixo/API DocumentationBeta

Patients

Patients are the core entity in Hospital OS. Every clinical workflow — OPD consultations, IPD admissions, lab orders, surgeries, and billing — is linked to a patient record. On registration, each patient is assigned a unique UHID (Unique Hospital ID) scoped to the branch, following the format KH-YYYY-NNNNN. The UHID is auto-generated by the system and cannot be manually set. The API uses JWT Bearer token authentication and returns all responses in the standard ApiResponse<T> envelope.

Authentication

All endpoints require a valid JWT Bearer token in the Authorization header.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Response envelope

Every response is wrapped in ApiResponse<T>.

{
  "success": true,
  "message": "Patient registered successfully",
  "data": { ... },
  "errors": null
}

Endpoints

GET/api/v1/patients

GET/api/v1/patients/{patientId}

POST/api/v1/patients

PUT/api/v1/patients/{patientId}

GET/api/v1/patients/{patientId}/visits

Enums

Gender

Value	Description
`MALE`	Male patient.
`FEMALE`	Female patient.
`OTHER`	Other / non-binary.

BloodGroup

Value	Description
`A+`	A positive.
`A-`	A negative.
`B+`	B positive.
`B-`	B negative.
`AB+`	AB positive.
`AB-`	AB negative.
`O+`	O positive.
`O-`	O negative.

The PatientResponse object

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "uhid": "KH-2026-00001",
  "firstName": "Rajesh",
  "lastName": "Kumar",
  "dateOfBirth": "1985-03-15",
  "gender": "MALE",
  "phone": "+919876543210",
  "email": "[email protected]",
  "address": "45 MG Road",
  "city": "Lucknow",
  "state": "Uttar Pradesh",
  "pincode": "226001",
  "bloodGroup": "B+",
  "emergencyContact": {
    "name": "Sunita Kumar",
    "phone": "+919876543211"
  },
  "aadharNumber": null,
  "abhaId": null,
  "registrationDate": "2026-06-10",
  "branchId": "a1b2c3d4-5678-9abc-def0-1234567890ab",
  "branchName": "City Hospital - Main"
}

List / search patients

GET/api/v1/patients

Returns a paginated list of patients. Supports searching by name, phone number, or UHID. The response is wrapped in ApiResponse<Page<PatientResponse>>.

Query parameters

Parameter	Type	Default	Description
`search`	string	--	Search by patient name, phone number, or UHID.
`page`	integer	0	Zero-based page number.
`size`	integer	20	Number of results per page.
`sort`	string	--	Sort field and direction, e.g. `registrationDate,desc`.

curl -X GET "https://hospital.katixo.com/api/v1/patients?search=Rajesh&size=10&page=0" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Get a patient

GET/api/v1/patients/{patientId}

Retrieves a single patient by UUID. Returns the full patient record wrapped in ApiResponse<PatientResponse>.

curl -X GET "https://hospital.katixo.com/api/v1/patients/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Register a patient

POST/api/v1/patients

Registers a new patient and auto-generates a UHID. Returns 201 Created with ApiResponse<PatientResponse>.

curl -X POST "https://hospital.katixo.com/api/v1/patients" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Priya",
    "lastName": "Sharma",
    "dateOfBirth": "1992-07-22",
    "gender": "FEMALE",
    "phone": "+919123456789",
    "email": "[email protected]",
    "address": "12 Civil Lines",
    "city": "Jaipur",
    "state": "Rajasthan",
    "pincode": "302001",
    "bloodGroup": "O+",
    "emergencyContact": {
      "name": "Vikram Sharma",
      "phone": "+919123456780"
    },
    "aadharNumber": "9876-5432-1098",
    "abhaId": null
  }'

CreatePatientRequest fields

Field	Type	Required	Description
`firstName`	String	Yes	Patient's first name.
`lastName`	String	Yes	Patient's last name.
`dateOfBirth`	LocalDate	Yes	Date of birth in `YYYY-MM-DD` format.
`gender`	Gender	Yes	`MALE`, `FEMALE`, or `OTHER`.
`phone`	String	Yes	Mobile phone number with country code (e.g., `+919876543210`).
`email`	String	No	Email address.
`address`	String	No	Street address.
`city`	String	No	City name.
`state`	String	No	State name (e.g., "Uttar Pradesh").
`pincode`	String	No	6-digit PIN code.
`bloodGroup`	BloodGroup	No	Blood group. See enum above.
`emergencyContact`	Object	No	Emergency contact with `name` (String) and `phone` (String) fields.
`aadharNumber`	String	No	12-digit Aadhaar number (formatted as `XXXX-XXXX-XXXX`).
`abhaId`	String	No	ABDM (Ayushman Bharat Digital Mission) health ID for digital health record linking.

Update a patient

PUT/api/v1/patients/{patientId}

Updates an existing patient's details. The request body uses the same CreatePatientRequest schema. The uhid and registrationDate cannot be modified. Returns ApiResponse<PatientResponse>.

curl -X PUT "https://hospital.katixo.com/api/v1/patients/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Rajesh",
    "lastName": "Kumar",
    "dateOfBirth": "1985-03-15",
    "gender": "MALE",
    "phone": "+919876543210",
    "email": "[email protected]",
    "address": "72 Hazratganj",
    "city": "Lucknow",
    "state": "Uttar Pradesh",
    "pincode": "226001",
    "bloodGroup": "B+",
    "emergencyContact": {
      "name": "Sunita Kumar",
      "phone": "+919876543211"
    },
    "aadharNumber": "1234-5678-9012",
    "abhaId": "rajesh.kumar@abdm"
  }'

Get visit history

GET/api/v1/patients/{patientId}/visits

Retrieves the complete visit history for a patient, including both OPD (outpatient) and IPD (inpatient) records. Returns ApiResponse<List<VisitResponse>>.

curl -X GET "https://hospital.katixo.com/api/v1/patients/f47ac10b-58cc-4372-a567-0e02b2c3d479/visits" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Example response

{
  "success": true,
  "message": "Visit history retrieved",
  "data": [
    {
      "visitId": "b2c3d4e5-6789-abcd-ef01-234567890abc",
      "type": "OPD",
      "visitDate": "2026-06-10",
      "department": "General Medicine",
      "doctorName": "Dr. Anita Verma",
      "diagnosis": "Acute viral fever",
      "status": "COMPLETED"
    },
    {
      "visitId": "c3d4e5f6-789a-bcde-f012-34567890abcd",
      "type": "IPD",
      "admissionDate": "2026-05-01",
      "dischargeDate": "2026-05-05",
      "department": "Orthopaedics",
      "doctorName": "Dr. Manoj Tiwari",
      "diagnosis": "Fracture - left tibia",
      "ward": "General Ward - A",
      "bedNumber": "GW-A-14",
      "status": "DISCHARGED"
    }
  ],
  "errors": null
}

Error responses

When validation fails or a resource is not found, the API returns an ApiResponse with success: false and the errors array populated.

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    "firstName: must not be blank",
    "phone: must not be blank",
    "gender: must not be null"
  ]
}