API reference

Hosts

12 operations.

GET /v1/hosts

The account's hosts, newest first.

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

Parameters

Name In Type Required Notes
limit query integer no Limits: at least 1, at most 100.
before query string no Limits: pattern ^host_[0-9a-z]{26}$.
archived query string no Values: true , false .

Answers

200 One page of hosts. Archived hosts are left out unless archived is true. application/json

Field Type Always sent Notes
hosts array of Host 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/hosts

Adds a host. The host's default schedule is created with it, with Monday to Friday, 09:00 to 17:00, in the host's time zone.

Operation id
createHost
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
hosts.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
display_name string yes
email string yes
time_zone string yes
member_id string or null no Limits: pattern ^mem_[0-9a-z]{26}$.
phone string or null no
locale string or null no

Answers

201 The host. 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) Host 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
402 The account needs an eligible plan or a Free host selection. plan_required
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 same identifier was already used for a different request. This request is already running. id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

GET /v1/hosts/{host_id}

One host, archived or not.

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

Parameters

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

Answers

200 The host. application/json

Field Type Always sent Notes
(whole body) Host 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/hosts/{host_id}

Changes a host. Send the version you read. A member may change the name and time zone of the host linked to them. Activation is applied after the profile.

Operation id
updateHost
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
hosts.manage_own
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
host_id path string yes Limits: pattern ^host_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
display_name string no
email string no
time_zone string no
member_id string or null no Limits: pattern ^mem_[0-9a-z]{26}$.
phone string or null no
locale string or null no
is_active boolean no

Answers

200 The host after the change. application/json

Field Type Always sent Notes
(whole body) Host 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
402 The account needs an eligible plan or a Free host selection. plan_required
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/hosts/{host_id}/limits

Replaces a host's own booking limits: at most so many bookings a day, a week (Monday to Sunday), two weeks (fixed blocks from a starting Monday) or a month, in the host's time zone, across every event type that counts toward them. Each replaces the account's default for its period; a null maximum means no limit in that period. Send the whole list and the version you read; an empty list clears it, so the account's defaults apply. Optionally sets the host's own starting Monday. A member may change the limits of the host linked to them.

Operation id
replaceHostLimits
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
hosts.manage_own
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
host_id path string yes Limits: pattern ^host_[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[].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 the host's time zone. Values: day , week , two_weeks , month .
limits[].max_count integer or null yes At most this many bookings in one period. Null: no limit in this period, whatever the account's default says. Limits: at least 1.
limit_cycle_start string or null no The Monday the host's two-week blocks are counted from, YYYY-MM-DD in the host's time zone. Left out: unchanged. Null: the account's. Limits: pattern ^\d{4}-\d{2}-\d{2}$.

Answers

200 The host after the change. application/json

Field Type Always sent Notes
(whole body) Host 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/me/host-limits

The booking limits of the host linked to the caller, and how many places are used and left in the current periods. Null when no host is linked to the caller (a key never has one). Counts only: never which bookings, never an event type's total, never another host.

Operation id
getOwnHostLimits
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
hosts.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Answers

200 The caller's own host's limits, or null. application/json

Field Type Always sent Notes
host object or null yes
host.host_id string yes
host.time_zone string yes
host.limit_cycle_start string yes The Monday the host's two-week blocks are counted from: its own, else the account's.
host.limits array of object yes The host's own limits, every period, across every event type that counts toward them.
host.limits[] object yes
host.limits[].period string yes Values: day , week , two_weeks , month .
host.limits[].max_count integer or null yes The number that applies. Null: no limit.
host.limits[].period_start string yes The current period's start, inclusive. Limits: format date-time.
host.limits[].period_end string yes The current period's end, exclusive. Limits: format date-time.
host.limits[].used integer yes Bookings that count in the current period.
host.limits[].left integer or null yes Places left in the current period. Null: no limit.
host.limits[].source string yes own: the host's own limit. default: the account's default. none: no limit in this period. Values: own , default , none .
host.event_types array of object yes The per-host limits of each event type the host is on, counting only this host's bookings of it.
host.event_types[] object yes
host.event_types[].event_type_id string yes
host.event_types[].name string yes
host.event_types[].limits array of object yes
host.event_types[].limits[] object yes
host.event_types[].limits[].period string yes Values: day , week , two_weeks , month .
host.event_types[].limits[].max_count integer or null yes The number that applies. Null: no limit.
host.event_types[].limits[].period_start string yes The current period's start, inclusive. Limits: format date-time.
host.event_types[].limits[].period_end string yes The current period's end, exclusive. Limits: format date-time.
host.event_types[].limits[].used integer yes Bookings that count in the current period.
host.event_types[].limits[].left integer or null yes Places left in the current period. Null: no limit.

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

GET /v1/hosts/{host_id}/limit-usage

One host's booking limits and how many places are used and left in the current periods. Counts only, never which bookings.

Operation id
getHostLimitUsage
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. Not in the first set of tools (decision 0043, point 9).

Parameters

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

Answers

200 The host's limits. application/json

Field Type Always sent Notes
host_id string yes
time_zone string yes
limit_cycle_start string yes The Monday the host's two-week blocks are counted from: its own, else the account's.
limits array of object yes The host's own limits, every period, across every event type that counts toward them.
limits[] object yes
limits[].period string yes Values: day , week , two_weeks , month .
limits[].max_count integer or null yes The number that applies. Null: no limit.
limits[].period_start string yes The current period's start, inclusive. Limits: format date-time.
limits[].period_end string yes The current period's end, exclusive. Limits: format date-time.
limits[].used integer yes Bookings that count in the current period.
limits[].left integer or null yes Places left in the current period. Null: no limit.
limits[].source string yes own: the host's own limit. default: the account's default. none: no limit in this period. Values: own , default , none .
event_types array of object yes The per-host limits of each event type the host is on, counting only this host's bookings of it.
event_types[] object yes
event_types[].event_type_id string yes
event_types[].name string yes
event_types[].limits array of object yes
event_types[].limits[] object yes
event_types[].limits[].period string yes Values: day , week , two_weeks , month .
event_types[].limits[].max_count integer or null yes The number that applies. Null: no limit.
event_types[].limits[].period_start string yes The current period's start, inclusive. Limits: format date-time.
event_types[].limits[].period_end string yes The current period's end, exclusive. Limits: format date-time.
event_types[].limits[].used integer yes Bookings that count in the current period.
event_types[].limits[].left integer or null yes Places left in the current period. Null: no limit.

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

POST /v1/hosts/{host_id}/archive

Archives a host. The row stays, and so do the host's schedules. An archived host cannot be changed.

Operation id
archiveHost
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).

Parameters

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

Request body application/json, required

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

Answers

200 The archived host. application/json

Field Type Always sent Notes
(whole body) Host 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/hosts/{host_id}/restore

Brings an archived host back. Refused when another host now has this email or member link.

Operation id
restoreHost
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).

Parameters

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

Request body application/json, required

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

Answers

200 The host, no longer archived. application/json

Field Type Always sent Notes
(whole body) Host 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
402 The account needs an eligible plan or a Free host selection. plan_required
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/hosts/{host_id}/external-ids/{system}

Gives a host its id in another system, such as the user id a CRM has for this person. Send the id you last saw for this host and system (null for none). One id names one host per system: an id another host has is refused, never moved. An archived host takes no new id. Not part of the host's version.

Operation id
setHostExternalId
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. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
host_id path string yes Limits: pattern ^host_[0-9a-z]{26}$.
system path string yes The account's name for the other system: a lower-case letter, then lower-case letters, digits, _ or -, 1 to 32 characters.

Request body application/json, required

Field Type Required Notes
external_id string yes The host's id in that system, exactly as that system gives it: 1 to 255 characters on one line, with no spaces at either end. Compared with its case.
expected_external_id string or null yes The id this host had in that system when you read it, or null when it had none. A different stored id refuses the change as a version conflict.

Answers

200 The host after the change. application/json

Field Type Always sent Notes
(whole body) Host 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/hosts/{host_id}/external-ids/{system}/remove

Removes a host's id in another system. Send the id you last saw. An archived host's ids can be removed. The id travels in the body, never in the address, because it names a person's account in that system.

Operation id
removeHostExternalId
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. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

Name In Type Required Notes
host_id path string yes Limits: pattern ^host_[0-9a-z]{26}$.
system path string yes The account's name for the other system: a lower-case letter, then lower-case letters, digits, _ or -, 1 to 32 characters.

Request body application/json, required

Field Type Required Notes
expected_external_id string yes The id this host had in that system when you read it. A different stored id refuses the removal as a version conflict.

Answers

200 The host after the change. application/json

Field Type Always sent Notes
(whole body) Host 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/hosts/{host_id}/busy

When one host is busy in a range: spans only, never what fills them. For a system that draws its own calendar; a booking checks the time again.

Operation id
getHostBusy
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
calendars.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
host_id path string yes Limits: pattern ^host_[0-9a-z]{26}$.
from query string yes The start of the range, inclusive. Limits: format date-time.
to query string yes The end of the range, exclusive. At most 62 days after from, the same bound as a slot list. Limits: format date-time.

Answers

200 The host's busy spans in the range. application/json

Field Type Always sent Notes
(whole body) HostBusy 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
503 A calendar could not be reached. provider_unavailable