API ReferenceAppointments

List appointments

List all appointments that belong to the account.

GET
/v1/appointments

Authorization

authorization
AuthorizationBearer <token>

In: header

Query Parameters

page?integer

Page number

Range1 <= value
page_size?integer

Number of items per page

Range1 <= value
include_sensitive?boolean

Whether to include sensitive fields (such as client name, email, and phone)

Defaultfalse
period?string

Filter by time period. upcoming is appointments that have not ended; past is appointments that have ended.

Value in

  • "upcoming"
  • "past"
status?string

Filter by status.

Value in

  • "scheduled"
  • "canceled"
appointment_type?string

Filter by appointment type.

Value in

  • "virtual"
  • "in_person"
provider_ids?string

Filter by provider ID(s). Accepts a single ID or comma-delimited list.

service_ids?string

Filter by service ID(s). Accepts a single ID or comma-delimited list.

client_ids?string

Filter by client ID(s). Accepts a single ID or comma-delimited list.

location_ids?string

Filter by location ID(s). Accepts a single ID or comma-delimited list.

start_at_min?string

Filter for appointments starting on or after this time (ISO 8601 format).

Formatdate-time
start_at_max?string

Filter for appointments starting on or before this time (ISO 8601 format).

Formatdate-time
end_at_min?string

Filter for appointments ending on or after this time (ISO 8601 format).

Formatdate-time
end_at_max?string

Filter for appointments ending on or before this time (ISO 8601 format).

Formatdate-time
order_by?array<string>

A field to order by

order_directions?array<>

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. You can find available time slots using the [List slots for a service](/api/list-service-slots) endpoint.