API reference

Event types

13 operations.

GET /v1/event-types

The account's event types, in their stored order.

Operation id
listEventTypes
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.read
Assistant tool
Yes. It only reads.

Parameters

Name In Type Required Notes
archived query string no Values: true , false .
active query string no Values: true , false .
host_id query string no Limits: pattern ^host_[0-9a-z]{26}$.

Answers

200 The event types. Archived ones are left out unless archived is true. application/json

Field Type Always sent Notes
event_types array of EventType yes

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
429 Too many attempts. rate_limited

POST /v1/event-types

Adds an event type. It starts off, and its public path is chosen from the name.

Operation id
createEventType
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Retry key
Required: send an Idempotency-Key header.
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
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
name string yes
duration_min integer yes
description string or null no Limits: at most 2000 characters.
kind string no Values: one_on_one , round_robin , collective .
host_choice string no Values: link_only , visitor_picks .
visibility string no Values: listed , unlisted , api_only .
slot_interval_min integer or null no Limits: at least 1.
min_notice_min integer no
buffer_before_min integer no
buffer_after_min integer no
window_days integer no
max_guests integer no
schedule_id string or null no Limits: pattern ^sch_[0-9a-z]{26}$.
time_zone string or null no
locale string or null no
invitee_notification string no Values: email , calendar_invite , both .
visitor_notifications object no
visitor_notifications.confirmation boolean no Whether the visitor is sent a confirmation email for a new booking.
visitor_notifications.changes boolean no Whether the visitor is told about a new time, a new host, or a cancellation.
visitor_notifications.reminders boolean no Whether the visitor is sent reminder emails before the meeting.
reminder_offsets array of integer no Limits: at most 5 items.
tags array of string no Limits: at most 10 items.
position integer no Limits: at least 0.
reschedule_host string no Only on a round-robin event type: whether a reschedule may move the booking to another pool host. keep: never; a host who can no longer be booked gets no new time. any: when the booking's own host cannot take the new time, another pool host is chosen as for a new round-robin booking, and the visitor and both hosts are told. Stored whatever the kind and ignored on other kinds. Default keep. Values: keep , any .

Answers

201 The event type. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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. conflict , id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

GET /v1/event-types/{event_type_id}

One event type, archived or not, with its hosts, host groups, pauses, locations, questions and pages.

Operation id
getEventType
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.read
Assistant tool
Yes. It only reads.

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Answers

200 The event type. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
429 Too many attempts. rate_limited

PATCH /v1/event-types/{event_type_id}

Changes an event type. Send the version you read. Turning it on is refused, and nothing else is saved, when a host or a location is still missing. Turning it off is refused while a switched-on routing form sends visitors to it. A brand_id must name a brand of this account; another account's brand answers not found. A confirmation_redirect_url whose host the account does not allow is refused, and nothing is saved.

Operation id
updateEventType
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
name string no
description string or null no Limits: at most 2000 characters.
kind string no Values: one_on_one , round_robin , collective .
host_choice string no Values: link_only , visitor_picks .
visibility string no Values: listed , unlisted , api_only .
duration_min integer no
slot_interval_min integer or null no Limits: at least 1.
min_notice_min integer no
buffer_before_min integer no
buffer_after_min integer no
window_days integer no
max_guests integer no
schedule_id string or null no Limits: pattern ^sch_[0-9a-z]{26}$.
time_zone string or null no
locale string or null no
invitee_notification string no Values: email , calendar_invite , both .
visitor_notifications object no
visitor_notifications.confirmation boolean no Whether the visitor is sent a confirmation email for a new booking.
visitor_notifications.changes boolean no Whether the visitor is told about a new time, a new host, or a cancellation.
visitor_notifications.reminders boolean no Whether the visitor is sent reminder emails before the meeting.
reminder_offsets array of integer no Limits: at most 5 items.
tags array of string no Limits: at most 10 items.
position integer no Limits: at least 0.
reschedule_host string no Only on a round-robin event type: whether a reschedule may move the booking to another pool host. keep: never; a host who can no longer be booked gets no new time. any: when the booking's own host cannot take the new time, another pool host is chosen as for a new round-robin booking, and the visitor and both hosts are told. Stored whatever the kind and ignored on other kinds. Default keep. Values: keep , any .
counts_toward_host_limits boolean no Whether this event type's bookings count toward each host's own limits.
counts_no_shows boolean no Whether a confirmed booking of this event type whose outcome is a no-show still counts toward every limit. On by default; off frees its place in the period.
brand_id string or null no A brand of this account for the event type's pages and emails. Null: the account's default brand. Limits: pattern ^brd_[0-9a-z]{26}$.
confirmation_redirect_url string or null no Where the visitor is sent after a confirmed booking: an https address on a host in the account's redirect_allowed_hosts, with no port, user name or placeholder. The booking page adds booking_id and nothing else. Null: none. Limits: at most 2000 characters.
is_active boolean no

Answers

200 The event type after the change. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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/event-types/{event_type_id}/archive

Archives an event type and switches its booking links off. The row stays. Refused while a switched-on routing form sends visitors to it.

Operation id
archiveEventType
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.

Answers

200 The archived event type. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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/event-types/{event_type_id}/restore

Brings an archived event type back. Links that were switched off stay off.

Operation id
restoreEventType
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.

Answers

200 The event type, no longer archived. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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

POST /v1/event-types/{event_type_id}/clone

Copies an event type: its settings, hosts, host groups, questions, locations, limits and its own hours (as a new schedule). The copy is switched off and named "Copy of" and the name. Booking links, pauses, bookings and history are not copied.

Operation id
cloneEventType
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Retry key
Required: send an Idempotency-Key header.
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.
Idempotency-Key header string yes Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Answers

201 The new event type. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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. conflict , id_conflict , request_in_progress
429 Too many attempts. rate_limited

PUT /v1/event-types/{event_type_id}/hosts

Replaces the hosts of an event type. Send the whole list and the version you read.

Operation id
replaceEventTypeHosts
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
hosts array of object yes
hosts[] object yes
hosts[].host_id string yes Limits: pattern ^host_[0-9a-z]{26}$.
hosts[].schedule_id string or null no Limits: pattern ^sch_[0-9a-z]{26}$.
hosts[].priority integer no Limits: at least 1, at most 100.
hosts[].weight integer no Limits: at least 0, at most 10000.

Answers

200 The event type after the hosts were replaced. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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

PUT /v1/event-types/{event_type_id}/host-groups

Replaces the host groups of an event type. Send the whole list and the version you read. A host assigned directly keeps the direct row's priority and weight.

Operation id
replaceEventTypeHostGroups
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
host_groups array of object yes
host_groups[] object yes
host_groups[].host_group_id string yes Limits: pattern ^grp_[0-9a-z]{26}$.
host_groups[].priority integer no Limits: at least 1, at most 100.
host_groups[].weight integer no Limits: at least 0, at most 10000.

Answers

200 The event type after the host groups were replaced. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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

PUT /v1/event-types/{event_type_id}/pauses

Replaces the pauses of an event type: hosts who stay assigned but get no bookings of it until the pause ends. Send the whole list; an empty list clears it. Pausing the last bookable host of an active event type is refused. Unpausing never is.

Operation id
replaceEventTypePauses
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
pauses array of object yes
pauses[] object yes
pauses[].host_id string yes Limits: pattern ^host_[0-9a-z]{26}$.
pauses[].until_at string or null no When the pause ends. Left out or null pauses until the pause is removed. Limits: format date-time.

Answers

200 The event type after the pauses were replaced. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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

PUT /v1/event-types/{event_type_id}/locations

Replaces the locations. Send the whole list. An entry that carries its id keeps that id.

Operation id
replaceEventTypeLocations
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
locations array of object yes
locations[] object yes
locations[].id string no Limits: pattern ^loc_[0-9a-z]{26}$.
locations[].kind string yes Values: google_meet , microsoft_teams , phone , in_person , custom_text .
locations[].value_source string no Values: fixed , host_profile , booker .
locations[].value string or null no

Answers

200 The event type after the locations were replaced. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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

PUT /v1/event-types/{event_type_id}/limits

Replaces the booking limits of an event type. Send the whole list and the version you read; an empty list clears it. At most one limit for each kind and period. A day, a week (Monday to Sunday), two weeks (fixed blocks from a starting Monday) and a month are local calendar periods: each host's own time zone and starting Monday for per_host, the account's for total.

Operation id
replaceEventTypeLimits
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
limits array of object yes
limits[] object yes
limits[].kind string yes per_host: each host, this event type only. total: all hosts together. invitee_active: one visitor's future bookings. Values: per_host , total , invitee_active .
limits[].period string or null no A day, a week from Monday to Sunday, two weeks in fixed blocks from the starting Monday, or a calendar month. Required for per_host and total; left out or null for invitee_active. Values: day , week , two_weeks , month .
limits[].max_count integer yes At most this many bookings in one period. Limits: at least 1.

Answers

200 The event type after the limits were replaced. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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

PUT /v1/event-types/{event_type_id}/questions

Replaces the questions. Send the whole list. An entry that carries its id keeps that id.

Operation id
replaceEventTypeQuestions
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
questions array of object yes
questions[] object yes
questions[].id string no Limits: pattern ^etq_[0-9a-z]{26}$.
questions[].label string yes
questions[].kind string yes Values: short_text , long_text , single_choice , multi_choice , dropdown , phone .
questions[].required boolean no
questions[].options array of string no
questions[].allow_other boolean no

Answers

200 The event type after the questions were replaced. application/json

Field Type Always sent Notes
(whole body) EventType yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
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