Admin Appointments API

Administrative endpoints for managing appointments across the entire system.

List All Appointments

Get a comprehensive list of all appointments in the system.

Endpoint: GET /v1/admin/clinic/appointments
Authentication: Required (Admin role)

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of items per page
`sort_by`	string	No	Field to sort by
`sort_dir`	string	No	Sort direction (“ASC” or “DESC”)
`search`	string	No	Search term
`provider_id`	integer	No	Filter by provider ID
`patient_id`	integer	No	Filter by patient ID
`status`	string	No	Filter by appointment status

Example Request


GET /v1/admin/clinic/appointments?page=1&page_size=100&status=scheduled HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Filter Appointments

Filter appointments with advanced administrative criteria.

Endpoint: POST /v1/admin/clinic/appointments/filter_appointments
Authentication: Required (Admin role)

Request Body Parameters

Parameter	Type	Required	Description
`search`	string	No	Search term
`sort_by`	string	No	Field to sort by
`sort_dir`	string	No	Sort direction
`filters`	object	No	Filter criteria with available parameters: `date` (object with start_date/end_date), `status` (string), `appointment_type` (string), `patient_name` (string), `provider_name` (string)
`page_size`	integer	No	Number of items per page

Example Request


POST /v1/admin/clinic/appointments/filter_appointments HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "search": "therapy",
  "filters": {
    "date_range": {
      "start": "2023-10-01",
      "end": "2023-10-31"
    },
    "status": "completed",
    "provider_id": 456
  },
  "page_size": 50
}

Get Appointment Details

Endpoint: GET /v1/admin/clinic/appointments/{id}
Authentication: Required (Admin role)

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Appointment ID

Example Request


GET /v1/admin/clinic/appointments/789 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Update Appointment

Endpoint: PUT /v1/admin/clinic/appointments/{id}
Authentication: Required (Admin role)

Request Body Parameters

Parameter	Type	Required	Description
`appointment`	object	Yes	Appointment data object
`appointment.scheduled_at`	string	No	Scheduled date/time (ISO 8601)
`appointment.provider_id`	integer	No	Provider ID
`appointment.patient_id`	integer	No	Patient ID
`appointment.status`	string	No	Appointment status
`appointment.notes`	string	No	Appointment notes
`appointment.duration_minutes`	integer	No	Duration in minutes

Delete Appointment

Endpoint: DELETE /v1/admin/clinic/appointments/{id}
Authentication: Required (Admin role)

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Appointment ID

Get No-Show Appointments

Get appointments marked as no-shows.

Endpoint: GET /v1/admin/clinic/appointments/no_shows
Authentication: Required (Admin role)

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of items per page
`date_range`	string	No	Date range filter

Refresh Twilio Tokens

Refresh Twilio access tokens for video appointments.

Endpoint: POST /v1/admin/clinic/appointments/{id}/refresh_twilio_tokens
Authentication: Required (Admin role)

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Appointment ID

Appointment Filters

Get available filter options for admin appointment searches.

Endpoint: GET /v1/admin/clinic/appointments/filters
Authentication: Required (Admin role)

Response Format

Appointment Response


{
  "id": 789,
  "patient_id": 1049,
  "provider_id": 456,
  "scheduled_at": "2023-10-27T14:30:00.000Z",
  "status": "scheduled",
  "appointment_type": "therapy",
  "duration_minutes": 60,
  "notes": "Initial consultation",
  "no_show": false,
  "twilio_room_sid": "RM1234567890abcdef",
  "created_at": "2023-10-20T10:00:00.000Z",
  "updated_at": "2023-10-20T15:30:00.000Z",
  "patient": {
    "id": 1049,
    "first_name": "John",
    "last_name": "Doe"
  },
  "provider": {
    "id": 456,
    "first_name": "Dr. Jane",
    "last_name": "Smith"
  }
}

Appointment Status Values

scheduled - Appointment is scheduled
confirmed - Appointment has been confirmed
in_progress - Appointment is currently happening
completed - Appointment has been completed
cancelled - Appointment was cancelled
no_show - Patient did not show up
rescheduled - Appointment was rescheduled

Appointment Types

therapy - Therapy session
consultation - Initial consultation
follow_up - Follow-up appointment
assessment - Assessment session
group_therapy - Group therapy session
medication_review - Medication review

Error Responses

403 Forbidden


{
  "errors": "Admin access required"
}

422 Unprocessable Entity


{
  "errors": {
    "scheduled_at": ["can't be blank", "must be in the future"],
    "provider_id": ["must exist"],
    "patient_id": ["must exist"]
  }
}

404 Not Found


{
  "errors": "Appointment not found"
}

Notes

All admin appointment endpoints require administrative privileges
Appointments can be filtered by multiple criteria for comprehensive reporting
No-show tracking helps with patient engagement metrics
Twilio tokens are used for video appointment functionality
Status changes are automatically tracked for audit purposes
Bulk operations may be available for administrative efficiency