Bookings
13 operations.
-
GET
/v1/bookings/export.csv -
GET
/v1/bookings/summary -
GET
/v1/bookings -
POST
/v1/bookings -
GET
/v1/bookings/{booking_id} -
GET
/v1/bookings/{booking_id}/timeline -
GET
/v1/bookings/{booking_id}/slots -
GET
/v1/event-types/{event_type_id}/slots -
POST
/v1/bookings/{booking_id}/cancel -
POST
/v1/bookings/{booking_id}/reschedule -
POST
/v1/bookings/{booking_id}/outcome -
POST
/v1/bookings/{booking_id}/reassign -
PUT
/v1/bookings/{booking_id}/reports/{system}
GET
/v1/bookings/export.csv
Download bookings as a spreadsheet.
- Operation id
exportBookings- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.export - Assistant tool
- No. It answers something other than JSON (decision 0043, point 7).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
status
|
query | string | no | |
host_id
|
query | string | no | Limits: pattern ^host_[0-9a-z]{26}$. |
event_type_id
|
query | string | no | Limits: pattern ^evt_[0-9a-z]{26}$. |
from
|
query | string | no | Limits: format date-time. |
to
|
query | string | no | Limits: format date-time. |
q
|
query | string | no | |
limit
|
query | string | no | |
cursor
|
query | string | no |
Answers
200 The bookings, one row per booking. text/csv
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/bookings/summary
Booking activity over account-local calendar days ending today, and confirmed starts in the next 168 hours.
- Operation id
getBookingActivitySummary- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.read_own - Assistant tool
- No. Not in the first set of tools (decision 0043, point 9).
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
days
|
query | string | no |
Values:
7
,
30
,
90
.
|
Answers
200 Booking activity in the caller's host scope. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
BookingActivitySummary | 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/bookings
List bookings by start and id, descending by default or ascending with order=asc.
- Operation id
listBookings- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.read_own - Assistant tool
- Yes. It only reads.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
status
|
query | string | no | |
host_id
|
query | string | no | Limits: pattern ^host_[0-9a-z]{26}$. |
event_type_id
|
query | string | no | Limits: pattern ^evt_[0-9a-z]{26}$. |
from
|
query | string | no | Limits: format date-time. |
to
|
query | string | no | Limits: format date-time. |
q
|
query | string | no | |
cursor
|
query | string | no | |
limit
|
query | string | no | |
order
|
query | string | no |
Values:
asc
,
desc
.
|
Answers
200 One page of bookings. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
bookings
|
array of BookingSummary | yes | |
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/bookings
Book a time the host offers, for a visitor. The same operation the booking page uses.
- Operation id
createBookingForVisitor- 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
- Required: send an Idempotency-Key header.
- Assistant tool
- Yes. The booking row keeps the retry key and the request's fingerprint (booking.client_request_id), so the same key never makes a second booking, even after the claim is forgotten.
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 |
|---|---|---|---|
event_type_id
|
string | yes | Limits: pattern ^evt_[0-9a-z]{26}$. |
host_id
|
string | no | Limits: pattern ^host_[0-9a-z]{26}$. |
start
|
string | yes | Limits: format date-time. |
invitee
|
object | yes | |
invitee.name
|
string | yes | |
invitee.email
|
string | yes | |
invitee.phone
|
string | no | |
invitee.time_zone
|
string | yes | |
invitee.locale
|
string | no | |
location_id
|
string | no | Limits: at least 1 character. |
location_value
|
string | no | |
answers
|
array of object | no | |
answers[]
|
object | yes | |
answers[].question_id
|
string | yes | Limits: at least 1 character. |
answers[].value
|
string or array of string | yes | |
guests
|
array of object | no | People the visitor invites besides themselves. They are invited on the calendar event and sent the booking's emails, without its cancel and reschedule links. At most the event type's max_guests; refused when it is 0. Limits: at most 10 items. |
guests[]
|
object | yes | |
guests[].email
|
string | yes | |
guests[].name
|
string | no | |
external_ref
|
string | no | Your own reference for this booking, such as a record id in your system. Stored on the booking and returned when it is read and in its webhook bodies. A hint only: it never finds, opens or authorizes anything, and two bookings may carry the same one. |
requested_by
|
string | no |
Your system's own reference to the person who asked for this booking there, such as a user id. Stored on the booking with your key or member as its issuer, and returned in the booking read, the export and every webhook body of the booking as requested_by. A hint, never authority: it is not who made the booking (created_by says that).
|
Answers
201 The booking is confirmed. 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)
|
Booking | yes |
202 The booking is still being confirmed. 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)
|
Booking | 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 cannot be done while something else depends on it. The same identifier was already used for a different request. This request is already running. Someone else got that time. |
conflict
,
id_conflict
,
request_in_progress
,
slot_taken
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 422 | The time is not offered. |
invalid_slot
|
| 429 | Too many attempts. |
rate_limited
|
| 503 | A system this account relies on did not answer. Try again in a moment. A calendar could not be reached. |
lookup_unavailable
,
provider_unavailable
|
GET
/v1/bookings/{booking_id}
Read one booking.
- Operation id
getBooking- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.read_own - Assistant tool
- Yes. It only reads.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
Answers
200 The booking. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
(whole body)
|
Booking | 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
|
GET
/v1/bookings/{booking_id}/timeline
What happened to one booking, oldest first.
- Operation id
getBookingTimeline- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.read_own - Assistant tool
- Yes. It only reads.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
Answers
200 Versions, emails and jobs, in order, and the routing form submission the booking was made through. For owners and admins, also how round-robin chose the host and the submission's answers. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
entries
|
array of object | yes | |
entries[]
|
one of 6 shapes | yes | |
entries[]{type=version}
|
object | yes | Shape 1 of 6, where type is version. |
entries[]{type=version}.type
|
string | yes |
Values:
version
.
|
entries[]{type=version}.id
|
string | yes | |
entries[]{type=version}.at
|
string | yes | Limits: format date-time. |
entries[]{type=version}.version
|
integer | yes | |
entries[]{type=version}.kind
|
string | yes |
Values:
create
,
reschedule
,
cancel
,
host_change
,
outcome
,
details
.
|
entries[]{type=version}.status
|
string | yes |
Values:
pending
,
confirmed
,
canceled
,
expired
.
|
entries[]{type=version}.start
|
string | yes | Limits: format date-time. |
entries[]{type=version}.end
|
string | yes | Limits: format date-time. |
entries[]{type=version}.actor
|
object | yes | |
entries[]{type=version}.actor.type
|
string | yes |
Values:
visitor
,
member
,
api_key
,
host
,
system
,
calendar
.
|
entries[]{type=version}.actor.id
|
string | no | |
entries[]{type=version}.moved_from
|
object | no | |
entries[]{type=version}.moved_from.start
|
string | yes | Limits: format date-time. |
entries[]{type=version}.moved_from.end
|
string | yes | Limits: format date-time. |
entries[]{type=version}.moved_to
|
object | no | |
entries[]{type=version}.moved_to.start
|
string | yes | Limits: format date-time. |
entries[]{type=version}.moved_to.end
|
string | yes | Limits: format date-time. |
entries[]{type=version}.host_from
|
string | no | |
entries[]{type=version}.host_to
|
string | no | |
entries[]{type=email}
|
object | yes | Shape 2 of 6, where type is email. |
entries[]{type=email}.type
|
string | yes |
Values:
email
.
|
entries[]{type=email}.id
|
string | yes | |
entries[]{type=email}.at
|
string | yes | Limits: format date-time. |
entries[]{type=email}.template
|
string | yes | |
entries[]{type=email}.recipient_role
|
string | yes |
Values:
invitee
,
guest
,
host
,
member
.
|
entries[]{type=email}.state
|
string | yes |
Values:
queued
,
sent
,
failed
,
postponed
.
|
entries[]{type=job}
|
object | yes | Shape 3 of 6, where type is job. |
entries[]{type=job}.type
|
string | yes |
Values:
job
.
|
entries[]{type=job}.id
|
string | yes | |
entries[]{type=job}.at
|
string | yes | Limits: format date-time. |
entries[]{type=job}.kind
|
string | yes |
Values:
outbox_dispatch
,
webhook_fanout
,
email_send
,
reminder
,
pending_expiry
,
calendar_cleanup
,
reservation_recovery
,
observation_retry
,
watch_renewal
,
full_sync
,
calendar_sync
,
calendar_event_check
,
calendar_reconcile
,
link_token_prune
,
invite_prune
,
idempotency_prune
,
retention_sweep
,
account_export
,
account_purge
,
suspension_release
,
member_removed_keys_notice
.
|
entries[]{type=job}.state
|
string | yes |
Values:
pending
,
running
,
done
,
failed
,
dead
,
canceled
,
held
.
|
entries[]{type=job}.attempts
|
integer | yes | |
entries[]{type=job}.last_error_code
|
string or null | yes | |
entries[]{type=round_robin}
|
object | yes | Shape 4 of 6, where type is round_robin. |
entries[]{type=round_robin}.type
|
string | yes |
Values:
round_robin
.
|
entries[]{type=round_robin}.id
|
string | yes | |
entries[]{type=round_robin}.at
|
string | yes | Limits: format date-time. |
entries[]{type=round_robin}.rules_version
|
integer | yes | |
entries[]{type=round_robin}.window_days
|
integer | yes | |
entries[]{type=round_robin}.start
|
string | yes | Limits: format date-time. |
entries[]{type=round_robin}.decided_by
|
string | yes |
Values:
only_candidate
,
priority
,
load
,
least_recent
,
tie_break
.
|
entries[]{type=round_robin}.status
|
string | yes |
Values:
pending
,
confirmed
,
given_up
.
|
entries[]{type=round_robin}.host_id
|
string or null | yes | |
entries[]{type=round_robin}.position
|
integer | yes | |
entries[]{type=round_robin}.refusals
|
integer | yes | |
entries[]{type=round_robin}.passed
|
array of object | yes | |
entries[]{type=round_robin}.passed[]
|
object | yes | |
entries[]{type=round_robin}.passed[].host_id
|
string | yes | |
entries[]{type=round_robin}.passed[].reason
|
string | yes |
Values:
claim_refused
,
unassigned
,
unknown
,
archived
,
inactive
,
paused
,
weight_zero
,
no_phone
,
no_calendar
,
at_limit
.
|
entries[]{type=round_robin}.settled_at
|
string or null | yes | Limits: format date-time. |
entries[]{type=round_robin}.candidates
|
array of object | yes | |
entries[]{type=round_robin}.candidates[]
|
object | yes | |
entries[]{type=round_robin}.candidates[].host_id
|
string | yes | |
entries[]{type=round_robin}.candidates[].rank
|
integer or null | yes | |
entries[]{type=round_robin}.candidates[].priority
|
integer or null | yes | |
entries[]{type=round_robin}.candidates[].weight
|
integer or null | yes | |
entries[]{type=round_robin}.candidates[].bookings_in_window
|
integer or null | yes | |
entries[]{type=round_robin}.candidates[].last_assigned_at
|
string or null | yes | Limits: format date-time. |
entries[]{type=round_robin}.candidates[].tie_break_key
|
string or null | yes | |
entries[]{type=round_robin}.candidates[].left_out
|
string or null | yes |
Values:
unknown
,
archived
,
inactive
,
paused
,
weight_zero
,
calendar_unknown
,
busy
,
no_hours
,
no_phone
,
no_calendar
,
at_limit
.
|
entries[]{type=round_robin}.candidates[].newcomer
|
boolean | yes | |
entries[]{type=round_robin}.candidates[].starting_load
|
object or null | yes | |
entries[]{type=round_robin}.candidates[].starting_load.bookings
|
integer | yes | |
entries[]{type=round_robin}.candidates[].starting_load.weight
|
integer | yes | |
entries[]{type=routing}
|
object | yes | Shape 5 of 6, where type is routing. |
entries[]{type=routing}.type
|
string | yes |
Values:
routing
.
|
entries[]{type=routing}.id
|
string | yes | |
entries[]{type=routing}.at
|
string | yes | Limits: format date-time. |
entries[]{type=routing}.routing_form_id
|
string | yes | |
entries[]{type=routing}.form_version
|
integer | yes | |
entries[]{type=routing}.matched_rule_id
|
string or null | yes | |
entries[]{type=routing}.answers
|
array of object | no | |
entries[]{type=routing}.answers[]
|
object | yes | |
entries[]{type=routing}.answers[].question_id
|
string | yes | |
entries[]{type=routing}.answers[].label
|
string | yes | |
entries[]{type=routing}.answers[].answer
|
string or array of string | yes | |
entries[]{type=report}
|
object | yes | Shape 6 of 6, where type is report. |
entries[]{type=report}.type
|
string | yes |
Values:
report
.
|
entries[]{type=report}.id
|
string | yes | |
entries[]{type=report}.at
|
string | yes | Limits: format date-time. |
entries[]{type=report}.system
|
string | yes | |
entries[]{type=report}.version
|
integer | yes | |
entries[]{type=report}.status
|
string | yes |
Values:
done
,
skipped
,
failed
.
|
entries[]{type=report}.error_code
|
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
|
| 404 | Nothing was found there. |
not_found
|
| 429 | Too many attempts. |
rate_limited
|
GET
/v1/bookings/{booking_id}/slots
Free times this booking can move to. Its own time does not block it.
- Operation id
listBookingSlots- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.read_own - Assistant tool
- Yes. It only reads.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
from
|
query | string | yes | Limits: format date-time. |
to
|
query | string | yes | Limits: format date-time. |
Answers
200 The free times. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
host_id
|
string or null | yes | The host whose times these are: the booking's own. Null when the list also holds the times of the event type's other pool hosts (a round-robin event type whose reschedule_host is any); a move to such a time goes to one of them. |
slots
|
array of object | yes | |
slots[]
|
object | yes | |
slots[].start
|
string | yes | Limits: format date-time. |
slots[].end
|
string | yes | Limits: format date-time. |
from
|
string | yes | Limits: format date-time. |
to
|
string | 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 was changed by someone else since it was read. |
version_conflict
|
| 429 | Too many attempts. |
rate_limited
|
| 503 | A calendar could not be reached. |
provider_unavailable
|
GET
/v1/event-types/{event_type_id}/slots
Free times of one event type, for booking on behalf of a visitor.
- Operation id
listEventTypeSlots- 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
- Yes. It only reads.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
event_type_id
|
path | string | yes | Limits: pattern ^evt_[0-9a-z]{26}$. |
from
|
query | string | yes | Limits: format date-time. |
to
|
query | string | yes | Limits: format date-time. |
host_id
|
query | string | no | Limits: pattern ^host_[0-9a-z]{26}$. |
Answers
200 The free times, and the range that was searched after clipping. application/json
| Field | Type | Always sent | Notes |
|---|---|---|---|
host_id
|
string | no | |
slots
|
array of object | yes | |
slots[]
|
object | yes | |
slots[].start
|
string | yes | Limits: format date-time. |
slots[].end
|
string | yes | Limits: format date-time. |
from
|
string | yes | Limits: format date-time. |
to
|
string | 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
|
| 429 | Too many attempts. |
rate_limited
|
| 503 | A calendar could not be reached. |
provider_unavailable
|
POST
/v1/bookings/{booking_id}/cancel
Cancel a booking. The same operation a visitor uses.
- Operation id
cancelBooking- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.manage_own - Retry key
- Required: send an Idempotency-Key header.
- Assistant tool
- Yes. It changes or removes something. It changes the booking only at the version the caller read; once the change is made the version has moved on, so a repeat is refused with version_conflict instead of acting twice.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
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 |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
reason
|
string | no |
Answers
200 The booking is canceled. 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)
|
Booking | 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 | 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
|
POST
/v1/bookings/{booking_id}/reschedule
Move a booking to a time the host offers. The same operation a visitor uses.
- Operation id
rescheduleBooking- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.manage_own - Retry key
- Required: send an Idempotency-Key header.
- Assistant tool
- Yes. It changes or removes something. It changes the booking only at the version the caller read; once the change is made the version has moved on, so a repeat is refused with version_conflict instead of acting twice.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
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 |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
start
|
string | yes | Limits: format date-time. |
Answers
200 The booking is at the new time. 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)
|
Booking | yes |
202 The move is still being finished. 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)
|
Booking | 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 | The same identifier was already used for a different request. This request is already running. Someone else got that time. This was changed by someone else since it was read. |
id_conflict
,
request_in_progress
,
slot_taken
,
version_conflict
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 422 | The time is not offered. |
invalid_slot
|
| 429 | Too many attempts. |
rate_limited
|
| 503 | A calendar could not be reached. |
provider_unavailable
|
POST
/v1/bookings/{booking_id}/outcome
Record whether the visitor attended.
- Operation id
setBookingOutcome- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.manage_own - Retry key
- Required: send an Idempotency-Key header.
- Assistant tool
- Yes. It changes or removes something. It changes the booking only at the version the caller read; once the change is made the version has moved on, so a repeat is refused with version_conflict instead of acting twice.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
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 |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
outcome
|
string | yes |
Answers
200 The booking, with the outcome stored. 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)
|
Booking | 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 | 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
|
POST
/v1/bookings/{booking_id}/reassign
Reassign a booking to another host, at the same time.
- Operation id
reassignBooking- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.manage - Retry key
- Required: send an Idempotency-Key header.
- Assistant tool
- Yes. It changes or removes something. It changes the booking only at the version the caller read; once the change is made the version has moved on, so a repeat is refused with version_conflict instead of acting twice.
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
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 |
|---|---|---|---|
version
|
integer | yes | Limits: at least 1. |
host_id
|
string | yes | Limits: pattern ^host_[0-9a-z]{26}$. |
Answers
200 The booking is with the new 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)
|
Booking | yes |
202 The reassignment is still being finished. 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)
|
Booking | 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. Someone else got that time. This was changed by someone else since it was read. |
id_conflict
,
request_in_progress
,
slot_taken
,
version_conflict
|
| 415 | Send the body as JSON. |
unsupported_media_type
|
| 429 | Too many attempts. |
rate_limited
|
| 503 | A calendar could not be reached. |
provider_unavailable
|
PUT
/v1/bookings/{booking_id}/reports/{system}
Report what your system did with one version of a booking: done, skipped or failed. Not a change to the booking: it writes no version and sends no event.
- Operation id
reportBooking- Who can call it
- Acts in one account, the one the credential belongs to.
- Credentials
- session or API key
- Permission
-
bookings.report - Retry key
- Optional: 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 |
|---|---|---|---|---|
booking_id
|
path | string | yes | Limits: pattern ^bkg_[0-9a-z]{26}$. |
system
|
path | string | yes |
The name your system reports as: a lower-case letter, then lower-case letters, digits, _ or -, 1 to 32 characters. The same name a webhook endpoint's report_system names, when the product should expect your reports.
|
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 |
|---|---|---|---|
version
|
integer | yes |
The booking version you acted on: the booking_version of the event you handled, from 1 to the booking's current version.
Limits: at least 1.
|
sequence
|
integer | yes | A number your system increases with every report it makes about this booking, across versions, such as its attempt counter or the attempt's time in milliseconds. Of two reports of one version, the one with the greater sequence is kept. Limits: at least 0. |
status
|
string | yes |
done: your system holds this version. skipped: it does not project this version, by design. failed: it tried and could not; send done with a greater sequence once a retry succeeds.
Values:
done
,
skipped
,
failed
.
|
error_code
|
string | no | A stable code from your system, 1 to 64 letters, digits, _, :, . or -. Never a message: a message can quote the visitor. Left out, the report stores none. |
external_id
|
string | no | Your system's id for its record of this meeting. Personal data about the visitor: kept with the visitor's data and removed with it; a report for a booking whose visitor data is already removed stores none. |
Answers
200 The report the booking now holds for your system, and whether this one is it. A report of an earlier version or a smaller sequence than the stored one is answered with applied: false and changes nothing.
application/json
-
Header
Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
| Field | Type | Always sent | Notes |
|---|---|---|---|
booking_id
|
string | yes | |
applied
|
boolean | yes | True when this report is what the booking now holds for your system (also for an exact repeat). False when a report of a later version, or a greater sequence, was already there: nothing changed. |
report
|
object | yes | The report the booking holds for your system now. |
report.system
|
string | yes | |
report.version
|
integer | yes | |
report.sequence
|
integer | yes | |
report.status
|
string | yes |
Values:
done
,
skipped
,
failed
.
|
report.error_code
|
string or null | yes | |
report.external_id
|
string or null | yes | Null when none was given, and once the visitor's data is removed. |
report.failing_since
|
string or null | yes |
While status is failed: when this run of failed reports began. Repeated failures keep it.
Limits: format date-time.
|
report.reported_by
|
object | yes | |
report.reported_by.type
|
string | yes |
Values:
member
,
api_key
.
|
report.reported_by.id
|
string | yes | |
report.reported_at
|
string | yes | Limits: format date-time. |
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
|