Skip to main content

PublicBookingIntent

A public booking intent that tracks the lifecycle of a booking attempt. This is a simplified view without sensitive or admin-only fields.

appointment objectnullable

The created appointment. Present when status is completed.

anyOf
add_to_calendar_urlurirequired

Canonical URL for adding the appointment to a 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.

cancel_urlurirequired

Canonical URL for canceling the 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.

cancellation objectrequired

Information about whether the appointment can be canceled by the client.

allowedbooleanrequired

Whether the appointment can be canceled by the client.

disabled_messagestringnullablerequired

A message explaining why cancellation is disabled, if applicable. Only present when allowed is false.

confirmed_atdate-timenullablerequired

Time at which the object was confirmed.

end_at objectrequired

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

localdate-timerequired

The local date/time in ISO-8601 format, including the UTC offset (e.g., 2025-03-01T10:00:00-05:00).

Example: 2025-03-01T10:00:00-05: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
utcdate-timerequired

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

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

Canonical URL for downloading an ICS file for the 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.

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: [public_appointment]

reschedule_urlurirequired

Canonical URL for rescheduling the 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.

rescheduling objectrequired

Information about whether the appointment can be rescheduled by the client.

allowedbooleanrequired

Whether the appointment can be rescheduled by the client.

disabled_messagestringnullablerequired

A message explaining why rescheduling is disabled, if applicable. Only present when allowed is false.

start_at objectrequired

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

localdate-timerequired

The local date/time in ISO-8601 format, including the UTC offset (e.g., 2025-03-01T10:00:00-05:00).

Example: 2025-03-01T10:00:00-05: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
utcdate-timerequired

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]

urls objectrequireddeprecated

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

add_to_calendaruri[]required
add_to_google_calendaruri[]required
canceluri[]required
icsuri[]required
rescheduleuri[]required
end_at objectnullable

The end time of the selected slot

anyOf
localdate-timerequired

The local date/time in ISO-8601 format, including the UTC offset (e.g., 2025-03-01T10:00:00-05:00).

Example: 2025-03-01T10:00:00-05: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
utcdate-timerequired

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

Example: 2025-03-01T03:00:00Z
errors object[]nullable

Validation errors for data provided so far. Fields not yet submitted are not flagged. Null when not computed.

  • Array [
    • codestringnullable

    Machine-readable error code (e.g. slot_unavailable, no_available_provider, time_range_conflict)

    Example: slot_unavailable
    detailstringrequired
    Example: is not available
    source objectrequired
    pointerstringrequired
    Example: /start_at
    titlestringrequired
    Example: Invalid value
  • ]
    • hold_untildate-timenullable

    When the hold expires (UTC)

    idstringrequired

    The booking intent ID

    Possible values: Value must match regular expression ^bi_\w{24}$

    locked_fieldsstring[]

    Fields that are locked and cannot be updated via the public API.

    Possible values: [service_id, provider_id, slot, client_data, submissions]

    objectstringrequired

    The object type

    Possible values: [public_booking_intent]

    requirements object

    Per-section completeness status for a booking intent. Provides boolean signals for whether each section of the booking flow has enough data to proceed, enabling the frontend to make navigation decisions without parsing error pointers.

    booking objectrequired

    Booking step completeness status.

    completebooleanrequired

    Whether the booking step is complete (provider and slot fields are present).

    info objectrequired

    Info step completeness status.

    completebooleanrequired

    Whether the info step is complete (required client fields are present).

    submissions object[]required

    Per-form completeness status, in the same order as the service's forms.

  • Array [
    • completebooleanrequired

    Whether the submission exists and all required fields have been answered.

    form_idstringrequired

    The form's object ID.

  • ]
    • start_at objectnullable

    The start time of the selected slot

    anyOf
    localdate-timerequired

    The local date/time in ISO-8601 format, including the UTC offset (e.g., 2025-03-01T10:00:00-05:00).

    Example: 2025-03-01T10:00:00-05: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
    utcdate-timerequired

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

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

    The current status of the booking intent. Automatically transitions from pending to slot_selected when provider_id, start_at, end_at, and time_zone are all present (on create or update).

    Possible values: [pending, slot_selected, completed, abandoned]

    workflow object

    Server-computed workflow state for a booking intent. Provides step routing, completability, and defunct state so the frontend can render the correct booking flow without inferring these from raw fields.

    available_stepsstring[]required

    Ordered list of steps the user can visit. Computed from service forms and locked_fields.

    can_change_slotbooleanrequired

    Whether slot fields (start_at, end_at, time_zone) are unlocked and can be modified.

    can_completebooleanrequired

    Whether the intent has enough valid data to submit right now. When true, calling the complete endpoint will succeed regardless of whether the current status is pending or slot_selected.

    defunct_reasonstringnullable

    Why the intent is defunct. Null when not defunct.

    Possible values: [abandoned, no_available_steps, slot_expired, status_invalid]

    is_defunctbooleanrequired

    Whether the intent is in an unrecoverable state and should render a terminal UI.

    resume_stepstringrequired

    The step the UI should show on load or resume. One of: booking, info, form:<form_id>, confirmed, defunct.

    PublicBookingIntent
    {
      "appointment": null,
      "end_at": {
        "local": "2026-02-23T10:30:00-05:00",
        "object": "zoned_date_time",
        "time_zone": "America/New_York",
        "unix_ts": 1771947000,
        "utc": "2026-02-23T15:30:00Z"
      },
      "errors": null,
      "hold_until": "2026-02-22T10:10:00Z",
      "id": "bi_abc123def456abc123def456",
      "locked_fields": [],
      "object": "public_booking_intent",
      "requirements": {
        "booking": {
          "complete": true
        },
        "info": {
          "complete": false
        },
        "submissions": [
          {
            "complete": false,
            "form_id": "frm_abc123def456"
          }
        ]
      },
      "start_at": {
        "local": "2026-02-23T10:00:00-05:00",
        "object": "zoned_date_time",
        "time_zone": "America/New_York",
        "unix_ts": 1771945200,
        "utc": "2026-02-23T15:00:00Z"
      },
      "status": "slot_selected",
      "workflow": {
        "available_steps": [
          "booking",
          "info",
          "form:frm_abc123def456"
        ],
        "can_change_slot": true,
        "can_complete": false,
        "defunct_reason": null,
        "is_defunct": false,
        "resume_step": "info"
      }
    }