List appointments
List all appointments that belong to the account.
Authorization
authorization In: header
Query Parameters
Page number
1 <= valueNumber of items per page
1 <= valueWhether to include sensitive fields (such as client name, email, and phone)
falseFilter by time period. upcoming is appointments that have not ended; past is appointments that have ended.
Value in
- "upcoming"
- "past"
Filter by status.
Value in
- "scheduled"
- "canceled"
Filter by appointment type.
Value in
- "virtual"
- "in_person"
Filter by provider ID(s). Accepts a single ID or comma-delimited list.
Filter by service ID(s). Accepts a single ID or comma-delimited list.
Filter by client ID(s). Accepts a single ID or comma-delimited list.
Filter by location ID(s). Accepts a single ID or comma-delimited list.
Filter for appointments starting on or after this time (ISO 8601 format).
date-timeFilter for appointments starting on or before this time (ISO 8601 format).
date-timeFilter for appointments ending on or after this time (ISO 8601 format).
date-timeFilter for appointments ending on or before this time (ISO 8601 format).
date-timeA field to order by
The order direction for the order_by field
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/appointments?order_by=%3Forder_by%5B%5D%3Dstart_at_utc&order_directions=%3Forder_directions%5B%5D%3Dasc"{ "data": [ { "add_to_calendar_url": "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/add_to_calendar", "appointment_type": "in_person", "buffer_policy": { "after_duration": "PT1H", "before_duration": "PT15M", "enabled": true }, "buffered_end_at": { "local": "2025-03-01T12:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736468400, "utc": "2025-03-01T05:00:00Z" }, "buffered_start_at": { "local": "2025-03-01T09:45:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736460300, "utc": "2025-03-01T02:45:00Z" }, "cancel_url": "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/cancel", "cancellation_events": [ { "actor": null, "cancellation_reason": { "id": "cr_a1b2c3d4e5f6", "name": "Distance too far", "object": "cancellation_reason", "sort_order": 1 }, "custom_reason_text": "I'm sick", "initiated_by": "client", "object": "cancellation_event", "occurred_at": "2023-01-01T03:00:00Z", "source": "client_ui" } ], "client": { "created_at": "2025-01-15T14:30:00Z", "email": "jane.smith@example.com", "first_name": "Jane", "id": "clnt_a1b2c3d4e5f6", "last_name": "Smith", "locale": "en-US", "metadata": { "external_id": "123" }, "object": "client", "phone": "+15551234567", "reference_id": "ext_12345", "time_zone": "America/Chicago", "updated_at": "2025-03-10T09:45:00Z" }, "client_data": { "email": "jane.smith@example.com", "fields": { "age": 30 }, "first_name": "Jane", "last_name": "Smith", "locale": "en-US", "phone": "+15551234567", "reference_id": "ext_12345", "time_zone": "America/Chicago" }, "confirm_url": "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/confirm", "confirmation_events": [ { "actor": null, "end_at": { "local": "2023-01-01T01:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736464800, "utc": "2023-01-01T04:00:00Z" }, "initiated_by": "client", "object": "confirmation_event", "occurred_at": "2023-01-01T03:00:00Z", "source": "client_ui", "start_at": { "local": "2023-01-01T00:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736461200, "utc": "2023-01-01T03:00:00Z" } } ], "confirmed_at": "2025-03-10T15:30:00Z", "created_at": "2025-03-10T14:30:00Z", "end_at": { "local": "2025-03-01T11:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736464800, "utc": "2025-03-01T04:00:00Z" }, "ics_url": "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/ics", "id": "appt_a1b2c3d4e5f6", "join_url": "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/join", "meeting": { "conferencing_provider": "zoom_admin", "error_message": null, "external_meeting_id": "82912345678", "host_url": "https://book.acme.com/p/appointments/appt_a1b2c3d4e5f6/host?token=An5thqO6Li9Dy9WXe3IsJQYDEXGjS70GjQIdNntKZgw", "id": "amtg_a1b2c3d4e5f6", "join_url": "https://zoom.us/j/82912345678", "object": "appointment_meeting", "password": "abc123", "status": "created" }, "object": "appointment", "provider": { "created_at": "2017-09-12T12:34:55Z", "display_name": "John Smith", "email": "john@example.com", "first_name": "John", "id": "prov_d025a96ac0c6", "last_name": "Smith", "metadata": { "external_id": "123" }, "object": "provider", "time_zone": "America/New_York", "updated_at": "2017-09-13T10:11:12Z" }, "providers": [ { "created_at": "2017-09-12T12:34:55Z", "display_name": "John Smith", "email": "john@example.com", "first_name": "John", "id": "prov_d025a96ac0c6", "last_name": "Smith", "metadata": { "external_id": "123" }, "object": "provider", "role": "primary", "time_zone": "America/New_York", "updated_at": "2017-09-13T10:11:12Z" } ], "reschedule_events": [ { "actor": null, "initiated_by": "client", "new_end_at": { "local": "2023-01-01T01:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736464800, "utc": "2023-01-01T04:00:00Z" }, "new_start_at": { "local": "2023-01-01T00:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736461200, "utc": "2023-01-01T03:00:00Z" }, "object": "reschedule_event", "occurred_at": "2023-01-01T03:00:00Z", "previous_end_at": { "local": "2023-01-01T01:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736464800, "utc": "2023-01-01T04:00:00Z" }, "previous_start_at": { "local": "2023-01-01T00:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736461200, "utc": "2023-01-01T03:00:00Z" }, "source": "client_ui" } ], "reschedule_url": "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/reschedule", "service": { "appointment_type": "in_person", "booking_policy": { "advance_notice": { "enabled": true, "minimum_duration": "PT1H" }, "allow_booking": true, "disabled_message": "Booking is disabled for this service.", "hold": { "duration": "PT10M", "enabled": true }, "maximize_utilization": { "enabled": true } }, "buffer_policy": { "after_duration": "PT1H", "before_duration": "PT15M", "enabled": true }, "cancellation_policy": { "advance_notice": { "enabled": true, "minimum_duration": "PT1H" }, "allow_cancellation": true, "disabled_message": "Cancellation is disabled for this service." }, "change_policy_text": "Appointments within 48 hours cannot be canceled or rescheduled online. Please call our office.", "created_at": "2025-02-17T17:49:19Z", "duration": "PT1H30M", "forms": [ { "created_at": "2025-02-17T17:49:19Z", "form_id": "frm_d025a96ac0c6", "form_name": "Intake Form", "id": "sf_d025a96ac0c6", "object": "service_form", "sort_order": 1, "updated_at": "2025-02-17T17:49:19Z" } ], "id": "srv_d025a96ac0c6", "internal_name": null, "metadata": { "external_id": "123" }, "name": "Initial Consult", "object": "service", "provider_notifications": { "additional_recipients": [ "admin@example.com" ], "notify_provider": true, "types": [ { "type": "new_appointment" } ] }, "rescheduling_policy": { "advance_notice": { "enabled": true, "minimum_duration": "PT1H" }, "allow_rescheduling": true, "disabled_message": "Rescheduling is disabled for this service." }, "slot_rules": [ { "recurrence_rule": { "byday": [ "mo", "we", "fr" ], "freq": "weekly" }, "start_times": [ "09:00", "10:00" ] } ], "updated_at": "2025-02-17T17:49:19Z" }, "start_at": { "local": "2025-03-01T10:00:00-05:00", "object": "zoned_date_time", "time_zone": "America/New_York", "unix_ts": 1736461200, "utc": "2025-03-01T03:00:00Z" }, "status": "scheduled", "updated_at": "2025-03-10T14:30:00Z", "urls": { "add_to_calendar": [ "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/add_to_calendar" ], "add_to_google_calendar": [ "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/add_to_google_calendar" ], "cancel": [ "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/cancel" ], "confirm": [ "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/confirm" ], "ics": [ "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/ics" ], "join": [ "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/join" ], "reschedule": [ "https://book.acme.com/c/appointments/appt_a1b2c3d4e5f6/reschedule" ] } } ], "meta": { "current_page": 1, "page_size": 10, "total_count": 50, "total_pages": 5 }}Get appointment GET
Get an existing appointment.
Reschedule appointment POST
Reschedule an existing appointment. The new time slot for the appointment must be available unless you explicitly disable validation (by setting `validate_slot` to `false` in the request body). You can find available time slots using the [List slots for a service](/api/list-service-slots) endpoint. The `end_at` time must be after `start_at` and within 24 hours of it. Canceled appointments cannot be rescheduled. Setting `validate_slot` to `false` can double-book the provider. Client emails, provider notifications, webhooks, and calendar sync still run.