Account
7 operations.
-
POST
/v1/accounts -
POST
/v1/account-deletion -
POST
/v1/account-deletion/cancel -
GET
/v1/account -
PATCH
/v1/account -
PUT
/v1/account/host-limit-defaults -
GET
/v1/account/export
POST
/v1/accounts
Creates an account with the signed-in person as its owner, and acts in it.
- Operation id
createAccount- Who can call it
- A signed-in person, for themselves. Not tied to an account.
- Credentials
- session
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
handle
|
string | yes | Limits: 1 to 64 characters. |
name
|
string | yes | Limits: 1 to 200 characters. |
time_zone
|
string | yes | Limits: 1 to 64 characters. |
locale
|
string | no | Limits: 1 to 35 characters. |
human_check
|
string | yes |
Answers
201 The new account. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
Account | 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. |
forbidden
|
| 409 | Another account already has this handle. |
handle_taken
|
| 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/account-deletion
Asks to delete an account the signed-in person owns, naming its handle as confirmation. The account closes at once (no pages, members, keys or assistants) and its data is purged after a grace period of 14 days, once every cancellation, email and calendar cleanup already queued has finished. Refused while the account has a pending booking or a confirmed booking that has not ended: the answer counts them. Download the account first: there is no download while it waits.
- Operation id
deleteAccount- Who can call it
- A signed-in person, for themselves. Not tied to an account.
- Credentials
- session
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
account_id
|
string | yes | Limits: 1 to 64 characters. |
handle
|
string | yes | Limits: 1 to 64 characters. |
Answers
200 The account, now waiting to be purged. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
account
|
object | yes | |
account.id
|
string | yes | |
account.handle
|
string | yes | |
account.name
|
string | yes | |
account.status
|
string | yes | |
deletion_requested_at
|
string or null | yes | Limits: format date-time. |
purge_after
|
string or null | yes | Limits: format date-time. |
purge_started_at
|
string or null | 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
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. |
forbidden
|
| 404 | Nothing was found there. |
not_found
|
| 409 | This cannot be done while something else depends on it. This request is already running. |
conflict
,
request_in_progress
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
| 503 | This environment is not fully set up. A calendar could not be reached. |
not_configured
,
provider_unavailable
|
POST
/v1/account-deletion/cancel
Cancels the deletion of an account the signed-in person owns, during its grace period: the account is active again, with its members, keys and assistants. Refused once the purge has started.
- Operation id
cancelAccountDeletion- Who can call it
- A signed-in person, for themselves. Not tied to an account.
- Credentials
- session
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
account_id
|
string | yes | Limits: 1 to 64 characters. |
Answers
200 The account, active again. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
account
|
object | yes | |
account.id
|
string | yes | |
account.handle
|
string | yes | |
account.name
|
string | yes | |
account.status
|
string | yes | |
deletion_requested_at
|
string or null | yes | Limits: format date-time. |
purge_after
|
string or null | yes | Limits: format date-time. |
purge_started_at
|
string or null | 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
|
| 401 | Sign in is required. |
unauthenticated
|
| 403 | You are not allowed to do that. |
forbidden
|
| 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
|
GET
/v1/account
The account this session acts in.
- Operation id
getAccount- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.read - Assistant tool
- Yes. It only reads.
Answers
200 The account. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
Account | 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/account
Changes the account's handle, name, time zone, default language, enabled languages, its two email settings (the host notice and the calendar file on a cancellation), whether changes made in a host's calendar flow back into the booking, how long visitor data is kept after a meeting, the sites that may show its booking pages in a frame, or the hosts its after-booking redirects may go to.
- Operation id
updateAccount- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.update - 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).
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
handle
|
string | no | Limits: 1 to 64 characters. |
name
|
string | no | Limits: 1 to 200 characters. |
time_zone
|
string | no | Limits: 1 to 64 characters. |
locale
|
string | no | Limits: 1 to 35 characters. |
enabled_locales
|
array of string or null | no | The languages the account's pages may be shown in, including the default. Null means the default language only. Limits: at most 20 items. |
has_host_notice
|
boolean | no | Whether a host gets an email when a booking is made, moved or canceled. |
has_cancel_calendar_file
|
boolean | no | Whether a cancellation email carries the calendar file that removes the meeting. |
has_calendar_sync
|
boolean | no | Whether a host's own move, delete or decline of a booking's event in their calendar changes the booking. On by default. |
visitor_data_retention_days
|
integer | no | How many days after a meeting ends its visitor's data is deleted: the name, email, phone, answers, guests, the routing form's answers, and the copies in webhook events and the email log. The booking itself stays. 30 to 730. Limits: at least 30, at most 730. |
embed_allowed_origins
|
array of string | no | The whole list of sites that may show the booking pages in a frame: exact https origins such as https://www.example.com, with no path and no wildcard. An empty list allows none. Limits: at most 20 items. |
redirect_allowed_hosts
|
array of string | no | The whole list of host names an event type's after-booking redirect may go to: exact names such as www.example.com, with no scheme, port, path or wildcard. An empty list allows none, and an event type's redirect to a host taken off the list stops at once. Limits: at most 20 items. |
Answers
200 The account after the change. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
Account | 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 | The handle was renamed recently. Another account already has this handle. This was changed by someone else since it was read. |
handle_renamed_recently
,
handle_taken
,
version_conflict
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
PUT
/v1/account/host-limit-defaults
Replaces the account's default for each host's own booking limits, and optionally the Monday two-week limits are counted from. A host's own limit for a period replaces the default for that period. Send the whole list and the account version you read. Changing the starting Monday also needs account.update.
- Operation id
replaceHostLimitDefaults- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
hosts.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).
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
defaults
|
array of object | yes | The whole list, at most one for each period. An empty list removes every default. Limits: at most 4 items. |
defaults[]
|
object | yes | |
defaults[].period
|
string | yes |
A day, a week from Monday to Sunday, two weeks in fixed blocks from the starting Monday, or a calendar month, in each host's time zone.
Values:
day
,
week
,
two_weeks
,
month
.
|
defaults[].max_count
|
integer | yes | At most this many bookings in one period. Limits: at least 1. |
limit_cycle_start
|
string | no | The Monday two-week limits are counted from, YYYY-MM-DD in the account's time zone. Left out: unchanged. It can be changed, never cleared. Changing it also needs account.update. Limits: pattern ^\d{4}-\d{2}-\d{2}$. |
Answers
200 The account after the change. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
Account | 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
|
GET
/v1/account/export
Downloads everything the account holds as one JSON Lines file: one line per row, {"table": ..., "row": {...}}, the account's own row first, and last a trailer with the rows written per table and "complete": true. A file without the trailer is incomplete: download it again. Instants are ISO 8601 UTC strings. Secrets are never written. It is a live read: a row changed during the download may appear as it was before or after the change.
- Operation id
exportAccount- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
account.export - Assistant tool
- No. It downloads the whole account, which is never an assistant's tool (decision 0045, point 1).
Answers
200 The account, one row per line, ending with the trailer. application/jsonl
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
|
| 422 | The account is too large to download in one file. |
export_too_large
|
| 429 | Too many attempts. |
rate_limited
|