Katixo/API DocumentationBeta

OPD (Outpatient Department)

Manage the complete outpatient workflow — from appointment booking and patient check-in through consultation, prescription, and follow-up scheduling. The OPD module includes an auto-generated token queue system that tracks patient flow in real time. All endpoints require JWT Bearer token authentication.

Base URL

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

Endpoints

POST/api/v1/opd/appointments

GET/api/v1/opd/appointments

GET/api/v1/opd/appointments/{appointmentId}

PUT/api/v1/opd/appointments/{appointmentId}/check-in

PUT/api/v1/opd/appointments/{appointmentId}/start-consultation

PUT/api/v1/opd/appointments/{appointmentId}/complete

GET/api/v1/opd/queue

POST/api/v1/opd/prescriptions

Authentication: All endpoints require a valid JWT Bearer token in the Authorization header. All IDs are UUIDs. Token numbers (e.g. T-001) are auto-generated per doctor per day.

The AppointmentResponse object

{
  "success": true,
  "message": "Appointment retrieved successfully",
  "data": {
    "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "tokenNumber": "T-001",
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "patientName": "Rajesh Kumar Verma",
    "patientUhid": "UHID-2026-00451",
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "doctorName": "Dr. Anjali Sharma",
    "departmentName": "General Medicine",
    "appointmentDate": "2026-06-12",
    "appointmentTime": "10:30:00",
    "type": "SCHEDULED",
    "status": "SCHEDULED",
    "checkedInAt": null,
    "consultationStartedAt": null,
    "completedAt": null,
    "createdAt": "2026-06-11T14:20:00Z"
  },
  "errors": null
}

Appointment statuses

Status	Description
`SCHEDULED`	Appointment booked but patient has not yet arrived at the hospital.
`CHECKED_IN`	Patient has arrived and checked in at the OPD counter. Added to the doctor's queue.
`IN_CONSULTATION`	Doctor has started seeing the patient. Consultation is in progress.
`COMPLETED`	Consultation finished. Prescription and follow-up (if any) have been recorded.
`CANCELLED`	Appointment was cancelled by the patient or hospital staff.
`NO_SHOW`	Patient did not arrive for the scheduled appointment.

Appointment types

Type	Description
`WALK_IN`	Patient walks in without a prior appointment. Token assigned on the spot.
`SCHEDULED`	Pre-booked appointment with a specific date and time slot.
`FOLLOW_UP`	Follow-up visit linked to a previous consultation.

Book an appointment

POST/api/v1/opd/appointments

Books a new OPD appointment and auto-generates a token number for the given doctor and date. 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 consulting doctor.
`departmentId`	UUID	Yes	Department ID (e.g. General Medicine, Orthopedics, Pediatrics, ENT, Ophthalmology).
`appointmentDate`	LocalDate	Yes	Date of appointment (YYYY-MM-DD).
`appointmentTime`	LocalTime	Yes	Time slot (HH:mm:ss, 24-hour format).
`type`	String	Yes	Appointment type: `WALK_IN`, `SCHEDULED`, or `FOLLOW_UP`.
`notes`	String	No	Free-text notes (e.g. chief complaint, referral info).

Example: book a scheduled appointment

curl -X POST https://hospital.katixo.com/api/v1/opd/appointments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "departmentId": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
    "appointmentDate": "2026-06-12",
    "appointmentTime": "10:30:00",
    "type": "SCHEDULED",
    "notes": "Patient complains of persistent fever for 3 days"
  }'

# Response (201 Created)
{
  "success": true,
  "message": "Appointment booked successfully",
  "data": {
    "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "tokenNumber": "T-001",
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "patientName": "Rajesh Kumar Verma",
    "patientUhid": "UHID-2026-00451",
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "doctorName": "Dr. Anjali Sharma",
    "departmentName": "General Medicine",
    "appointmentDate": "2026-06-12",
    "appointmentTime": "10:30:00",
    "type": "SCHEDULED",
    "status": "SCHEDULED",
    "checkedInAt": null,
    "consultationStartedAt": null,
    "completedAt": null,
    "createdAt": "2026-06-11T14:20:00Z"
  },
  "errors": null
}

List appointments

GET/api/v1/opd/appointments

Returns a paginated list of OPD appointments. The response is wrapped in ApiResponse<PagedResponse<AppointmentResponse>>.

Query parameters

Parameter	Type	Description
`date`	LocalDate	Filter by appointment date (YYYY-MM-DD). Defaults to today.
`doctorId`	UUID	Filter by doctor.
`departmentId`	UUID	Filter by department.
`status`	String	Filter by status: `SCHEDULED`, `CHECKED_IN`, `IN_CONSULTATION`, `COMPLETED`, `CANCELLED`, `NO_SHOW`.
`page`	int	Page number (zero-based, default: 0).
`size`	int	Results per page (default: 20).

curl "https://hospital.katixo.com/api/v1/opd/appointments?date=2026-06-12&doctorId=d1e2f3a4-b5c6-7890-dcba-fe0987654321&status=CHECKED_IN&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Appointments retrieved successfully",
  "data": {
    "content": [
      {
        "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
        "tokenNumber": "T-001",
        "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "patientName": "Rajesh Kumar Verma",
        "patientUhid": "UHID-2026-00451",
        "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
        "doctorName": "Dr. Anjali Sharma",
        "departmentName": "General Medicine",
        "appointmentDate": "2026-06-12",
        "appointmentTime": "10:30:00",
        "type": "SCHEDULED",
        "status": "CHECKED_IN",
        "checkedInAt": "2026-06-12T10:15:00Z",
        "consultationStartedAt": null,
        "completedAt": null,
        "createdAt": "2026-06-11T14:20:00Z"
      },
      {
        "id": "c2b3d4e5-f6a7-8901-bcde-f12345678901",
        "tokenNumber": "T-002",
        "patientId": "e58bd10c-69dd-4483-b568-1f13c4d5e6f7",
        "patientName": "Sunita Devi",
        "patientUhid": "UHID-2026-00523",
        "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
        "doctorName": "Dr. Anjali Sharma",
        "departmentName": "General Medicine",
        "appointmentDate": "2026-06-12",
        "appointmentTime": "11:00:00",
        "type": "WALK_IN",
        "status": "CHECKED_IN",
        "checkedInAt": "2026-06-12T10:45:00Z",
        "consultationStartedAt": null,
        "completedAt": null,
        "createdAt": "2026-06-12T10:40:00Z"
      }
    ],
    "page": 0,
    "size": 10,
    "totalElements": 2,
    "totalPages": 1,
    "last": true
  },
  "errors": null
}

Get appointment details

GET/api/v1/opd/appointments/{appointmentId}

Retrieves a single appointment by its UUID. Returns ApiResponse<AppointmentResponse>.

curl https://hospital.katixo.com/api/v1/opd/appointments/b1a2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Check in patient

PUT/api/v1/opd/appointments/{appointmentId}/check-in

Marks the patient as arrived and moves them into the doctor's token queue. Transitions the appointment status from SCHEDULED to CHECKED_IN. The checkedInAt timestamp is recorded automatically.

curl -X PUT https://hospital.katixo.com/api/v1/opd/appointments/b1a2c3d4-e5f6-7890-abcd-ef1234567890/check-in \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Patient checked in successfully",
  "data": {
    "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "tokenNumber": "T-001",
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "patientName": "Rajesh Kumar Verma",
    "patientUhid": "UHID-2026-00451",
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "doctorName": "Dr. Anjali Sharma",
    "departmentName": "General Medicine",
    "appointmentDate": "2026-06-12",
    "appointmentTime": "10:30:00",
    "type": "SCHEDULED",
    "status": "CHECKED_IN",
    "checkedInAt": "2026-06-12T10:15:00Z",
    "consultationStartedAt": null,
    "completedAt": null,
    "createdAt": "2026-06-11T14:20:00Z"
  },
  "errors": null
}

Start consultation

PUT/api/v1/opd/appointments/{appointmentId}/start-consultation

Indicates the doctor has started seeing the patient. Transitions the appointment from CHECKED_IN to IN_CONSULTATION. The consultationStartedAt timestamp is recorded automatically.

curl -X PUT https://hospital.katixo.com/api/v1/opd/appointments/b1a2c3d4-e5f6-7890-abcd-ef1234567890/start-consultation \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Consultation started",
  "data": {
    "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "tokenNumber": "T-001",
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "patientName": "Rajesh Kumar Verma",
    "patientUhid": "UHID-2026-00451",
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "doctorName": "Dr. Anjali Sharma",
    "departmentName": "General Medicine",
    "appointmentDate": "2026-06-12",
    "appointmentTime": "10:30:00",
    "type": "SCHEDULED",
    "status": "IN_CONSULTATION",
    "checkedInAt": "2026-06-12T10:15:00Z",
    "consultationStartedAt": "2026-06-12T10:32:00Z",
    "completedAt": null,
    "createdAt": "2026-06-11T14:20:00Z"
  },
  "errors": null
}

Complete consultation

PUT/api/v1/opd/appointments/{appointmentId}/complete

Marks the consultation as finished. Transitions the appointment from IN_CONSULTATION to COMPLETED. A prescription should be created before or alongside completing the consultation.

curl -X PUT https://hospital.katixo.com/api/v1/opd/appointments/b1a2c3d4-e5f6-7890-abcd-ef1234567890/complete \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Consultation completed",
  "data": {
    "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "tokenNumber": "T-001",
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "patientName": "Rajesh Kumar Verma",
    "patientUhid": "UHID-2026-00451",
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "doctorName": "Dr. Anjali Sharma",
    "departmentName": "General Medicine",
    "appointmentDate": "2026-06-12",
    "appointmentTime": "10:30:00",
    "type": "SCHEDULED",
    "status": "COMPLETED",
    "checkedInAt": "2026-06-12T10:15:00Z",
    "consultationStartedAt": "2026-06-12T10:32:00Z",
    "completedAt": "2026-06-12T10:48:00Z",
    "createdAt": "2026-06-11T14:20:00Z"
  },
  "errors": null
}

Get token queue

GET/api/v1/opd/queue

Returns the current token queue for a doctor on a given date. The queue is ordered by check-in time and includes estimated wait times based on average consultation duration.

Query parameters

Parameter	Type	Description
`doctorId`	UUID	Required. The doctor whose queue to retrieve.
`date`	LocalDate	Date to query (YYYY-MM-DD). Defaults to today.

curl "https://hospital.katixo.com/api/v1/opd/queue?doctorId=d1e2f3a4-b5c6-7890-dcba-fe0987654321&date=2026-06-12" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Queue retrieved successfully",
  "data": {
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "doctorName": "Dr. Anjali Sharma",
    "departmentName": "General Medicine",
    "date": "2026-06-12",
    "currentToken": "T-001",
    "totalInQueue": 4,
    "averageConsultationMinutes": 15,
    "queue": [
      {
        "position": 1,
        "tokenNumber": "T-001",
        "appointmentId": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
        "patientName": "Rajesh Kumar Verma",
        "patientUhid": "UHID-2026-00451",
        "status": "IN_CONSULTATION",
        "checkedInAt": "2026-06-12T10:15:00Z",
        "estimatedWaitMinutes": 0
      },
      {
        "position": 2,
        "tokenNumber": "T-002",
        "appointmentId": "c2b3d4e5-f6a7-8901-bcde-f12345678901",
        "patientName": "Sunita Devi",
        "patientUhid": "UHID-2026-00523",
        "status": "CHECKED_IN",
        "checkedInAt": "2026-06-12T10:45:00Z",
        "estimatedWaitMinutes": 8
      },
      {
        "position": 3,
        "tokenNumber": "T-003",
        "appointmentId": "d3c4e5f6-a7b8-9012-cdef-234567890123",
        "patientName": "Mohammed Irfan",
        "patientUhid": "UHID-2026-00612",
        "status": "CHECKED_IN",
        "checkedInAt": "2026-06-12T11:02:00Z",
        "estimatedWaitMinutes": 23
      },
      {
        "position": 4,
        "tokenNumber": "T-004",
        "appointmentId": "e4d5f6a7-b8c9-0123-def0-345678901234",
        "patientName": "Priya Singh",
        "patientUhid": "UHID-2026-00487",
        "status": "CHECKED_IN",
        "checkedInAt": "2026-06-12T11:10:00Z",
        "estimatedWaitMinutes": 38
      }
    ]
  },
  "errors": null
}

Create prescription

POST/api/v1/opd/prescriptions

Creates a prescription record for an OPD consultation. Includes diagnosis, vitals, medications, lab test orders, and follow-up scheduling. Returns 201 Created on success.

Request body

Field	Type	Required	Description
`appointmentId`	UUID	Yes	The appointment this prescription is for.
`diagnosis`	String	Yes	Primary diagnosis (e.g. "Acute viral fever with pharyngitis").
`complaints`	String	Yes	Chief complaints as described by the patient.
`vitals`	Object	No	Patient vitals: `bp`, `pulse`, `temp`, `weight`, `height`, `spo2`.
`medications`	Array	No	Array of medications. Each: `drugName`, `dosage`, `frequency`, `duration`, `instructions`.
`labTests`	UUID[]	No	Array of lab test IDs to order (e.g. CBC, Dengue NS1).
`followUpDate`	LocalDate	No	Recommended follow-up date (YYYY-MM-DD).

Vitals object

Field	Type	Description
`bp`	String	Blood pressure (e.g. "120/80").
`pulse`	int	Pulse rate in beats per minute.
`temp`	BigDecimal	Body temperature in Fahrenheit.
`weight`	BigDecimal	Body weight in kilograms.
`height`	BigDecimal	Height in centimeters.
`spo2`	int	Oxygen saturation percentage.

Medication object

Field	Type	Description
`drugName`	String	Name of the drug (e.g. "Paracetamol 500mg").
`dosage`	String	Dosage (e.g. "1 tablet", "5ml").
`frequency`	String	How often (e.g. "TDS" for three times daily, "BD" for twice daily, "OD" for once daily).
`duration`	String	Duration of course (e.g. "5 days", "2 weeks").
`instructions`	String	Special instructions (e.g. "After meals", "At bedtime", "With lukewarm water").

Example: create a prescription

curl -X POST https://hospital.katixo.com/api/v1/opd/prescriptions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "appointmentId": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "diagnosis": "Acute viral fever with pharyngitis",
    "complaints": "High fever for 3 days, sore throat, body ache, headache",
    "vitals": {
      "bp": "120/80",
      "pulse": 92,
      "temp": 101.4,
      "weight": 72.5,
      "height": 170,
      "spo2": 97
    },
    "medications": [
      {
        "drugName": "Paracetamol 500mg",
        "dosage": "1 tablet",
        "frequency": "TDS",
        "duration": "5 days",
        "instructions": "After meals. Take if fever above 100°F."
      },
      {
        "drugName": "Azithromycin 500mg",
        "dosage": "1 tablet",
        "frequency": "OD",
        "duration": "3 days",
        "instructions": "Before meals on empty stomach"
      },
      {
        "drugName": "Cetirizine 10mg",
        "dosage": "1 tablet",
        "frequency": "OD",
        "duration": "5 days",
        "instructions": "At bedtime"
      },
      {
        "drugName": "Pantoprazole 40mg",
        "dosage": "1 tablet",
        "frequency": "OD",
        "duration": "5 days",
        "instructions": "Before breakfast on empty stomach"
      }
    ],
    "labTests": [
      "aa11bb22-cc33-dd44-ee55-ff6677889900",
      "bb22cc33-dd44-ee55-ff66-778899001122"
    ],
    "followUpDate": "2026-06-17"
  }'

# Response (201 Created)
{
  "success": true,
  "message": "Prescription created successfully",
  "data": {
    "id": "f5e6d7c8-b9a0-1234-5678-901234567890",
    "appointmentId": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "patientName": "Rajesh Kumar Verma",
    "patientUhid": "UHID-2026-00451",
    "doctorId": "d1e2f3a4-b5c6-7890-dcba-fe0987654321",
    "doctorName": "Dr. Anjali Sharma",
    "departmentName": "General Medicine",
    "diagnosis": "Acute viral fever with pharyngitis",
    "complaints": "High fever for 3 days, sore throat, body ache, headache",
    "vitals": {
      "bp": "120/80",
      "pulse": 92,
      "temp": 101.4,
      "weight": 72.5,
      "height": 170,
      "spo2": 97
    },
    "medications": [
      {
        "id": "11aa22bb-33cc-44dd-55ee-66ff77889900",
        "drugName": "Paracetamol 500mg",
        "dosage": "1 tablet",
        "frequency": "TDS",
        "duration": "5 days",
        "instructions": "After meals. Take if fever above 100°F."
      },
      {
        "id": "22bb33cc-44dd-55ee-66ff-778899001122",
        "drugName": "Azithromycin 500mg",
        "dosage": "1 tablet",
        "frequency": "OD",
        "duration": "3 days",
        "instructions": "Before meals on empty stomach"
      },
      {
        "id": "33cc44dd-55ee-66ff-7788-990011223344",
        "drugName": "Cetirizine 10mg",
        "dosage": "1 tablet",
        "frequency": "OD",
        "duration": "5 days",
        "instructions": "At bedtime"
      },
      {
        "id": "44dd55ee-66ff-7788-9900-112233445566",
        "drugName": "Pantoprazole 40mg",
        "dosage": "1 tablet",
        "frequency": "OD",
        "duration": "5 days",
        "instructions": "Before breakfast on empty stomach"
      }
    ],
    "labTests": [
      {
        "id": "aa11bb22-cc33-dd44-ee55-ff6677889900",
        "testName": "Complete Blood Count (CBC)",
        "status": "ORDERED"
      },
      {
        "id": "bb22cc33-dd44-ee55-ff66-778899001122",
        "testName": "Dengue NS1 Antigen",
        "status": "ORDERED"
      }
    ],
    "followUpDate": "2026-06-17",
    "createdAt": "2026-06-12T10:48:00Z"
  },
  "errors": null
}

Appointment workflow

The typical OPD flow follows these state transitions:

1Book — POST /api/v1/opd/appointments → status becomes SCHEDULED

2Check In — PUT .../check-in → status becomes CHECKED_IN, patient enters queue

3Start Consultation — PUT .../start-consultation → status becomes IN_CONSULTATION

4Prescribe — POST /api/v1/opd/prescriptions → creates prescription with medications and lab orders

5Complete — PUT .../complete → status becomes COMPLETED

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",
    "doctorId: must not be null",
    "appointmentDate: must not be null"
  ]
}

# 404 Not Found
{
  "success": false,
  "message": "Appointment not found",
  "data": null,
  "errors": ["No appointment found with id: b1a2c3d4-e5f6-7890-abcd-ef1234567890"]
}

# 409 Conflict — invalid state transition
{
  "success": false,
  "message": "Invalid status transition",
  "data": null,
  "errors": ["Cannot start consultation: appointment status is SCHEDULED, must be CHECKED_IN"]
}

# 409 Conflict — doctor slot unavailable
{
  "success": false,
  "message": "Slot unavailable",
  "data": null,
  "errors": ["Dr. Anjali Sharma already has an appointment at 10:30 on 2026-06-12"]
}