Appointment | SavvyCal Appointments

An appointment represents a booking that a client has made with a provider for a service.

Example

{  "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"    ]  }}

add_to_calendar_url*string

Canonical URL for the client to add this appointment to their calendar. Resolves to the account's active custom domain when configured, otherwise the canonical app host. The host portion may change if the account changes its custom-domain configuration.

Formaturi

appointment_type*string

The type of appointment.

Value in

"in_person"
"virtual"

buffer_policy*

A policy for keeping time before and/or after appointments free of other bookings and busy external calendar events (e.g. prep time before, charting time after). The policy is captured on the appointment at booking time and continues to shield the surrounding time even if the service configuration changes later.

Example

{  "after_duration": "PT1H",  "before_duration": "PT15M",  "enabled": true}

buffered_end_at*

The end of the window shielded from other bookings, including the after-buffer captured at booking time. Equals end_at when no buffer applies.

buffered_start_at*

The start of the window shielded from other bookings, including the before-buffer captured at booking time. Equals start_at when no buffer applies.

cancel_url*string

Canonical URL for the client to cancel this appointment. Resolves to the account's active custom domain when configured, otherwise the canonical app host. The host portion may change if the account changes its custom-domain configuration.

Formaturi

cancellation_events*array<>

client*

This is an object representing a client.

Example

{  "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*

Client data provided while creating the appointment. Some fields will be null unless include_sensitive is true.

confirm_url*string

Canonical URL for the client to confirm this appointment. Resolves to the account's active custom domain when configured, otherwise the canonical app host. The host portion may change if the account changes its custom-domain configuration.

Formaturi

confirmation_events*array<>

confirmed_at*|

Time at which the object was confirmed.

Formatdate-time

created_at*string

Time at which the object was created.

Formatdate-time

end_at*

An object describing a date/time in local time and in UTC.

Example

{  "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"}

ics_url*string

Canonical URL for the client to download an iCal file for this appointment. Resolves to the account's active custom domain when configured, otherwise the canonical app host. The host portion may change if the account changes its custom-domain configuration.

Formaturi

id*string

Unique identifier for the object.

Match^appt_\w{12}$

join_url*string

Canonical URL for the client to join this appointment. Resolves to the account's active custom domain when configured, otherwise the canonical app host. The host portion may change if the account changes its custom-domain configuration.

Formaturi

meeting*

Conferencing meeting details. Null when no conferencing was configured for this appointment.

object*"appointment"

String representing the object's type.

Value in

"appointment"

provider*

A provider represents a staff member who can provide services to clients.

Example

{  "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*array<>

All providers on this appointment. The primary provider is always listed first.

reschedule_events*array<>

reschedule_url*string

Canonical URL for the client to reschedule this appointment. Resolves to the account's active custom domain when configured, otherwise the canonical app host. The host portion may change if the account changes its custom-domain configuration.

Formaturi

service*

A service represents a type of appointment.

Example

{  "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*

An object describing a date/time in local time and in UTC.

Example

{  "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*string

The status of the appointment.

Value in

"scheduled"
"canceled"

updated_at?string

Time at which the object was last updated.

Formatdate-time

urls*

Deprecated

Deprecated nested URL collections for this appointment. Use the flat *_url fields instead.