API reference

Link tokens

4 operations.

GET /v1/link-tokens

The account's prefilled links, newest first, with their visitor's details and state. Never a link's token. Pass next_cursor as cursor for the next page.

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

Parameters

Name In Type Required Notes
cursor query string no
limit query integer no Limits: at least 1, at most 200.

Answers

200 The links. application/json

Field Type Always sent Notes
link_tokens array of object yes
link_tokens[] object yes
link_tokens[].id string yes
link_tokens[].state string yes used while a booking holds the link, revoked once revoked, expired past its expiry. Values: active , used , expired , revoked .
link_tokens[].event_type_id string yes
link_tokens[].host_id string or null yes
link_tokens[].email string or null yes Null when the link was made without an email.
link_tokens[].name string or null yes
link_tokens[].phone string or null yes
link_tokens[].answers array of object yes
link_tokens[].answers[] object yes
link_tokens[].answers[].question_id string yes
link_tokens[].answers[].value string or array of string yes
link_tokens[].external_ref string or null yes
link_tokens[].requested_by string or null yes
link_tokens[].locked array of string yes
link_tokens[].vouch boolean yes
link_tokens[].booking_id string or null yes The booking that holds the link, while one does.
link_tokens[].created_by object yes
link_tokens[].created_by.type string yes Values: member , api_key .
link_tokens[].created_by.id string yes
link_tokens[].created_at string yes Limits: format date-time.
link_tokens[].expires_at string yes Limits: format date-time.
link_tokens[].revoked_at string or null yes Limits: format date-time.
next_cursor string or null 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/link-tokens

Mints a prefilled link that books one event type once, for one visitor, and answers its address once. Needs the right to book for a visitor with the pinned host (or any host); vouch also needs bookings.read and bookings.manage.

Operation id
createLinkToken
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
bookings.create_own
Retry key
Optional: send an Idempotency-Key header.
Assistant tool
No. It mints a capability, credential or secret that outlives the grant and is later checked against the member's full role (decision 0043, point 8).

Parameters

Name In Type Required Notes
Idempotency-Key header string no 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
event_type_id string yes The event type the link books. Limits: pattern ^evt_[0-9a-z]{26}$.
host_id string no Pins the link to this host of the event type. A pinned host who cannot take the booking answers unavailable, never another host. Limits: pattern ^host_[0-9a-z]{26}$.
email string no The visitor's email. Fixed on the page: the visitor cannot change it. Leave it out when you do not know it: the visitor types it. Required with vouch. Limits: at most 320 characters.
name string no The visitor's name, filled in on the page. Limits: at most 200 characters.
phone string no The visitor's phone number, in international form, filled in on the page. Limits: at most 40 characters.
answers array of object no Answers to the event type's questions, by question id. Limits: at most 100 items.
answers[] object yes
answers[].question_id string yes Limits: 1 to 40 characters.
answers[].value string or array of string yes
external_ref string no Your own reference for this visitor or record, stored on the booking. Never shown on the page. Limits: at most 255 characters.
requested_by string no Your system's own reference to the person who asked for this link there, such as a user id: 1 to 255 characters on one line, with no spaces at either end. Stored on the booking with your key or member as its issuer, and sent in every webhook body of the booking as requested_by. A hint, never authority: it names who asked for the link, not who completed the booking. Never shown on the page, in an email or in a lookup.
locked array of string no Which prefilled fields the visitor may not change. Each must have a value.
vouch boolean no Your system vouches for the email: the page may show the visitor's upcoming booking of this event type with its manage links. Needs bookings.read and bookings.manage.
expires_at string no When the link stops working. In the future and at most 30 days from now; 7 days from now when left out. Limits: format date-time.

Answers

201 The link, with its address. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
state string yes used while a booking holds the link, revoked once revoked, expired past its expiry. Values: active , used , expired , revoked .
event_type_id string yes
host_id string or null yes
email string or null yes Null when the link was made without an email.
name string or null yes
phone string or null yes
answers array of object yes
answers[] object yes
answers[].question_id string yes
answers[].value string or array of string yes
external_ref string or null yes
requested_by string or null yes
locked array of string yes
vouch boolean yes
booking_id string or null yes The booking that holds the link, while one does.
created_by object yes
created_by.type string yes Values: member , api_key .
created_by.id string yes
created_at string yes Limits: format date-time.
expires_at string yes Limits: format date-time.
revoked_at string or null yes Limits: format date-time.
url string or null yes The page address with the link's token in its fragment, shown this once. Null on a repeat of the same request (same Idempotency-Key): the token is never shown again, so revoke the link and mint another.

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. id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/link-tokens/{link_token_id}

Revokes an unused prefilled link: it stops working at once. A link a booking holds cannot be revoked; cancel the booking instead. Revoking a revoked link changes nothing.

Operation id
revokeLinkToken
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
bookings.create_own
Assistant tool
No. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

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

Answers

200 The link after the revoke. application/json

Field Type Always sent Notes
id string yes
state string yes used while a booking holds the link, revoked once revoked, expired past its expiry. Values: active , used , expired , revoked .
event_type_id string yes
host_id string or null yes
email string or null yes Null when the link was made without an email.
name string or null yes
phone string or null yes
answers array of object yes
answers[] object yes
answers[].question_id string yes
answers[].value string or array of string yes
external_ref string or null yes
requested_by string or null yes
locked array of string yes
vouch boolean yes
booking_id string or null yes The booking that holds the link, while one does.
created_by object yes
created_by.type string yes Values: member , api_key .
created_by.id string yes
created_at string yes Limits: format date-time.
expires_at string yes Limits: format date-time.
revoked_at string or null yes Limits: format date-time.

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. conflict
429 Too many attempts. rate_limited

POST /v1/link-tokens/resolve

Reads the state and bound booking of one exact prefilled token. A key also needs bookings.read. An active result is only a snapshot and does not prove that no booking is in progress.

Operation id
resolveLinkToken
Who can call it
The authenticating API key, in its own account.
Credentials
API key
Permission
bookings.read_own

Request body application/json, required

Field Type Required Notes
token string yes The original opaque token from the link fragment. Never put it in a URL.

Answers

200 The token's current state and the booking holding it, if any. application/json

Field Type Always sent Notes
token_id string yes The opaque ID for the existing revoke operation. Limits: pattern ^ltk_[0-9a-z]{26}$.
state string yes Values: active , used , expired , revoked .
booking_id string or null 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
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited