Booking links
8 operations.
-
GET
/v1/links -
POST
/v1/links -
POST
/v1/links/legacy-batch -
POST
/v1/links/legacy-switch -
GET
/v1/links/path-check -
GET
/v1/links/{link_id} -
PATCH
/v1/links/{link_id} -
DELETE
/v1/links/{link_id}
GET
/v1/links
The account's booking links, in path order.
- Operation id
listLinks- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
event_type_id
|
query | string | no | Limits: pattern ^evt_[0-9a-z]{26}$. |
host_id
|
query | string | no | Limits: pattern ^host_[0-9a-z]{26}$. |
active
|
query | string | no |
Values:
true
,
false
.
|
Answers
200 The booking links. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
links
|
array of BookingLink | 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/links
Adds a booking link to an event type, a host, a routing form or another address. The path is stored as a slug. A second link to the same event type, host or form is an extra path, not a second canonical one. With origin: import and an old address it is a legacy link, created off.
- Operation id
createLink- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.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 |
|---|---|---|---|
path
|
string | yes | |
target
|
one of 4 shapes | yes | |
target{type=event_type}
|
object | yes | Shape 1 of 4, where type is event_type. |
target{type=event_type}.type
|
string | yes |
Values:
event_type
.
|
target{type=event_type}.event_type_id
|
string | yes | Limits: pattern ^evt_[0-9a-z]{26}$. |
target{type=host}
|
object | yes | Shape 2 of 4, where type is host. |
target{type=host}.type
|
string | yes |
Values:
host
.
|
target{type=host}.host_id
|
string | yes | Limits: pattern ^host_[0-9a-z]{26}$. |
target{type=redirect}
|
object | yes | Shape 3 of 4, where type is redirect. |
target{type=redirect}.type
|
string | yes |
Values:
redirect
.
|
target{type=redirect}.url
|
string | yes | |
target{type=routing_form}
|
object | yes | Shape 4 of 4, where type is routing_form. |
target{type=routing_form}.type
|
string | yes |
Values:
routing_form
.
|
target{type=routing_form}.routing_form_id
|
string | yes | Limits: pattern ^rtf_[0-9a-z]{26}$. |
origin
|
string | no |
import makes a legacy link for an account that moved from another tool: created off, forwarding to its old address, to an event type or a routing form only, never canonical.
Values:
import
.
|
inactive_redirect_url
|
string | no |
A legacy link's old address, an https address: where the link forwards while it is off. Required with origin: import, refused without it.
|
duplicate_rule
|
string | no |
Whether this link refuses a second booking from the same visitor. off (the default) does not. this_link refuses another booking through this link. account refuses another booking anywhere in the account, including one made by staff or through the API.
Values:
off
,
this_link
,
account
.
|
duplicate_match_phone
|
boolean | no | When the duplicate rule is on, also match a normalised phone number. Off by default. A phone that does not canonicalise is not matched. |
Answers
201 The booking link. 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)
|
BookingLink | 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
|
POST
/v1/links/legacy-batch
Makes up to 100 legacy links in one write, each off and forwarding to its old address, and answers each new address in item order. A path is the item's own or made from the old address's path. A path that is invalid, reserved, taken, given twice, or under a host's own path refuses the whole batch, naming each item in its issues; nothing is made and nothing is suffixed.
- Operation id
createLegacyLinks- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.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 |
|---|---|---|---|
items
|
array of object | yes | 1 to 100 old addresses, each with its target. Limits: 1 to 100 items. |
items[]
|
object | yes | |
items[].old_address
|
string | yes | The old address, an https address: where the link forwards while it is off. |
items[].target
|
one of 2 shapes | yes | |
items[].target{type=event_type}
|
object | yes | Shape 1 of 2, where type is event_type. |
items[].target{type=event_type}.type
|
string | yes |
Values:
event_type
.
|
items[].target{type=event_type}.event_type_id
|
string | yes | Limits: pattern ^evt_[0-9a-z]{26}$. |
items[].target{type=routing_form}
|
object | yes | Shape 2 of 2, where type is routing_form. |
items[].target{type=routing_form}.type
|
string | yes |
Values:
routing_form
.
|
items[].target{type=routing_form}.routing_form_id
|
string | yes | Limits: pattern ^rtf_[0-9a-z]{26}$. |
items[].path
|
string | no | The path under the account. Left out, it is made from the old address's path: each segment as a slug, at most 3 segments. |
Answers
201 The new legacy links. application/json
-
Header
Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
| Field | Type | Always sent | Notes |
|---|---|---|---|
links
|
array of BookingLink | yes | The new legacy links, in the order of the items. |
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
|
POST
/v1/links/legacy-switch
Turns up to 25 legacy links on or off in one write, all or none. Each item names a link, the version you read and the state wanted. A link is turned on only when its target can take bookings now: an event type that is on, shown on a booking page, with a host who can be booked, has hours and a connected calendar; a routing form that is on, whose every event type passes the same check. Turning off is never refused for that. Any refused item refuses the whole switch, naming each item in its issues; nothing changes. Each link gets a new version, a history row and an audit row. To go back, turn them off again, or restore an earlier version from the history.
- Operation id
switchLegacyLinks- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.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 |
|---|---|---|---|
items
|
array of object | yes | 1 to 25 legacy links, each named once. Limits: 1 to 25 items. |
items[]
|
object | yes | |
items[].link_id
|
string | yes | Limits: pattern ^lnk_[0-9a-z]{26}$. |
items[].version
|
integer | yes | The link's version, the one you read. Limits: at least 1. |
items[].is_active
|
boolean | yes |
true turns the link on: it opens the new booking page. false turns it off: it forwards to its old address.
|
Answers
200 The legacy links after the switch. application/json
-
Header
Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
| Field | Type | Always sent | Notes |
|---|---|---|---|
batch_id
|
string | yes |
Names this switch: the id of its first history row. Every audit row of the switch carries it as batch_id.
|
links
|
array of BookingLink | yes | The legacy links after the switch, in the order of the items. |
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 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
|
GET
/v1/links/path-check
Whether a path can be saved in this account. The answer is the slug the path would be stored as.
- Operation id
checkLinkPath- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
path
|
query | string | yes |
Answers
200 The normalised path, and why it cannot be saved when it cannot. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
path
|
string | yes | |
available
|
boolean | yes | |
problems
|
array of string | 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
|
GET
/v1/links/{link_id}
One booking link, including the other paths that open the same target.
- Operation id
getLink- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.read - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
link_id
|
path | string | yes | Limits: pattern ^lnk_[0-9a-z]{26}$. |
Answers
200 The booking link. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
BookingLink | 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/links/{link_id}
Changes a booking link. Send the version you read. A new path keeps the old one as an alias. The redirect address itself is chosen at creation. A legacy link's old address can be replaced, never cleared. A legacy link is turned on only when its target can take bookings now; the refusal names why under json.is_active.
- Operation id
updateLink- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.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 |
|---|---|---|---|---|
link_id
|
path | string | yes | Limits: pattern ^lnk_[0-9a-z]{26}$. |
Request body application/json, required
| Field | Type | Required | Notes |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
path
|
string | no | |
is_active
|
boolean | no | |
inactive_redirect_url
|
string or null | no | |
duplicate_rule
|
string | no |
Values:
off
,
this_link
,
account
.
|
duplicate_match_phone
|
boolean | no |
Answers
200 The booking link after the change. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
BookingLink | 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
|
DELETE
/v1/links/{link_id}
Removes an old path. The canonical link stays.
- Operation id
deleteLink- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
links.manage - Assistant tool
- No. It deletes. A delete is never a tool (decision 0043, point 8).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
link_id
|
path | string | yes | Limits: pattern ^lnk_[0-9a-z]{26}$. |
version
|
query | integer | yes | Limits: at least 1. |
Answers
204 The old path has been removed.
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. This was changed by someone else since it was read. |
conflict
,
version_conflict
|
| 429 | Too many attempts. |
rate_limited
|