Doctor APIs

APIs for managing doctor profiles, schedules, specializations, and clinic associations.

Overview

Doctor APIs handle doctor profile management, schedule configuration, clinic associations, and professional information.

Base Path: /doctors

Authentication: Required for all endpoints

Profile Context: Doctor profile access or clinic admin permissions

Endpoints

Doctor Profile Management

Get Doctor Profile

Retrieves doctor profile information.

GET /doctors/:id

Success Response:

{
  "success": true,
  "data": {
    "id": 101,
    "user_id": 456,
    "first_name": "Dr. Sarah",
    "last_name": "Johnson",
    "name": "Dr. Sarah Johnson",
    "phone_number": "9876543210",
    "email": "sarah.johnson@email.com",
    "speciality": "Pediatrics",
    "qualification": "MBBS, MD Pediatrics",
    "registration_number": "MH12345",
    "experience_years": 8,
    "bio": "Experienced pediatrician specializing in child healthcare",
    "photo_url": "https://s3.amazonaws.com/...",
    "verified": true,
    "consultation_fee": 800,
    "followup_fee": 400,
    "consultation_duration": 20,
    "languages": ["English", "Hindi", "Marathi"],
    "awards": [
      "Best Pediatrician Award 2023",
      "Excellence in Child Care 2022"
    ],
    "education": [
      {
        "degree": "MBBS",
        "institution": "Grant Medical College",
        "year": 2016
      },
      {
        "degree": "MD Pediatrics", 
        "institution": "KEM Hospital",
        "year": 2019
      }
    ],
    "certifications": [
      {
        "name": "Pediatric Emergency Medicine",
        "issuer": "Indian Academy of Pediatrics",
        "year": 2020
      }
    ],
    "clinics": [
      {
        "clinic_id": 123,
        "clinic_name": "Children's Hospital",
        "role": "consultant",
        "consultation_fee": 800,
        "location": "Mumbai"
      }
    ],
    "stats": {
      "total_patients": 2500,
      "total_consultations": 5200,
      "rating": 4.8,
      "total_reviews": 156,
      "years_experience": 8
    },
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-20T16:30:00Z"
  }
}

Update Doctor Profile

Updates doctor profile information.

PUT /doctors/:id

Request Body:

{
  "doctor": {
    "first_name": "Dr. Sarah",
    "last_name": "Johnson",
    "email": "updated.email@domain.com",
    "speciality": "Pediatric Cardiology",
    "qualification": "MBBS, MD Pediatrics, DM Cardiology",
    "experience_years": 9,
    "bio": "Updated professional bio",
    "consultation_fee": 900,
    "followup_fee": 450,
    "consultation_duration": 25,
    "languages": ["English", "Hindi", "Marathi", "Gujarati"]
  }
}

Get Current Doctor Profile

Gets the profile of the currently authenticated doctor.

GET /doctors/me

Doctor Search & Discovery

Search Doctors

Search for doctors by various criteria.

GET /doctors/search

Query Parameters:

Parameter	Type	Description
q	string	Search query (name, speciality)
speciality	string	Filter by speciality
city	string	Filter by city
min_fee	number	Minimum consultation fee
max_fee	number	Maximum consultation fee
verified	boolean	Only verified doctors
available_today	boolean	Doctors with slots today
rating_min	number	Minimum rating (1-5)
page	integer	Page number
per_page	integer	Items per page

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 101,
      "name": "Dr. Sarah Johnson",
      "speciality": "Pediatrics",
      "qualification": "MBBS, MD",
      "experience_years": 8,
      "consultation_fee": 800,
      "photo_url": "https://...",
      "rating": 4.8,
      "total_reviews": 156,
      "verified": true,
      "next_available": "2024-01-22T10:00:00Z",
      "clinics": [
        {
          "clinic_id": 123,
          "clinic_name": "Children's Hospital",
          "city": "Mumbai"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_count": 120,
      "per_page": 25
    },
    "filters": {
      "specialities": ["Pediatrics", "Cardiology", "Dermatology"],
      "cities": ["Mumbai", "Delhi", "Bangalore"],
      "fee_range": {"min": 200, "max": 2000}
    }
  }
}

Get Doctor Specialities

Lists all available medical specialities.

GET /doctors/specialities

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "General Medicine",
      "category": "primary_care",
      "doctor_count": 450
    },
    {
      "id": 2, 
      "name": "Pediatrics",
      "category": "specialty",
      "doctor_count": 280
    },
    {
      "id": 3,
      "name": "Cardiology", 
      "category": "super_specialty",
      "doctor_count": 120
    }
  ]
}

Doctor Schedules

Get Doctor Schedule

Gets doctor's schedule for a specific date range.

GET /doctors/:id/schedule

Query Parameters:

Parameter	Type	Description
start_date	date	Start date (YYYY-MM-DD)
end_date	date	End date (YYYY-MM-DD)
clinic_id	integer	Filter by specific clinic

Success Response:

{
  "success": true,
  "data": {
    "doctor_id": 101,
    "clinic_id": 123,
    "weekly_schedule": [
      {
        "day": "monday",
        "day_number": 1,
        "active": true,
        "slots": [
          {
            "start_time": "09:00",
            "end_time": "13:00",
            "slot_duration": 20,
            "total_slots": 12,
            "available_slots": 8
          },
          {
            "start_time": "14:00", 
            "end_time": "18:00",
            "slot_duration": 20,
            "total_slots": 12,
            "available_slots": 12
          }
        ]
      },
      {
        "day": "tuesday",
        "day_number": 2, 
        "active": true,
        "slots": [
          {
            "start_time": "10:00",
            "end_time": "17:00",
            "slot_duration": 20,
            "total_slots": 21,
            "available_slots": 15
          }
        ]
      },
      {
        "day": "sunday",
        "day_number": 0,
        "active": false,
        "slots": []
      }
    ]
  }
}

Update Doctor Schedule

Updates doctor's schedule for a specific clinic.

PUT /doctors/:id/schedule

Request Body:

{
  "schedule": {
    "clinic_id": 123,
    "weekly_schedule": [
      {
        "day": "monday",
        "active": true,
        "slots": [
          {
            "start_time": "09:00",
            "end_time": "13:00",
            "slot_duration": 15
          },
          {
            "start_time": "14:00",
            "end_time": "18:00", 
            "slot_duration": 15
          }
        ]
      },
      {
        "day": "sunday",
        "active": false,
        "slots": []
      }
    ]
  }
}

Get Available Slots

Gets available appointment slots for a doctor.

GET /doctors/:id/available_slots

Query Parameters:

Parameter	Type	Required	Description
date	date	Yes	Date for availability (YYYY-MM-DD)
clinic_id	integer	No	Specific clinic

Success Response:

{
  "success": true,
  "data": {
    "date": "2024-01-22",
    "doctor_id": 101,
    "clinic_id": 123,
    "available_slots": [
      {
        "time": "09:00",
        "duration": 20,
        "type": "consultation",
        "fee": 800
      },
      {
        "time": "09:20",
        "duration": 20,
        "type": "consultation",
        "fee": 800
      },
      {
        "time": "10:40",
        "duration": 20,
        "type": "followup",
        "fee": 400
      }
    ],
    "total_slots": 24,
    "available_count": 18,
    "booked_count": 6
  }
}

Doctor-Clinic Associations

Get Doctor's Clinics

Lists all clinics where the doctor practices.

GET /doctors/:id/clinics

Success Response:

{
  "success": true,
  "data": [
    {
      "clinic_id": 123,
      "clinic_name": "Children's Hospital",
      "role": "consultant",
      "consultation_fee": 800,
      "consultation_duration": 20,
      "patients_per_hour": 3,
      "city": "Mumbai",
      "address": "123 Health Street",
      "schedule_configured": true,
      "active": true,
      "joined_at": "2024-01-10T09:00:00Z"
    },
    {
      "clinic_id": 124,
      "clinic_name": "Metro Clinic",
      "role": "visiting_consultant", 
      "consultation_fee": 1000,
      "consultation_duration": 30,
      "patients_per_hour": 2,
      "city": "Mumbai",
      "schedule_configured": false,
      "active": true,
      "joined_at": "2024-01-15T14:00:00Z"
    }
  ]
}

Join Clinic

Associates doctor with a clinic (usually via invitation).

POST /doctors/:id/clinics

Request Body:

{
  "association": {
    "clinic_id": 125,
    "role": "consultant",
    "consultation_fee": 900,
    "consultation_duration": 25,
    "invitation_code": "ABC123"
  }
}

Update Clinic Association

Updates doctor's settings for a specific clinic.

PUT /doctors/:id/clinics/:clinic_id

Request Body:

{
  "association": {
    "consultation_fee": 950,
    "consultation_duration": 30,
    "patients_per_hour": 2,
    "active": true
  }
}

Leave Clinic

Removes doctor's association with a clinic.

DELETE /doctors/:id/clinics/:clinic_id

Doctor Performance & Analytics

Get Doctor Dashboard

Gets doctor's dashboard statistics.

GET /doctors/:id/dashboard

Query Parameters:

Parameter	Type	Description
period	string	today, week, month, year
clinic_id	integer	Filter by specific clinic

Success Response:

{
  "success": true,
  "data": {
    "overview": {
      "appointments_today": 12,
      "pending_appointments": 3,
      "completed_appointments_today": 8,
      "no_shows_today": 1,
      "revenue_today": 9600,
      "revenue_this_month": 125000,
      "total_patients": 2500,
      "new_patients_this_month": 45
    },
    "schedule": {
      "next_appointment": {
        "id": 1001,
        "time": "14:30",
        "patient_name": "John Doe",
        "type": "consultation"
      },
      "remaining_slots_today": 6,
      "total_slots_today": 18
    },
    "performance": {
      "rating": 4.8,
      "total_reviews": 156,
      "patient_satisfaction": 94.5,
      "average_consultation_time": 22
    },
    "recent_reviews": [
      {
        "patient_name": "A***a D***",
        "rating": 5,
        "comment": "Excellent doctor, very caring",
        "date": "2024-01-20"
      }
    ]
  }
}

Get Patient Analytics

Gets doctor's patient-related analytics.

GET /doctors/:id/analytics/patients

Success Response:

{
  "success": true,
  "data": {
    "total_patients": 2500,
    "new_patients_trend": [
      {"month": "2024-01", "count": 45},
      {"month": "2023-12", "count": 38}
    ],
    "patient_demographics": {
      "age_groups": {
        "0-18": 890,
        "19-35": 650,
        "36-50": 580,
        "51+": 380
      },
      "gender": {
        "male": 1200,
        "female": 1250,
        "other": 50
      }
    },
    "top_conditions": [
      {"condition": "Common Cold", "count": 450},
      {"condition": "Fever", "count": 320},
      {"condition": "Allergies", "count": 280}
    ]
  }
}

Doctor Reviews & Ratings

Get Doctor Reviews

Gets reviews and ratings for a doctor.

GET /doctors/:id/reviews

Query Parameters:

Parameter	Type	Description
page	integer	Page number
per_page	integer	Reviews per page
rating	integer	Filter by rating (1-5)

Success Response:

{
  "success": true,
  "data": {
    "summary": {
      "average_rating": 4.8,
      "total_reviews": 156,
      "rating_distribution": {
        "5": 120,
        "4": 25,
        "3": 8,
        "2": 2,
        "1": 1
      }
    },
    "reviews": [
      {
        "id": 501,
        "rating": 5,
        "comment": "Excellent doctor, very patient with children",
        "patient_name": "A***a S***",
        "appointment_date": "2024-01-18",
        "created_at": "2024-01-19T10:30:00Z",
        "helpful_votes": 3
      },
      {
        "id": 502,
        "rating": 4,
        "comment": "Good consultation, helpful advice",
        "patient_name": "R***j P***",
        "appointment_date": "2024-01-17",
        "created_at": "2024-01-18T15:20:00Z",
        "helpful_votes": 1
      }
    ]
  },
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 8,
      "total_count": 156,
      "per_page": 20
    }
  }
}

Doctor Availability Management

Set Unavailability

Marks doctor as unavailable for specific dates/times.

POST /doctors/:id/unavailability

Request Body:

{
  "unavailability": {
    "start_date": "2024-01-25",
    "end_date": "2024-01-27",
    "start_time": "10:00",
    "end_time": "16:00", 
    "all_day": false,
    "reason": "Medical conference",
    "clinic_id": 123
  }
}

List Unavailabilities

Gets doctor's unavailable periods.

GET /doctors/:id/unavailability

Query Parameters:

Parameter	Type	Description
start_date	date	Filter from date
end_date	date	Filter to date
clinic_id	integer	Filter by clinic

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 301,
      "start_date": "2024-01-25",
      "end_date": "2024-01-27", 
      "start_time": "10:00",
      "end_time": "16:00",
      "all_day": false,
      "reason": "Medical conference",
      "clinic_id": 123,
      "created_at": "2024-01-20T09:00:00Z"
    }
  ]
}

Remove Unavailability

Removes an unavailability period.

DELETE /doctors/:id/unavailability/:unavailability_id

Doctor Education & Certifications

Add Education

Adds education qualification to doctor profile.

POST /doctors/:id/education

Request Body:

{
  "education": {
    "degree": "MD Internal Medicine",
    "institution": "AIIMS Delhi",
    "year_completed": 2020,
    "grade": "Distinction"
  }
}

Add Certification

Adds professional certification to doctor profile.

POST /doctors/:id/certifications

Request Body:

{
  "certification": {
    "name": "Fellow of American College of Cardiology",
    "issuing_organization": "American College of Cardiology",
    "issue_date": "2021-06-15",
    "expiry_date": "2026-06-15",
    "credential_id": "FACC2021001"
  }
}

Error Responses

Common Error Codes

Code	Status	Description
DOCTOR_NOT_FOUND	404	Doctor profile not found
UNAUTHORIZED_DOCTOR_ACCESS	403	User doesn't have access to doctor profile
INVALID_SCHEDULE	422	Invalid schedule configuration
CLINIC_ASSOCIATION_EXISTS	422	Already associated with clinic
UNAVAILABILITY_CONFLICT	422	Conflicts with existing appointments
QUALIFICATION_VERIFICATION_REQUIRED	422	Need to verify qualifications

Example Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_SCHEDULE",
    "message": "Schedule validation failed",
    "details": {
      "start_time": ["cannot be after end_time"],
      "slot_duration": ["must be between 5 and 60 minutes"]
    }
  }
}

Webhooks

Doctor-related webhooks:

doctor.created - New doctor profile created
doctor.verified - Doctor verification completed
doctor.schedule_updated - Schedule modified
doctor.joined_clinic - Associated with new clinic
doctor.review_added - New review received

Examples

Complete Doctor Setup

# 1. Update doctor profile
curl -X PUT https://api.kulcare.com/doctors/101 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "doctor": {
      "speciality": "Pediatrics",
      "consultation_fee": 800,
      "bio": "Experienced pediatrician"
    }
  }'

# 2. Set schedule
curl -X PUT https://api.kulcare.com/doctors/101/schedule \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "clinic_id": 123,
      "weekly_schedule": [
        {
          "day": "monday",
          "active": true,
          "slots": [
            {"start_time": "09:00", "end_time": "17:00", "slot_duration": 20}
          ]
        }
      ]
    }
  }'

# 3. Check available slots
curl -X GET "https://api.kulcare.com/doctors/101/available_slots?date=2024-01-22&clinic_id=123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Rate Limits

Profile updates: 20 per hour
Schedule updates: 10 per hour
Search requests: 100 per hour
Dashboard/analytics: 50 per hour

Next Steps

Patient APIs - Patient management
Appointment APIs - Booking and scheduling
Medical Records APIs - Prescriptions and records

Doctor APIs

OverviewCopy Anchor Link

EndpointsCopy Anchor Link

Doctor Profile ManagementCopy Anchor Link

Get Doctor ProfileCopy Anchor Link

Update Doctor ProfileCopy Anchor Link

Get Current Doctor ProfileCopy Anchor Link

Doctor Search & DiscoveryCopy Anchor Link

Search DoctorsCopy Anchor Link

Get Doctor SpecialitiesCopy Anchor Link

Doctor SchedulesCopy Anchor Link

Get Doctor ScheduleCopy Anchor Link

Update Doctor ScheduleCopy Anchor Link

Get Available SlotsCopy Anchor Link

Doctor-Clinic AssociationsCopy Anchor Link

Get Doctor's ClinicsCopy Anchor Link

Join ClinicCopy Anchor Link

Update Clinic AssociationCopy Anchor Link

Leave ClinicCopy Anchor Link

Doctor Performance & AnalyticsCopy Anchor Link

Get Doctor DashboardCopy Anchor Link

Get Patient AnalyticsCopy Anchor Link

Doctor Reviews & RatingsCopy Anchor Link

Get Doctor ReviewsCopy Anchor Link

Doctor Availability ManagementCopy Anchor Link

Set UnavailabilityCopy Anchor Link

List UnavailabilitiesCopy Anchor Link

Remove UnavailabilityCopy Anchor Link

Doctor Education & CertificationsCopy Anchor Link

Add EducationCopy Anchor Link

Add CertificationCopy Anchor Link

Error ResponsesCopy Anchor Link

Common Error CodesCopy Anchor Link

Example Error ResponseCopy Anchor Link

WebhooksCopy Anchor Link

ExamplesCopy Anchor Link

Complete Doctor SetupCopy Anchor Link

Rate LimitsCopy Anchor Link

Next StepsCopy Anchor Link

On this page

Overview

Endpoints

Doctor Profile Management

Get Doctor Profile

Update Doctor Profile

Get Current Doctor Profile

Doctor Search & Discovery

Search Doctors

Get Doctor Specialities

Doctor Schedules

Get Doctor Schedule

Update Doctor Schedule

Get Available Slots

Doctor-Clinic Associations

Get Doctor's Clinics

Join Clinic

Update Clinic Association

Leave Clinic

Doctor Performance & Analytics

Get Doctor Dashboard

Get Patient Analytics

Doctor Reviews & Ratings

Get Doctor Reviews

Doctor Availability Management

Set Unavailability

List Unavailabilities

Remove Unavailability

Doctor Education & Certifications

Add Education

Add Certification

Error Responses

Common Error Codes

Example Error Response

Webhooks

Examples

Complete Doctor Setup

Rate Limits

Next Steps