Link tokens
4 operations.
-
GET
/v1/link-tokens -
POST
/v1/link-tokens -
DELETE
/v1/link-tokens/{link_token_id} -
POST
/v1/link-tokens/resolve
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
|