Skip to main content
The Appointment Controller handles scheduling and management of patient appointments with doctors. Access is restricted to authenticated users with admin, doctor, or receptionist roles.

​
Authentication

All endpoints require:
  • Middleware: auth, verified
  • Role: admin, doctor, or receptionist

​
Endpoints

​
List Appointments

GET /appointments
Returns a paginated list of appointments with patient and doctor information.

​
Query Parameters

​
doctor_id
integer
Filter appointments by doctor ID. Note: Doctors automatically see only their own appointments regardless of this parameter.
​
date
date
Filter appointments by date (format: YYYY-MM-DD)
​
page
integer
default:"1"
Page number for pagination

​
Response

Returns an Inertia render with:
​
appointments
object
Paginated collection of appointments
​
data
array
Array of appointment objects
​
id
integer
Appointment ID
​
patient_id
integer
Patient ID
​
patient
object
Patient information
​
doctor_id
integer
Doctor (User) ID
​
doctor
object
Doctor information
​
start_time
datetime
Appointment start time
​
end_time
datetime
Appointment end time
​
status
string
Appointment status: scheduled, confirmed, completed, cancelled, or no_show
​
reason
string
Reason for appointment
​
notes
string
Additional notes
​
current_page
integer
Current page number
​
per_page
integer
Items per page (20)
​
doctors
array
List of doctors for filtering (id and name)
​
filters
object
Active filters (doctor_id, date)

​
Role-Based Filtering

  • Doctors: Automatically filtered to show only their own appointments
  • Admin/Receptionist: Can view all appointments or filter by doctor

​
Create Appointment Form

GET /appointments/create
Displays the form for creating a new appointment.

​
Query Parameters

​
patient_id
integer
Pre-select a patient for the appointment

​
Response

Returns an Inertia render with:
​
patients
array
List of all patients (id and full_name) sorted alphabetically
​
doctors
array
List of doctors (id and name)
​
selected_patient_id
integer
Pre-selected patient ID from query parameter

​
Store Appointment

POST /appointments
Creates a new appointment.

​
Request Body

​
patient_id
integer
required
Patient ID (must exist in patients table)
​
doctor_id
integer
required
Doctor ID (must exist in users table)
​
start_time
datetime
required
Appointment start time (format: YYYY-MM-DD HH:MM:SS)
​
end_time
datetime
required
Appointment end time (must be after start_time)
​
reason
string
Reason for appointment (max 255 characters)
​
notes
string
Additional notes

​
Validation

  • patient_id: Must exist in patients table
  • doctor_id: Must exist in users table
  • start_time: Must be a valid date
  • end_time: Must be a valid date and after start_time

​
Response

Redirects back with success message: “Cita agendada correctamente.”

​
Update Appointment

PUT /appointments/{appointment}
Updates an existing appointment. Commonly used for status changes and rescheduling.

​
Path Parameters

​
appointment
integer
required
Appointment ID

​
Request Body

All fields are optional:
​
status
string
Appointment status. Must be one of: scheduled, confirmed, completed, cancelled, no_show
​
start_time
datetime
New start time
​
end_time
datetime
New end time (must be after start_time if provided)
​
notes
string
Updated notes

​
Status Values

  • scheduled: Initial state when appointment is created
  • confirmed: Appointment confirmed by patient or staff
  • completed: Appointment has been completed
  • cancelled: Appointment cancelled
  • no_show: Patient did not show up for appointment

​
Response

Redirects back with success message: “Cita actualizada.”

​
Delete Appointment

DELETE /appointments/{appointment}
Soft deletes an appointment.

​
Path Parameters

​
appointment
integer
required
Appointment ID

​
Response

Redirects back with success message: “Cita eliminada.”

​
Implementation Details

  • Source: app/Http/Controllers/AppointmentController.php
  • Route: /appointments
  • Uses action classes: CreateAppointmentAction, UpdateAppointmentAction
  • Pagination: 20 records per page
  • Appointments sorted by start_time (latest first)
  • Soft deletes enabled
  • Relationships: Eager loads patient and doctor for performance

​
Date/Time Handling

  • All datetime fields are automatically cast to Carbon instances
  • Dates should be provided in ISO 8601 format: YYYY-MM-DD HH:MM:SS
  • Filtering by date uses whereDate() for date-only comparison

​
Role-Specific Behavior

​
Doctor Role

  • Automatically sees only their own appointments in the index
  • Cannot filter by other doctors

​
Admin/Receptionist Roles

  • Can view all appointments
  • Can filter by any doctor
  • Full CRUD access to all appointments

Build docs developers (and LLMs) love

Get started for freeTalk to us