Hosts
12 operations.
-
GET
/v1/hosts -
POST
/v1/hosts -
GET
/v1/hosts/{host_id} -
PATCH
/v1/hosts/{host_id} -
PUT
/v1/hosts/{host_id}/limits -
GET
/v1/me/host-limits -
GET
/v1/hosts/{host_id}/limit-usage -
POST
/v1/hosts/{host_id}/archive -
POST
/v1/hosts/{host_id}/restore -
PUT
/v1/hosts/{host_id}/external-ids/{system} -
POST
/v1/hosts/{host_id}/external-ids/{system}/remove -
GET
/v1/hosts/{host_id}/busy
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
|