API reference

Public booking

13 operations.

GET /v1/public/accounts/{handle}/event-types/{event_type_id}/slots

Free times a visitor can book for one event type.

Operation id
listFreeSlots
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
event_type_id path string yes Limits: at least 1 character.
from query string yes Limits: format date-time.
to query string yes Limits: format date-time.
host_id query string no Limits: at least 1 character.
link_id query string no Limits: at least 1 character.
x-route-handle header string no Limits: at least 1 character.
x-prefill-token header string no Limits: 1 to 64 characters.

Answers

200 The free times, and the range that was searched after clipping. application/json

Field Type Always sent Notes
host_id string no
slots array of object yes
slots[] object yes
slots[].start string yes Limits: format date-time.
slots[].end string yes Limits: format date-time.
from string yes Limits: format date-time.
to string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
429 Too many attempts. rate_limited
503 A calendar could not be reached. provider_unavailable

POST /v1/public/accounts/{handle}/event-types/{event_type_id}/slots

Free times for a booking being moved. The reschedule token is in the body.

Operation id
listRescheduleSlots
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
event_type_id path string yes Limits: at least 1 character.

Request body application/json, required

Field Type Required Notes
reschedule_token string yes Limits: 1 to 1024 characters.
from string yes Limits: format date-time.
to string yes Limits: format date-time.
host_id string no Limits: at least 1 character.

Answers

200 The free times, and the range that was searched after clipping. application/json

Field Type Always sent Notes
host_id string no
slots array of object yes
slots[] object yes
slots[].start string yes Limits: format date-time.
slots[].end string yes Limits: format date-time.
from string yes Limits: format date-time.
to string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited
503 A calendar could not be reached. provider_unavailable

POST /v1/public/accounts/{handle}/bookings

Book a time.

Operation id
createBooking
Who can call it
Anyone. No sign-in.
Credentials
None needed.
Retry key
Required: send an Idempotency-Key header.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
Idempotency-Key header string yes Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
event_type_id string yes Limits: at least 1 character.
host_id string no Limits: at least 1 character.
start string yes Limits: format date-time.
invitee object yes
invitee.name string yes
invitee.email string yes
invitee.phone string no
invitee.time_zone string yes
invitee.locale string no
location_id string no Limits: at least 1 character.
location_value string no
answers array of object no
answers[] object yes
answers[].question_id string yes Limits: at least 1 character.
answers[].value string or array of string yes
guests array of object no People the visitor invites besides themselves. They are invited on the calendar event and sent the booking's emails, without its cancel and reschedule links. At most the event type's max_guests; refused when it is 0. Limits: at most 10 items.
guests[] object yes
guests[].email string yes
guests[].name string no
link_id string no Limits: at least 1 character.
route string no Limits: at least 1 character.
prefill string no Limits: 1 to 64 characters.
surface string no Values: booking_page , embed .
attribution map of text to string no
human_check string yes

Answers

201 The booking is confirmed. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
version integer yes Limits: at least 1.
status string yes Values: pending , confirmed , canceled , expired .
start string yes Limits: format date-time.
end string yes Limits: format date-time.
event_type object yes
event_type.id string yes
event_type.name string yes
host object no
host.id string yes
host.display_name string yes
hosts array of object no
hosts[] object yes
hosts[].id string yes
hosts[].display_name string yes
location object yes
location.kind string yes
location.value string no
invitee_time_zone string yes
manage object yes
manage.cancel_token string yes
manage.reschedule_token string yes
redirect_url string no Where the booking page sends the visitor next: the event type's after-booking address with booking_id added and nothing else. Present only on the create and read answers of a confirmed booking whose address's host is still in the account's redirect_allowed_hosts.

202 The booking is still being confirmed. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
version integer yes Limits: at least 1.
status string yes Values: pending , confirmed , canceled , expired .
start string yes Limits: format date-time.
end string yes Limits: format date-time.
event_type object yes
event_type.id string yes
event_type.name string yes
host object no
host.id string yes
host.display_name string yes
hosts array of object no
hosts[] object yes
hosts[].id string yes
hosts[].display_name string yes
location object yes
location.kind string yes
location.value string no
invitee_time_zone string yes
manage object yes
manage.cancel_token string yes
manage.reschedule_token string yes
redirect_url string no Where the booking page sends the visitor next: the event type's after-booking address with booking_id added and nothing else. Present only on the create and read answers of a confirmed booking whose address's host is still in the account's redirect_allowed_hosts.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
402 The account needs an eligible plan or a Free host selection. plan_required
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. The same identifier was already used for a different request. This request is already running. Someone else got that time. conflict , id_conflict , request_in_progress , slot_taken
415 Send the body as JSON. unsupported_media_type
422 The time is not offered. invalid_slot
429 Too many attempts. rate_limited
503 A system this account relies on did not answer. Try again in a moment. A calendar could not be reached. lookup_unavailable , provider_unavailable

GET /v1/public/accounts/{handle}/bookings/{booking_id}

Read a booking with its manage token.

Operation id
getPublicBooking
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
booking_id path string yes Limits: at least 1 character.
token query string yes Limits: at least 1 character.

Answers

200 The booking. application/json

Field Type Always sent Notes
id string yes
version integer yes Limits: at least 1.
status string yes Values: pending , confirmed , canceled , expired .
start string yes Limits: format date-time.
end string yes Limits: format date-time.
event_type object yes
event_type.id string yes
event_type.name string yes
host object no
host.id string yes
host.display_name string yes
hosts array of object no
hosts[] object yes
hosts[].id string yes
hosts[].display_name string yes
location object yes
location.kind string yes
location.value string no
invitee_time_zone string yes
manage object yes
manage.cancel_token string yes
manage.reschedule_token string yes
redirect_url string no Where the booking page sends the visitor next: the event type's after-booking address with booking_id added and nothing else. Present only on the create and read answers of a confirmed booking whose address's host is still in the account's redirect_allowed_hosts.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
429 Too many attempts. rate_limited

POST /v1/public/accounts/{handle}/bookings/{booking_id}

Read a booking with its manage token in the body.

Operation id
readPublicBooking
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
booking_id path string yes Limits: at least 1 character.

Request body application/json, required

Field Type Required Notes
token string yes Limits: 1 to 1024 characters.

Answers

200 The booking. application/json

Field Type Always sent Notes
id string yes
version integer yes Limits: at least 1.
status string yes Values: pending , confirmed , canceled , expired .
start string yes Limits: format date-time.
end string yes Limits: format date-time.
event_type object yes
event_type.id string yes
event_type.name string yes
host object no
host.id string yes
host.display_name string yes
hosts array of object no
hosts[] object yes
hosts[].id string yes
hosts[].display_name string yes
location object yes
location.kind string yes
location.value string no
invitee_time_zone string yes
manage object yes
manage.cancel_token string yes
manage.reschedule_token string yes
redirect_url string no Where the booking page sends the visitor next: the event type's after-booking address with booking_id added and nothing else. Present only on the create and read answers of a confirmed booking whose address's host is still in the account's redirect_allowed_hosts.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

GET /v1/public/accounts/{handle}/bookings/{booking_id}/calendar-file

Download the calendar file for a booking.

Operation id
getPublicBookingCalendarFile
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
booking_id path string yes Limits: at least 1 character.
token query string yes Limits: at least 1 character.

Answers

200 The calendar file. text/calendar

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
429 Too many attempts. rate_limited

POST /v1/public/accounts/{handle}/bookings/{booking_id}/calendar-file

Download the calendar file for a booking. The manage token is in the body.

Operation id
postPublicBookingCalendarFile
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
booking_id path string yes Limits: at least 1 character.

Request body application/json, required

Field Type Required Notes
token string yes Limits: 1 to 1024 characters.

Answers

200 The calendar file. text/calendar

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

POST /v1/public/accounts/{handle}/bookings/{booking_id}/cancel

Cancel a booking with its cancel token.

Operation id
cancelPublicBooking
Who can call it
Anyone. No sign-in.
Credentials
None needed.
Retry key
Optional: send an Idempotency-Key header.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
booking_id path string yes Limits: at least 1 character.
Idempotency-Key header string no Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
token string no
reason string no

Answers

200 The booking is canceled. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
version integer yes Limits: at least 1.
status string yes Values: pending , confirmed , canceled , expired .
start string yes Limits: format date-time.
end string yes Limits: format date-time.
event_type object yes
event_type.id string yes
event_type.name string yes
host object no
host.id string yes
host.display_name string yes
hosts array of object no
hosts[] object yes
hosts[].id string yes
hosts[].display_name string yes
location object yes
location.kind string yes
location.value string no
invitee_time_zone string yes
manage object yes
manage.cancel_token string yes
manage.reschedule_token string yes
redirect_url string no Where the booking page sends the visitor next: the event type's after-booking address with booking_id added and nothing else. Present only on the create and read answers of a confirmed booking whose address's host is still in the account's redirect_allowed_hosts.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
409 The same identifier was already used for a different request. This request is already running. This was changed by someone else since it was read. id_conflict , request_in_progress , version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

POST /v1/public/accounts/{handle}/bookings/{booking_id}/reschedule

Move a booking to a new time with its reschedule token.

Operation id
reschedulePublicBooking
Who can call it
Anyone. No sign-in.
Credentials
None needed.
Retry key
Required: send an Idempotency-Key header.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
booking_id path string yes Limits: at least 1 character.
Idempotency-Key header string yes Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
token string no
start string yes Limits: format date-time.

Answers

200 The booking is at the new time. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
version integer yes Limits: at least 1.
status string yes Values: pending , confirmed , canceled , expired .
start string yes Limits: format date-time.
end string yes Limits: format date-time.
event_type object yes
event_type.id string yes
event_type.name string yes
host object no
host.id string yes
host.display_name string yes
hosts array of object no
hosts[] object yes
hosts[].id string yes
hosts[].display_name string yes
location object yes
location.kind string yes
location.value string no
invitee_time_zone string yes
manage object yes
manage.cancel_token string yes
manage.reschedule_token string yes
redirect_url string no Where the booking page sends the visitor next: the event type's after-booking address with booking_id added and nothing else. Present only on the create and read answers of a confirmed booking whose address's host is still in the account's redirect_allowed_hosts.

202 The move is still being finished. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
version integer yes Limits: at least 1.
status string yes Values: pending , confirmed , canceled , expired .
start string yes Limits: format date-time.
end string yes Limits: format date-time.
event_type object yes
event_type.id string yes
event_type.name string yes
host object no
host.id string yes
host.display_name string yes
hosts array of object no
hosts[] object yes
hosts[].id string yes
hosts[].display_name string yes
location object yes
location.kind string yes
location.value string no
invitee_time_zone string yes
manage object yes
manage.cancel_token string yes
manage.reschedule_token string yes
redirect_url string no Where the booking page sends the visitor next: the event type's after-booking address with booking_id added and nothing else. Present only on the create and read answers of a confirmed booking whose address's host is still in the account's redirect_allowed_hosts.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
409 The same identifier was already used for a different request. This request is already running. Someone else got that time. This was changed by someone else since it was read. id_conflict , request_in_progress , slot_taken , version_conflict
415 Send the body as JSON. unsupported_media_type
422 The time is not offered. invalid_slot
429 Too many attempts. rate_limited
503 A calendar could not be reached. provider_unavailable

POST /v1/public/manage/read

Read a manage page for its token. A manage link is a secret. The token is sent in the body, never in the URL.

Operation id
readManagedBooking
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Request body application/json, required

Field Type Required Notes
token string yes Limits: 1 to 1024 characters.
lang string no Limits: at most 64 characters.

Answers

200 The manage page's data, its brand colours and its sentences. application/json

Field Type Always sent Notes
manage string yes Values: cancel , reschedule .
accountId string yes
handle string yes
bookingId string yes
eventTypeId string yes
hostId string yes
eventName string yes
hostName string yes
accountName string yes
start string yes
end string yes
status string yes Values: confirmed , canceled , pending , expired .
locationKind string yes
locationValue string or null yes
locale string yes
inviteeTimeZone string yes
scheduleTimeZone string yes
durationMin number yes
windowDays number yes
minNoticeMin number yes
apiOrigin string yes
slotsPath string yes
actionPath string yes
readPath string yes
calendarPath string yes
bookAgainPath string or null yes
reasonMax number yes
messages map of text to object yes
messages{key} one of 2 shapes yes
messages{key}{variant 1} object yes Shape 1 of 2.
messages{key}{variant 1}.text string yes
messages{key}{variant 2} object yes Shape 2 of 2, where hidden is true.
messages{key}{variant 2}.hidden boolean yes Values: true .
languages array of object yes
languages[] object yes
languages[].lang string yes
languages[].name string yes
brand object or null yes
brand.--av-primary string yes
brand.--av-primary-dark string yes
brand.--av-mint string yes
sentences map of text to object yes
sentences{key} one of 2 shapes yes
sentences{key}{variant 1} object yes Shape 1 of 2.
sentences{key}{variant 1}.text string yes
sentences{key}{variant 2} object yes Shape 2 of 2, where hidden is true.
sentences{key}{variant 2}.hidden boolean yes Values: true .

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

POST /v1/public/accounts/{handle}/routing-forms/{routing_form_id}/submissions

Submit a routing form and learn where to go next.

Operation id
submitRoutingForm
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: at least 1 character.
routing_form_id path string yes Limits: at least 1 character.

Request body application/json, required

Field Type Required Notes
answers map of text to string or array of string or null yes
human_check string yes
locale string no Limits: at most 35 characters.
surface string no Values: booking_page , embed .

Answers

201 The submission is stored. Where the visitor goes next. application/json

Field Type Always sent Notes
submission_id string yes
result one of 3 shapes yes
result{kind=event_type} object yes Shape 1 of 3, where kind is event_type.
result{kind=event_type}.kind string yes Values: event_type .
result{kind=event_type}.address string yes
result{kind=url} object yes Shape 2 of 3, where kind is url.
result{kind=url}.kind string yes Values: url .
result{kind=url}.url string yes
result{kind=message} object yes Shape 3 of 3, where kind is message.
result{kind=message}.kind string yes Values: message .
result{kind=message}.text string yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited
503 A system this account relies on did not answer. Try again in a moment. lookup_unavailable

POST /v1/public/accounts/{handle}/page-reports

Report a booking page to the product's operator, with a reason: deceptive (asks for a password, a payment or personal details under a false pretence), impersonation, spam, harmful, or other. Nothing about the person reporting is stored.

Operation id
reportPage
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
handle path string yes Limits: 1 to 64 characters.

Request body application/json, required

Field Type Required Notes
path string yes Limits: 1 to 300 characters.
reason string yes Values: deceptive , impersonation , spam , harmful , other .
human_check string yes

Answers

204 The report was received.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
404 Nothing was found there. not_found
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited