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
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_atstring<date-time>nullablerequired

Time at which the object was confirmed.

end_at objectrequired

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

localstring<date-time>required

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
utcstring<date-time>required

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

Example: 2025-03-01T03:00:00Z
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]

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.

localstring<date-time>required

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
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]

urls objectrequired

URLs related to the appointment for client-facing actions.

add_to_calendarstring<uri>[]required

URLs for adding the appointment to a calendar.

add_to_google_calendarstring<uri>[]required

URLs for adding the appointment to Google Calendar.

cancelstring<uri>[]required

URLs for canceling the appointment.

icsstring<uri>[]required

URLs for downloading an ICS file for the appointment.

reschedulestring<uri>[]required

URLs for rescheduling the appointment.

end_at objectnullable

The end time of the selected slot

anyOf
localstring<date-time>required

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
utcstring<date-time>required

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_untilstring<date-time>nullable

    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
    localstring<date-time>required

    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
    utcstring<date-time>required

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