DeveloperQueue
Queue Management System
This document describes the implementation, API endpoints, and data structures for the queue management system in the CMS application.
Overview
The queue management system provides real-time tracking of patient appointments with the following features:
- Real-time Updates: Live queue updates using Ably WebSocket integration
- Status Management: Track patients through various stages of their visit
- Doctor Filtering: View queue by specific doctors or all doctors
- Date Navigation: Browse queue for different dates
- Category Support: Filter patients by clinic categories
Queue States
- Waiting: Patient checked in and waiting to be seen
- In Consultation: Patient currently with the doctor
- Completed: Consultation finished
- Cancelled: Appointment cancelled
- No Show: Patient didn't arrive
API Endpoints
1. Get Clinic Queue
Retrieves the complete queue for a clinic, including all doctors' appointments.
Endpoint:
GET https://api-stg.kulcare.com/clinics/{clinic_id}/queueParameters:
clinic_id(required): The unique identifier for the clinicdate(optional): Date in YYYY-MM-DD format (defaults to today)doctor_id(optional): Filter by specific doctor
Example Requests:
# Get today's queue
GET https://api-stg.kulcare.com/clinics/201090/queue
# Get queue for specific date
GET https://api-stg.kulcare.com/clinics/201090/queue?date=2025-07-24
# Get queue for specific doctor
GET https://api-stg.kulcare.com/clinics/201090/queue?doctor_id=2016852. Get Doctor-Specific Queue
Retrieves the queue for a specific doctor within a clinic.
Endpoint:
GET https://api-stg.kulcare.com/clinics/{clinic_id}/clinic_doctors/{clinic_doctor_id}/queueParameters:
clinic_id(required): The unique identifier for the clinicclinic_doctor_id(required): The unique identifier for the clinic doctor (e.g., 201685)
Example Request:
GET https://api-stg.kulcare.com/clinics/201090/clinic_doctors/201685/queueResponse Structure
Both endpoints return the same response format:
{
"queue": {
"data": [
{
"id": "29525",
"type": "appointment",
"attributes": {
"id": 29525,
"token_number": "5543K3UL",
"appointment_time": "2025-07-24T05:06:00.000Z",
"appointment_type": "WALKIN",
"appointment_status": "CHECKED_IN",
"created_at": "2025-07-23T08:18:34.138Z",
"referred_by": null,
"preferred_start_time": null,
"preferred_end_time": null,
"checked_in_at": null,
"created_by_id": null,
"created_by_type": null,
"booked_at": "2025-07-23T08:18:34.137Z",
"from_public_website": false,
"reason_for_visit": null,
"from_patient_app": false,
"payment_option": null,
"role": "owner",
"verified": false,
"verified_at": null,
"follow_up": false,
"cancelled_at": null,
"cancellation_reason": null,
"follow_up_type": null,
"added_to_ipd": false,
"time_to_doctor": "2025-07-24T05:06:00.000Z",
"careplan_id": null,
"status_updated_at": "2025-07-23T08:20:08.652Z",
"avg_duration": 45,
"lastest_bill_id": null,
"next_visit": null,
"session_details": {},
"total_billing_amount": 0,
"amount_received": 0,
"remaining_amount": 0,
"paid_billing_amount": 0,
"unpaid_billing_amount": 0,
"day_billing_details": {
"bills_generated": false,
"total_paid_amount": 0,
"total_service_amount": null
},
"patient_notes": null,
"patient_vitals": [],
"patient_details": {
"id": 17131,
"photo": null,
"unique_id": "MS001226",
"country_code": "91",
"phone_number": "7892032332",
"dob": "1991-07-01",
"gender": "Female",
"address_line_1": null,
"address_line_2": null,
"city": null,
"state": null,
"zipcode": null,
"latitude": null,
"longitude": null,
"email": null,
"attendant_name": null,
"attendant_country_code": null,
"attendant_phone_number": null,
"attendant_relation": null,
"dummy": false,
"age_str": "34y",
"first_name": "Antenaty",
"last_name": "User",
"age": 34,
"name": "Antenaty User",
"clinic_patient_id": 23149,
"last_visit": "2025-07-23T08:11:56.199Z",
"bills_generated": false,
"paid_amount": 0,
"unpaid_amount": 600.0,
"total_paid_amount": 0,
"total_service_amount": 600.0,
"language": {
"id": 1,
"name": "English",
"default_name": "en"
},
"alpha_2_code": "IN",
"parent_name": "",
"parent_relation": null,
"clinic_categories": []
},
"doctor_details": {
"id": 84142,
"photo": "https://kulcare-stag-profile-images.s3.ap-south-1.amazonaws.com/doctor_profile_images/doctor_images_84142/1609916389606_10%20years%20experience.png",
"clinic_doctor_id": 201685,
"name": "Aastha Verma",
"full_name": "Dr. Aastha Verma",
"first_name": "Aastha",
"speciality": "Pediatric Physiatrist",
"reg_nbr": "12341234",
"doctor_schedule": [
{
"id": 295319,
"start_time": "2000-01-01T05:00:00.000Z",
"end_time": "2000-01-01T17:30:00.000Z",
"days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"timezone": "Asia/Kolkata"
}
],
"telemedicine_setup": true,
"fees": 500.0,
"telemedicine_fees": 500.0,
"country_code": "91",
"phone_number": "5534003400"
},
"clinic_details": {
"id": 201090,
"name": "Therapy Clinic 92 ",
"covid_clinic": false,
"private_clinic": false,
"country_code": "91",
"phone_number": "5534003400",
"timezone": "Asia/Kolkata",
"location": {
"id": 200807,
"address_line_1": "92, Circular Road, Jawala Nagar, Shahdara, Delhi, Delhi, India",
"address_line_2": null,
"city": "East Delhi",
"state": null,
"country_code": "91",
"phone_number": "5534003400",
"zipcode": "110032",
"email": "5534003400@yopmail.com",
"website": null,
"latitude": 28.6707811,
"longitude": 77.29454609999999,
"phone_numbers": [
{
"id": 757,
"country_code": "91",
"phone_number": "5512341234",
"phone_type": "Reception"
},
{
"id": 758,
"country_code": "91",
"phone_number": "",
"phone_type": "OPD"
},
{
"id": 759,
"country_code": "91",
"phone_number": "",
"phone_type": "Emergency"
}
]
},
"logo_url": null
}
}
}
],
"meta": {
"day_start_time": "2000-01-01T03:30:00.000Z",
"checked_in_at": null,
"confirmed_appointments_count": 1,
"freemium_user": false
}
},
"out_of_queue": {
"data": [],
"meta": {
"day_start_time": "2000-01-01T03:30:00.000Z",
"checked_in_at": null,
"confirmed_appointments_count": 1,
"freemium_user": false
}
}
}Response Overview
The response contains two main sections:
queue- Contains appointments currently in the active queueout_of_queue- Contains appointments that have left the queue
Both sections include:
data- Array of appointment objectsmeta- Metadata about the queue state
Appointment Node Structure
Each appointment in the queue follows this detailed structure:
Root Level
id: String - Unique appointment identifiertype: String - Always "appointment" for queue itemsattributes: Object - Contains all appointment details
Attributes Object
Basic Appointment Info
id: Number - Numeric appointment IDtoken_number: String - Display token for the appointment (e.g., "5543K3UL")appointment_time: ISO String - Scheduled appointment timeappointment_type: String - Type of appointment ("WALKIN", "SCHEDULED", etc.)appointment_status: String - Current status ("CHECKED_IN", "WAITING", "COMPLETED", etc.)avg_duration: Number - Expected duration in minutes
Timestamps
created_at: ISO String - When appointment was createdbooked_at: ISO String - When appointment was bookedchecked_in_at: ISO String | null - When patient checked instatus_updated_at: ISO String - Last status change timetime_to_doctor: ISO String - Estimated time to see doctor
Appointment Details
role: String - Patient's role ("owner", "dependent")verified: Boolean - Whether appointment is verifiedverified_at: ISO String | null - Verification timestampfollow_up: Boolean - Is this a follow-up appointmentfollow_up_type: String | null - Type of follow-up if applicablereason_for_visit: String | null - Visit purposereferred_by: String | null - Referral source
Financial Information
total_billing_amount: Number - Total amount to be billedamount_received: Number - Amount already paidremaining_amount: Number - Outstanding amountpaid_billing_amount: Number - Confirmed paid amountunpaid_billing_amount: Number - Unpaid portionday_billing_details: Object containing:bills_generated: Boolean - Whether bills have been createdtotal_paid_amount: Number - Total paid for the daytotal_service_amount: Number | null - Total service charges
Patient Details Object
Contains comprehensive patient information:
- Identity:
id,unique_id,clinic_patient_id - Personal:
first_name,last_name,name,dob,gender,age,age_str - Contact:
country_code,phone_number,email - Address:
address_line_1,address_line_2,city,state,zipcode - Medical:
last_visit,patient_vitals[],patient_notes - Financial:
paid_amount,unpaid_amount,total_paid_amount,total_service_amount - System:
dummy,languageobject,alpha_2_code,clinic_categories[]
Doctor Details Object
Information about the assigned doctor:
- Identity:
id,clinic_doctor_id,reg_nbr - Personal:
name,full_name,first_name,speciality - Contact:
country_code,phone_number,photoURL - Services:
fees,telemedicine_fees,telemedicine_setup - Schedule:
doctor_schedule[]array containing:id: Schedule IDstart_time/end_time: Working hours (note: uses 2000-01-01 date placeholder)days[]: Array of working days ("Mon", "Tue", etc.)timezone: Doctor's timezone
Clinic Details Object
Information about the clinic:
- Basic Info:
id,name,timezone,logo_url - Type:
covid_clinic,private_clinicbooleans - Contact:
country_code,phone_number - Location Object:
- Address: Full address details with coordinates
- Contact: Multiple phone numbers with types (Reception, OPD, Emergency)
- Digital: Email, website
Key Implementation Notes
-
Date Handling:
- Appointment times use actual dates
- Doctor schedules use "2000-01-01" as date placeholder (only time matters)
- All times are in ISO format with timezone info
-
Financial Tracking:
- Multiple amount fields for different billing states
- Day-level billing summary separate from appointment billing
-
Status Flow:
- Appointments move through various statuses
checked_in_attracks actual check-in vs scheduled time
-
Null Safety:
- Many optional fields can be null
- Always check for null values before using
Additional API Endpoints
Get Patient Categories
Retrieves all patient categories for a specific clinic.
Endpoint:
GET https://api-stg.kulcare.com/clinics/{clinic_id}/categoriesExample Request:
GET https://api-stg.kulcare.com/clinics/201090/categoriesResponse:
{
"success": true,
"message": "list fetched",
"data": {
"clinic_categories": [
{
"id": 251,
"name": "Get Well Best",
"description": null,
"color_code": "0067A5",
"created_at": "2025-07-16T06:31:01.991Z",
"category_rules": [],
"category_services": []
},
{
"id": 232,
"name": "Pre-natal 3 months",
"description": null,
"color_code": "E68FAC",
"created_at": "2025-01-03T09:56:41.791Z",
"category_rules": [],
"category_services": []
},
{
"id": 230,
"name": "Tele 60",
"description": null,
"color_code": "008856",
"created_at": "2024-12-29T18:12:42.326Z",
"category_rules": [],
"category_services": []
},
{
"id": 229,
"name": "back pain therapy ",
"description": null,
"color_code": "848482",
"created_at": "2024-12-26T12:00:55.972Z",
"category_rules": [],
"category_services": []
},
{
"id": 220,
"name": "therpay session",
"description": null,
"color_code": "C2B280",
"created_at": "2024-10-08T12:06:39.875Z",
"category_rules": [],
"category_services": []
},
{
"id": 218,
"name": "x ray",
"description": null,
"color_code": "BE0032",
"created_at": "2024-09-12T09:48:45.462Z",
"category_rules": [],
"category_services": []
},
{
"id": 212,
"name": "hydrafacial",
"description": null,
"color_code": "F3C300",
"created_at": "2024-08-12T05:29:01.832Z",
"category_rules": [],
"category_services": []
},
{
"id": 79,
"name": "Ambulance",
"description": null,
"color_code": "A1CAF1",
"created_at": "2021-05-18T07:01:49.061Z",
"category_rules": [
{
"id": 80,
"min_age": null,
"max_age": null,
"gender_list": [],
"created_at": "2021-05-18T07:01:49.081Z",
"rule_type": "AGE_GENDER"
}
],
"category_services": []
},
{
"id": 78,
"name": "Emergency",
"description": null,
"color_code": "F38400",
"created_at": "2021-05-18T07:01:43.959Z",
"category_rules": [
{
"id": 79,
"min_age": null,
"max_age": null,
"gender_list": [],
"created_at": "2021-05-18T07:01:43.973Z",
"rule_type": "AGE_GENDER"
}
],
"category_services": []
},
{
"id": 77,
"name": "ICU Bed",
"description": null,
"color_code": "875692",
"created_at": "2021-05-18T07:01:35.948Z",
"category_rules": [
{
"id": 78,
"min_age": null,
"max_age": null,
"gender_list": [],
"created_at": "2021-05-18T07:01:35.966Z",
"rule_type": "AGE_GENDER"
}
],
"category_services": []
},
{
"id": 71,
"name": "Senior Citizens",
"description": "Test",
"color_code": "222222",
"created_at": "2021-01-04T10:36:00.666Z",
"category_rules": [
{
"id": 72,
"min_age": 60,
"max_age": null,
"gender_list": [
"Male",
"Female",
"Other"
],
"created_at": "2021-01-04T10:36:00.685Z",
"rule_type": "AGE_GENDER"
}
],
"category_services": [
{
"id": 91,
"discount_percentage": 10.0,
"clinic_service_ids": [
2401
],
"clinic_services": [
{
"id": 330,
"clinic_service_id": 2401,
"name": null
}
]
}
]
}
]
}
}
```
### Get Clinic Doctors
Retrieves all doctors associated with a specific clinic.
**Endpoint:**
```http
GET https://api-stg.kulcare.com/clinics/{clinic_id}/clinic_doctors?basic=true
```
**Example Request:**
```http
GET https://api-stg.kulcare.com/clinics/201090/clinic_doctors?basic=true
```
**Response:**
```json
{
"success": true,
"message": "list fetched",
"data": {
"doctors_list": [
{
"id": 201685,
"fees": 500.0,
"invited_at": null,
"photo": "https://kulcare-stag-profile-images.s3.ap-south-1.amazonaws.com/doctor_profile_images/doctor_images_84142/1609916389606_10%20years%20experience.png",
"telemedicine_fees": 500.0,
"fixed_appt_fees": 500.0,
"int_telemedicine_fees": null,
"int_basic_currency_id": null,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "5534003400",
"telemedicine_setup": true,
"available": true,
"schedules_exist": true,
"profile_completion_percent": 100,
"listed": true,
"unique_id": "LqaeX4EQl",
"cms_onboarding_complete": true,
"is_psychiatrist": false,
"schedules": [
{
"id": 295319,
"start_time": "2000-01-01T05:00:00.000Z",
"end_time": "2000-01-01T17:30:00.000Z",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"timezone": "Asia/Kolkata"
}
],
"formatted_schedules": [
{
"days": [
"Mon-Fri"
],
"time": [
{
"id": 295319,
"start_time": "10:30 am",
"end_time": "11:00 pm"
}
]
}
],
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Dr. Aastha Verma in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Dr. Aastha Verma is a Pediatric Physiatrist, MD with 15 years of experience",
"seo_type": "doctor_details"
},
"doctor": {
"id": 84142,
"first_name": "Aastha",
"last_name": "Verma",
"verified": true,
"gender": "Female",
"bio": "I love being a doctor. I love helping heal people of distress and ailments. I've spend 15 years of my valuable life learning how to heal people and I want to dedicate the next 40 years in the service of humanity. \n\nI do not wish to seek any awards or accolades for my services but if they do come my way that would be a really lovely thing. I would also like it to put it out there it would not hurt to also have a lot of money and some luxuries of life. Some vaunted interactional tourist destinations would also be nice. Hopefully at least once an year for the next 40 years. ",
"exp": 15,
"photo": " ",
"reg_nbr": "12341234",
"reg_photo_url": "https://kulcare-stag-profile-images.s3.ap-south-1.amazonaws.com/doctor_medical_license_images/doctor_84142/1635909286532_Screenshot 2021-09-17 at 4.54.03 PM.png",
"verified_at": "2021-11-03T03:15:49.602Z",
"achievements": null,
"education": "MD",
"title": "Dr. Aastha Verma",
"patients_per_hour": 10,
"slot_minutes": 45,
"country_code": "91",
"phone_number": "5534003400",
"speciality": "Pediatric Physiatrist",
"other_specialities": []
},
"spec_modules": [],
"search_keywords_list": []
},
{
"id": 206024,
"fees": 600.0,
"invited_at": "2024-10-24 03:39:50 +0000",
"photo": null,
"telemedicine_fees": 600.0,
"fixed_appt_fees": null,
"int_telemedicine_fees": null,
"int_basic_currency_id": null,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "5566666665",
"telemedicine_setup": true,
"available": true,
"schedules_exist": true,
"profile_completion_percent": 52,
"listed": false,
"unique_id": "lQ4Pv3yQ4",
"cms_onboarding_complete": true,
"is_psychiatrist": false,
"schedules": [
{
"id": 295224,
"start_time": "2000-01-01T03:30:00.000Z",
"end_time": "2000-01-01T17:30:00.000Z",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat",
"Sun"
],
"timezone": "Asia/Kolkata"
}
],
"formatted_schedules": [
{
"days": [
"Mon-Sun"
],
"time": [
{
"id": 295224,
"start_time": " 9:00 am",
"end_time": "11:00 pm"
}
]
}
],
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Dr. Aditi in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Dr. Aditi is a Gynecologist/Obstetricianwith 7 years of experience",
"seo_type": "doctor_details"
},
"doctor": {
"id": 87018,
"first_name": "Aditi",
"last_name": "",
"verified": true,
"gender": "Female",
"bio": null,
"exp": 7,
"photo": null,
"reg_nbr": "12345",
"reg_photo_url": null,
"verified_at": "2024-10-24T04:14:45.494Z",
"achievements": null,
"education": null,
"title": "Dr. Aditi",
"patients_per_hour": 6,
"slot_minutes": 45,
"country_code": "91",
"phone_number": "5566666665",
"speciality": "Gynecologist/Obstetrician",
"other_specialities": [
{
"id": 114789,
"doctor_id": 87018,
"name": "Gynecologist",
"spl_type": "OTHER",
"created_at": "2024-10-24T03:40:47.877Z",
"updated_at": "2024-10-24T03:40:47.878Z",
"basic_speciality_id": 19
}
]
},
"spec_modules": [],
"search_keywords_list": []
},
{
"id": 206004,
"fees": 500.0,
"invited_at": null,
"photo": null,
"telemedicine_fees": 300.0,
"fixed_appt_fees": null,
"int_telemedicine_fees": null,
"int_basic_currency_id": null,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "9465477157",
"telemedicine_setup": true,
"available": true,
"schedules_exist": false,
"profile_completion_percent": 53,
"listed": true,
"unique_id": "xQ95D93QP",
"cms_onboarding_complete": true,
"is_psychiatrist": true,
"schedules": [],
"formatted_schedules": null,
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Madhav in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Madhav is a Psychiatrist, MBBS with 3 years of experience",
"seo_type": "doctor_details"
},
"doctor": {
"id": 87009,
"first_name": "Madhav",
"last_name": "",
"verified": true,
"gender": "Male",
"bio": "kkslkslk",
"exp": 3,
"photo": null,
"reg_nbr": "qwwedsd213232",
"reg_photo_url": null,
"verified_at": "2024-07-30T06:18:51.935Z",
"achievements": null,
"education": "MBBS",
"title": "Madhav",
"patients_per_hour": 2,
"slot_minutes": null,
"country_code": "91",
"phone_number": "9465477157",
"speciality": "Psychiatrist",
"other_specialities": [
{
"id": 114836,
"doctor_id": 87009,
"name": "test",
"spl_type": "OTHER",
"created_at": "2025-07-17T12:12:51.753Z",
"updated_at": "2025-07-17T12:12:51.753Z",
"basic_speciality_id": null
}
]
},
"spec_modules": [],
"search_keywords_list": []
},
{
"id": 205999,
"fees": 500.0,
"invited_at": "2024-09-09 05:48:10 +0000",
"photo": null,
"telemedicine_fees": 600.0,
"fixed_appt_fees": null,
"int_telemedicine_fees": 100.0,
"int_basic_currency_id": 2,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "5675777777",
"telemedicine_setup": false,
"available": true,
"schedules_exist": false,
"profile_completion_percent": 18,
"listed": false,
"unique_id": "4Q8Ae57a0",
"cms_onboarding_complete": true,
"is_psychiatrist": true,
"schedules": [],
"formatted_schedules": null,
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Raghav in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Raghav is a Psychiatrist",
"seo_type": "doctor_details"
},
"doctor": {
"id": 87010,
"first_name": "Raghav",
"last_name": "",
"verified": false,
"gender": null,
"bio": null,
"exp": null,
"photo": null,
"reg_nbr": null,
"reg_photo_url": null,
"verified_at": null,
"achievements": null,
"education": null,
"title": "Raghav",
"patients_per_hour": 6,
"slot_minutes": null,
"country_code": "91",
"phone_number": "5675777777",
"speciality": "Psychiatrist",
"other_specialities": []
},
"spec_modules": [],
"search_keywords_list": []
},
{
"id": 205284,
"fees": 100.0,
"invited_at": null,
"photo": null,
"telemedicine_fees": 120.0,
"fixed_appt_fees": null,
"int_telemedicine_fees": null,
"int_basic_currency_id": null,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "5510239102",
"telemedicine_setup": true,
"available": true,
"schedules_exist": true,
"profile_completion_percent": 55,
"listed": true,
"unique_id": "gQw5nAkR4",
"cms_onboarding_complete": true,
"is_psychiatrist": false,
"schedules": [
{
"id": 294896,
"start_time": "2000-01-01T03:30:00.000Z",
"end_time": "2000-01-01T17:30:00.000Z",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat",
"Sun"
],
"timezone": "Asia/Kolkata"
}
],
"formatted_schedules": [
{
"days": [
"Mon-Sun"
],
"time": [
{
"id": 294896,
"start_time": " 9:00 am",
"end_time": "11:00 pm"
}
]
}
],
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Dr. Therapist in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Dr. Therapist is a Occupational Therapist",
"seo_type": "doctor_details"
},
"doctor": {
"id": 85719,
"first_name": "Therapist",
"last_name": "",
"verified": true,
"gender": "Male",
"bio": null,
"exp": null,
"photo": null,
"reg_nbr": "asd",
"reg_photo_url": "https://kulcare-stag-profile-images.s3.ap-south-1.amazonaws.com/doctor_medical_license_images/doctor_85719/1646913161332_Screen Shot 2022-03-10 at 9.41.55 AM.png",
"verified_at": "2022-03-10T11:54:17.319Z",
"achievements": null,
"education": null,
"title": "Dr. Therapist",
"patients_per_hour": 10,
"slot_minutes": null,
"country_code": "91",
"phone_number": "5510239102",
"speciality": "Occupational Therapist",
"other_specialities": []
},
"spec_modules": [
{
"id": 73,
"spec_module_id": 1,
"activated_at": "2022-10-11T07:02:46.181Z",
"name": "Psychiatrist"
}
],
"search_keywords_list": []
},
{
"id": 204668,
"fees": 900.0,
"invited_at": null,
"photo": null,
"telemedicine_fees": 200.0,
"fixed_appt_fees": null,
"int_telemedicine_fees": null,
"int_basic_currency_id": null,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "5555523399",
"telemedicine_setup": true,
"available": false,
"schedules_exist": true,
"profile_completion_percent": 54,
"listed": false,
"unique_id": "g0aYO2oj3",
"cms_onboarding_complete": true,
"is_psychiatrist": false,
"schedules": [
{
"id": 294892,
"start_time": "2000-01-01T03:30:00.000Z",
"end_time": "2000-01-01T17:30:00.000Z",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat",
"Sun"
],
"timezone": "Asia/Kolkata"
}
],
"formatted_schedules": [
{
"days": [
"Mon-Sun"
],
"time": [
{
"id": 294892,
"start_time": " 9:00 am",
"end_time": "11:00 pm"
}
]
}
],
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Dr. Pediatrics Doctor in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Dr. Pediatrics Doctor is a Pediatrician, mbbs with 4 years of experience",
"seo_type": "doctor_details"
},
"doctor": {
"id": 84566,
"first_name": "Pediatrics",
"last_name": "Doctor",
"verified": true,
"gender": "Male",
"bio": null,
"exp": 4,
"photo": null,
"reg_nbr": "56373832",
"reg_photo_url": null,
"verified_at": "2021-09-09T11:30:56.721Z",
"achievements": null,
"education": "mbbs",
"title": "Dr. Pediatrics Doctor",
"patients_per_hour": 5,
"slot_minutes": null,
"country_code": "91",
"phone_number": "5555523399",
"speciality": "Pediatrician",
"other_specialities": []
},
"spec_modules": [
{
"id": 41,
"spec_module_id": 2,
"activated_at": "2022-05-25T10:37:02.889Z",
"name": "Pediatrician"
}
],
"search_keywords_list": []
},
{
"id": 204667,
"fees": 200.0,
"invited_at": null,
"photo": null,
"telemedicine_fees": 300.0,
"fixed_appt_fees": null,
"int_telemedicine_fees": 500.0,
"int_basic_currency_id": 2,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "5515022000",
"telemedicine_setup": true,
"available": false,
"schedules_exist": true,
"profile_completion_percent": 85,
"listed": false,
"unique_id": "3VjrWKBQN",
"cms_onboarding_complete": true,
"is_psychiatrist": true,
"schedules": [
{
"id": 295205,
"start_time": "2000-01-01T03:30:00.000Z",
"end_time": "2000-01-01T16:30:00.000Z",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat",
"Sun"
],
"timezone": "Asia/Kolkata"
}
],
"formatted_schedules": [
{
"days": [
"Mon-Sun"
],
"time": [
{
"id": 295205,
"start_time": " 9:00 am",
"end_time": "10:00 pm"
}
]
}
],
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Psychiatrist Doctor in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Psychiatrist Doctor is a Psychiatrist, mbbs with 20 years of experience",
"seo_type": "doctor_details"
},
"doctor": {
"id": 84075,
"first_name": "Psychiatrist",
"last_name": "Doctor",
"verified": true,
"gender": "Male",
"bio": "asdasd",
"exp": 20,
"photo": "",
"reg_nbr": "masndkas",
"reg_photo_url": "",
"verified_at": "2024-10-01T13:47:04.724Z",
"achievements": null,
"education": "mbbs",
"title": "Psychiatrist Doctor",
"patients_per_hour": 10,
"slot_minutes": null,
"country_code": "91",
"phone_number": "5515022000",
"speciality": "Psychiatrist",
"other_specialities": []
},
"spec_modules": [
{
"id": 42,
"spec_module_id": 1,
"activated_at": "2022-05-25T10:37:10.552Z",
"name": "Psychiatrist"
}
],
"search_keywords_list": []
},
{
"id": 201752,
"fees": 400.0,
"invited_at": null,
"photo": "https://kulcare-stag-profile-images.s3.ap-south-1.amazonaws.com/doctor_profile_images/doctor_83679/1609753902880_20%20years%20experience.png",
"telemedicine_fees": 500.0,
"fixed_appt_fees": 400.0,
"int_telemedicine_fees": null,
"int_basic_currency_id": null,
"clinic_id": 201090,
"clinic_name": "Therapy Clinic 92 ",
"takes_in_clinic": true,
"use_kulcare_appts": true,
"status": "JOINED",
"country_code": "91",
"phone_number": "2002002002",
"telemedicine_setup": true,
"available": false,
"schedules_exist": true,
"profile_completion_percent": 42,
"listed": false,
"unique_id": "y0jNg02QW",
"cms_onboarding_complete": true,
"is_psychiatrist": false,
"schedules": [
{
"id": 293070,
"start_time": "2000-01-01T03:30:00.000Z",
"end_time": "2000-01-01T14:30:00.000Z",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat"
],
"timezone": "Asia/Kolkata"
}
],
"formatted_schedules": [
{
"days": [
"Mon-Sat"
],
"time": [
{
"id": 293070,
"start_time": " 9:00 am",
"end_time": " 8:00 pm"
}
]
}
],
"discount_schedule": [],
"google_account_connected": false,
"seo": {
"title": "Dr. Dermatology in Therapy Clinic 92 | Cardiology (Heart Care) Clinic in East Delhi.",
"description": "Therapy Clinic 92 is a Cardiology (Heart Care) Clinic in East Delhi. Dr. Dermatology is a Dermatologist/Cosmetologist, DM Cardiology with 20 years of experience",
"seo_type": "doctor_details"
},
"doctor": {
"id": 83679,
"first_name": "Dermatology",
"last_name": "",
"verified": false,
"gender": "Male",
"bio": null,
"exp": 20,
"photo": "https://kulcare-stg-profile-images.s3-ap-southeast-1.amazonaws.com/doctor_photos/20+years+experience.png",
"reg_nbr": "ABC123",
"reg_photo_url": null,
"verified_at": null,
"achievements": null,
"education": "DM Cardiology",
"title": "Dr. Dermatology",
"patients_per_hour": 6,
"slot_minutes": null,
"country_code": "91",
"phone_number": "2002002002",
"speciality": "Dermatologist/Cosmetologist",
"other_specialities": []
},
"spec_modules": [
{
"id": 43,
"spec_module_id": 3,
"activated_at": "2022-05-25T10:37:17.255Z",
"name": "Dermatologist"
}
],
"search_keywords_list": []
}
],
"google_account_connected": false,
"total_pages": 1,
"total_records": 8
}
}
```
## Data Structure Summary
### Queue Response Structure
The queue API responses follow this structure:
- **Root Level**: Contains `queue` and `out_of_queue` objects
- **Queue Sections**: Each contains `data` array and `meta` object
- **Appointments**: Follow JSON:API format with `id`, `type`, and `attributes`
### Key Data Points
#### Patient Categories
- Each category has an ID, name, color code, and optional rules
- Categories can have age/gender restrictions via `category_rules`
- Service discounts can be applied via `category_services`
#### Doctor Information
- Comprehensive doctor profiles with schedules and availability
- Fee structure for in-clinic and telemedicine consultations
- Specialty modules and verification status
- Schedule formatting for UI display
#### Important Notes
1. **Date Formats**: All timestamps use ISO 8601 format
2. **Placeholder Dates**: Doctor schedules use "2000-01-01" as date placeholder
3. **Timezone Awareness**: All operations respect clinic timezone settings
4. **Null Handling**: Many fields can be null - implement proper null checks
5. **Status Tracking**: Appointments flow through various status states
## Implementation Considerations
### Frontend Development
- Use the `token_number` for user-friendly appointment identification
- Display `formatted_schedules` for better UX
- Handle null values gracefully across all data fields
- Implement proper timezone conversion for appointment times
### Error Handling
- Check for empty `data` arrays in queue responses
- Validate required fields before processing appointments
- Handle network timeouts for real-time queue updates
### Performance
- Consider pagination for large doctor lists
- Cache patient categories as they change infrequently
- Implement real-time updates for queue status changes
## Frontend Implementation Details
### Data Transformation
The frontend transforms the API response to internal format:
```typescript
interface QueuePatient {
id: string
tokenNumber: string
patientId: string
patientName: string
patientAge: number
patientGender: "male" | "female" | "other"
patientPhone: string
doctorId: string
doctorName: string
appointmentTime: string
appointmentType: "consultation" | "follow-up" | "emergency"
status: "waiting" | "in-consultation" | "completed" | "cancelled" | "no-show"
checkInTime?: string
waitingTime?: number
consultationTime?: number
priority?: "normal" | "urgent" | "emergency"
visitType?: string
category?: string
}
```
### Status Mapping
API statuses are mapped to UI-friendly values:
- `confirmed` → `waiting`
- `checked_in` → `waiting`
- `with_doctor` → `in-consultation`
- `completed` → `completed`
- `cancelled` → `cancelled`
- `no_show` → `no-show`
### Queue Summary
The UI displays aggregated queue statistics:
```typescript
interface QueueSummary {
totalPatients: number
waitingPatients: number
inConsultation: number
completed: number
cancelled: number
noShow: number
averageWaitTime: number
averageConsultationTime: number
lastUpdated: string
}
```
## Real-Time Integration
The queue integrates with the Ably real-time system for live updates:
### Configuration
```typescript
// Environment variables
VITE_ABLY_KEY=your-ably-key
VITE_ABLY_ENVIRONMENT=development|production
```
### Hooks
```typescript
// Enable real-time updates in queue
const { patients, summary, isLoading } = useQueue({
date: selectedDate,
enableRealTime: true // Enables hybrid mode with reduced polling
})
// Monitor real-time connection
const { isConnected } = useRealtimeQueue({
enabled: true,
showNotifications: true,
date: selectedDate
})
```
### Events
The queue listens for these real-time events:
- `queue:patient:added` - New patient added to queue
- `queue:patient:updated` - Patient status changed
- `queue:patient:removed` - Patient removed from queue
- `queue:summary:updated` - Queue statistics updated
## Error Handling
### Common Issues
1. **"Categories do not exist"**: Treated as normal state for new clinics
2. **Empty Queue**: Shows appropriate empty state message
3. **Date Navigation**: Handles future/past dates appropriately
4. **Network Errors**: Displays retry options
### API Error Responses
```json
{
"source": "categories",
"title": "Categories do not exist"
}
```
## Performance Optimization
- **Reduced Polling**: 5-minute intervals when real-time is active
- **Stale Time**: 15 minutes with real-time, 10 minutes without
- **Cache Time**: 20 minutes for queue data
- **Optimistic Updates**: Immediate UI updates for status changes
## UI Features
### Filters
- **Doctor Filter**: View queue for specific doctor or all doctors
- **Category Filter**: Filter patients by clinic categories
- **Date Navigation**: Browse past and future dates
- **Search**: Search patients by name, token, or phone
### Actions
- **Status Updates**: Change patient status via dropdown
- **Real-time Indicator**: Shows live connection status
- **Density Control**: Adjust table row spacing
- **Auto-refresh**: Manual refresh with loading indicator
### Empty States
- Today's empty queue: "The queue is currently empty. Patients will appear here as they check in."
- Past date empty: "No patients were scheduled for this date."
- Future date empty: Shows option to return to today's queue
## Best Practices
1. **Always handle null values** from API responses
2. **Use proper date formatting** (YYYY-MM-DD) for API calls
3. **Implement proper loading states** during data fetches
4. **Show real-time connection status** to users
5. **Cache doctor and category lists** as they change infrequently
6. **Use optimistic updates** for better perceived performance
7. **Handle timezone conversions** properly for appointment times