Skip to main content

Appointment

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

appointment_typestringrequired

The type of appointment.

Possible values: [in_person, virtual]

cancellation_events object[]required
  • Array [
    • actorstringnullablerequired

    The actor that initiated the cancellation (user ID or bearer token ID).

    cancellation_reason objectnullablerequired

    This is an object representing a cancellation reason.

    idstringrequired

    Unique identifier for the object.

    Possible values: Value must match regular expression ^cr_\w{12}$

    namestringrequired

    The name of the cancellation reason.

    objectstringrequired

    String representing the object's type.

    Possible values: [cancellation_reason]

    sort_orderintegerrequired

    The sort order of the cancellation reason.

    custom_reason_textstringnullablerequired

    Custom reason text for the cancellation.

    initiated_bystringrequired

    The entity that initiated the cancellation.

    Possible values: [user, client]

    objectstringrequired

    Possible values: [cancellation_event]

    occurred_atstring<datetime>required

    The time at which the cancellation occurred (ISO-8601 format).

    sourcestringrequired

    The source of the cancellation event.

    Possible values: [client_ui, dashboard, api]

  • ]
    • client objectrequired

    This is an object representing a client.

    created_atstring<date-time>required

    Time at which the object was created.

    emailstring<email>nullable

    The client's email address. This field is only included if include_sensitive is true.

    first_namestringnullable

    The client's first name. This field is only included if include_sensitive is true.

    idstringrequired

    Unique identifier for the object.

    Possible values: Value must match regular expression ^clnt_\w{12}$

    last_namestringnullable

    The client's last name. This field is only included if include_sensitive is true.

    localestringrequired

    The locale of the client.

    Example: en-US
    objectstringrequired

    String representing the object's type.

    Possible values: [client]

    phonestringnullable

    The client's phone number (E.164 format). This field is only included if include_sensitive is true.

    reference_idstringnullablerequired

    External reference identifier for the client.

    time_zonestringrequired

    The client's time zone (IANA format).

    Example: America/Chicago
    updated_atstring<date-time>required

    Time at which the object was last updated.

    client_data objectrequired

    Client data provided while creating the appointment. Some fields are only included if include_sensitive is true.

    emailstring<email>nullable

    The client's email address. This field is only included if include_sensitive is true.

    first_namestringnullable

    The client's first name. This field is only included if include_sensitive is true.

    last_namestringnullable

    The client's last name. This field is only included if include_sensitive is true.

    localestringnullablerequired

    The locale of the client booking the appointment.

    Example: en-US
    phonestringnullable

    The client's phone number (E.164 format). This field is only included if include_sensitive is true.

    reference_idstringnullablerequired

    The client's external reference identifier.

    time_zonestringrequired

    The client's time zone (IANA format).

    Example: America/Chicago
    client_localestringnullabledeprecated

    Use client_data.locale instead.

    Example: en-US
    client_reference_idstringnullabledeprecated

    Use client_data.reference_id instead.

    client_time_zonestringdeprecated

    Use client_data.time_zone instead.

    Example: America/Chicago
    confirmation_events object[]required
  • Array [
    • actorstringnullablerequired

    The actor that initiated the confirmation (user ID or bearer token ID).

    end_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
    initiated_bystringrequired

    The entity that initiated the confirmation.

    Possible values: [user, client]

    objectstringrequired

    Possible values: [confirmation_event]

    occurred_atstring<datetime>required

    The time at which the confirmation occurred (ISO-8601 format).

    sourcestringrequired

    The source of the confirmation event.

    Possible values: [client_ui, dashboard, api]

    start_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
  • ]
    • confirmed_atstring<date-time>nullablerequired

    Time at which the object was confirmed.

    created_atstring<date-time>required

    Time at which the object was created.

    end_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
    fields objectrequireddeprecated

    Use client_data instead.

    emailstring<email>nullable

    The client's email address. This field is only included if include_sensitive is true.

    first_namestringnullable

    The client's first name. This field is only included if include_sensitive is true.

    last_namestringnullable

    The client's last name. This field is only included if include_sensitive is true.

    phonestringnullable

    The client's phone number (E.164 format). This field is only included if include_sensitive is true.

    idstringrequired

    Unique identifier for the object.

    Possible values: Value must match regular expression ^appt_\w{12}$

    objectstringrequired

    String representing the object's type.

    Possible values: [appointment]

    provider objectrequired

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

    created_atstring<date-time>required

    Time at which the object was created.

    display_namestringrequired

    The provider's display name.

    first_namestringrequired

    The provider's first name.

    idstringrequired

    Unique identifier for the object.

    Possible values: Value must match regular expression ^prov_\w{12}$

    last_namestringrequired

    The provider's last name.

    metadataobject

    Set of key-value pairs attached to this provider. Maximum size is 16 KB.

    objectstringrequired

    String representing the object's type.

    Possible values: [provider]

    updated_atstring<date-time>required

    Time at which the object was last updated.

    reschedule_events object[]required
  • Array [
    • actorstringnullablerequired
    initiated_bystringrequired

    Possible values: [user, client]

    new_end_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
    new_start_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
    objectstringrequired

    Possible values: [reschedule_event]

    occurred_atstring<datetime>required

    The time at which the reschedule occurred (ISO-8601 format).

    previous_end_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
    previous_start_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
    sourcestringrequired

    Possible values: [client_ui, dashboard, api]

  • ]
    • service objectrequired

    A service represents a service offering that clients can book with a provider.

    appointment_typestringrequired

    The type of appointment.

    Possible values: [in_person, virtual]

    booking_policy objectrequired

    A booking policy defines the rules for booking a service from public booking interfaces.

    advance_notice objectrequired

    A policy for requiring minimum advance notice.

    enabledbooleanrequired

    Whether advance notice is enabled.

    minimum_durationstringnullablerequired

    The minimum duration of advance notice.

    Possible values: Value must match regular expression ^PT(?:(\d+)H)?(?:(\d+)M)?$

    allow_bookingbooleanrequired

    Whether public booking is allowed for the service.

    disabled_messagestringnullablerequired

    The message to display when public booking is disabled.

    maximize_utilization objectrequired

    Avoid presenting overlapping time slots for service providers to eliminate gaps in the schedule.

    enabledbooleanrequired

    Whether maximize utilization is enabled for the service.

    cancellation_policy objectrequired

    A cancellation policy defines the rules for canceling a service from public booking interfaces.

    advance_notice objectrequired

    A policy for requiring minimum advance notice.

    enabledbooleanrequired

    Whether advance notice is enabled.

    minimum_durationstringnullablerequired

    The minimum duration of advance notice.

    Possible values: Value must match regular expression ^PT(?:(\d+)H)?(?:(\d+)M)?$

    allow_cancellationbooleanrequired

    Whether public cancellation is allowed for the service.

    disabled_messagestringnullablerequired

    The message to display when public cancellation is disabled.

    change_policy_textstringrequired

    Displayed to clients in follow-up communication. Use this to explain any important rules about cancellations or rescheduling.

    Example: Appointments within 48 hours cannot be canceled or rescheduled online. Please call our office.
    created_atstring<datetime>required

    When the service was created.

    durationstringrequired

    The duration of time slots in ISO-8601 duration format.

    Possible values: Value must match regular expression ^PT(?:(\d+)H)?(?:(\d+)M)?$

    Example: `PT30M`
    idstringrequired

    Unique identifier for the object.

    Possible values: Value must match regular expression ^srv_\w{12}$

    namestringrequired

    The name of the service.

    objectstringrequired

    String representing the object's type.

    Possible values: [service]

    rescheduling_policy objectrequired

    A rescheduling policy defines the rules for rescheduling a service from public booking interfaces.

    advance_notice objectrequired

    A policy for requiring minimum advance notice.

    enabledbooleanrequired

    Whether advance notice is enabled.

    minimum_durationstringnullablerequired

    The minimum duration of advance notice.

    Possible values: Value must match regular expression ^PT(?:(\d+)H)?(?:(\d+)M)?$

    allow_reschedulingbooleanrequired

    Whether public rescheduling is allowed for the service.

    disabled_messagestringnullablerequired

    The message to display when public rescheduling is disabled.

    slot_rules object[]required

    Array of slot rules for the service.

  • Array [
    • recurrence_rule objectrequired

    A recurrence rule describes a repeating pattern of times. Recurrences rules in SavvyCal are modeled after the conventions of iCalendar recurrence rules (RRULE), but are a subset of the full specification.

    bydaystring[]

    The days of the week on which the recurrence occurs.

    Possible values: Value must match regular expression (mo|tu|we|th|fr|sa|su)$

    Example: ["mo","we","fr"]
    countintegernullable

    Number of occurrences at which to end the recurrence.

    Possible values: >= 1

    freqstringrequired

    The frequency of the recurrence.

    Possible values: [daily, weekly]

    intervalinteger

    How often the recurrence rule repeats.

    Possible values: >= 1

    Example: 2
    untildatenullable

    Date at which to end the recurrence (in ISO-8601 format).

    Example: 2024-01-02
    start_timesstring[]required

    Array of start times for slots.

    Possible values: Value must match regular expression ^\d{2}:\d{2}$

  • ]
    • updated_atstring<datetime>required

    When the service was last updated.

    start_at objectrequired

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

    localstringrequired

    The local date/time in ISO-8601 format (without time zone information).

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

    Example: 2025-03-01T10:00:00
    objectstringrequired

    String representing the object's type.

    Possible values: [zoned_date_time]

    time_zonestringrequired

    The time zone of the local time (IANA format).

    Example: America/New_York
    unix_tsintegerrequired

    The UTC date/time in Unix timestamp format (seconds).

    Example: 1736461200
    utcstring<date-time>required

    The UTC date/time in ISO-8601 format (with time zone information).

    Example: 2025-03-01T03:00:00Z
    statusstringrequired

    The status of the appointment.

    Possible values: [scheduled, canceled]

    updated_atstring<date-time>

    Time at which the object was last updated.

    urls object

    URLs for this appointment.

    add_to_calendarstring<uri>[]

    URLs for the client to use to add this appointment to their calendar.

    add_to_google_calendarstring<uri>[]required

    URLs for the client to use to add this appointment to Google Calendar.

    cancelstring<uri>[]required

    URLs for the client to use to cancel this appointment.

    confirmstring<uri>[]required

    URLs for the client to use to confirm this appointment.

    icsstring<uri>[]required

    URLs for the client to use to download an iCal file for this appointment.

    reschedulestring<uri>[]required

    URLs for the client to use to reschedule this appointment.

    Appointment
    {
      "appointment_type": "in_person",
      "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",
        "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",
        "first_name": "Jane",
        "last_name": "Smith",
        "locale": "en-US",
        "phone": "+15551234567",
        "reference_id": "ext_12345",
        "time_zone": "America/Chicago"
      },
      "client_locale": "en-US",
      "client_reference_id": "ext_12345",
      "client_time_zone": "America/Chicago",
      "confirmation_events": [
        {
          "actor": null,
          "end_at": {
            "local": "2023-01-01T01:00: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",
            "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",
        "object": "zoned_date_time",
        "time_zone": "America/New_York",
        "unix_ts": 1736464800,
        "utc": "2025-03-01T04:00:00Z"
      },
      "fields": {
        "email": "jane.smith@example.com",
        "first_name": "Jane",
        "last_name": "Smith",
        "phone": "+15551234567"
      },
      "id": "appt_a1b2c3d4e5f6",
      "object": "appointment",
      "provider": {
        "created_at": "2017-09-12T12:34:55Z",
        "display_name": "John Smith",
        "first_name": "John",
        "id": "prov_d025a96ac0c6",
        "last_name": "Smith",
        "metadata": {
          "external_id": "123"
        },
        "object": "provider",
        "updated_at": "2017-09-13T10:11:12Z"
      },
      "reschedule_events": [
        {
          "actor": null,
          "initiated_by": "client",
          "new_end_at": {
            "local": "2023-01-01T01:00: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",
            "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",
            "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",
            "object": "zoned_date_time",
            "time_zone": "America/New_York",
            "unix_ts": 1736461200,
            "utc": "2023-01-01T03:00:00Z"
          },
          "source": "client_ui"
        }
      ],
      "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.",
          "maximize_utilization": {
            "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",
        "id": "srv_d025a96ac0c6",
        "name": "Initial Consult",
        "object": "service",
        "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",
        "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_google_calendar": [
          "https://savvycal.app/c/appointments/appt_a1b2c3d4e5f6/add_to_google_calendar"
        ],
        "cancel": [
          "https://savvycal.app/c/appointments/appt_a1b2c3d4e5f6/cancel"
        ],
        "confirm": [
          "https://savvycal.app/c/appointments/appt_a1b2c3d4e5f6/confirm"
        ],
        "ics": [
          "https://savvycal.app/c/appointments/appt_a1b2c3d4e5f6/ics"
        ],
        "reschedule": [
          "https://savvycal.app/c/appointments/appt_a1b2c3d4e5f6/reschedule"
        ]
      }
    }