Skip to content
Docs

Bookings

Booking, viewing, rescheduling and cancelling an individual booking are public: the invitee proves ownership with the manageToken returned when the booking is created, sent as the token query parameter. Listing bookings needs an API key.

Keep the manageToken. It is returned once, at booking time, and is the only way an invitee can later move or cancel the booking. Calling reschedule or cancel with an API key instead of a token acts on the host's behalf. Rescheduling accepts either a new start, or a sessionId to move a seat in a group session.

Possible conflicts: slot_unavailable (the slot was taken, so fetch slots again), invalid_slot (not an offered start), already_booked, booking_not_active and booking_in_past. Booking events can also be delivered as webhooks.

POST /public/:handle/:slug/bookings

Book a slot. Auth: none.

Path parameters

FieldTypeRequiredDefault / limits
handlestringyes-
slugstringyes-

Request body

FieldTypeRequiredDefault / limits
startstring (date-time)yes-
inviteeNamestringyes1–100 chars
inviteeEmailstring (email)yes-
inviteeTimezonestringyesmin 1 chars

Response 201

Body

FieldTypeRequiredDefault / limits
bookingobjectyes-
booking.idstring (uuid)yes-
booking.eventTypeIdstring (uuid)yes-
booking.hostIdstring (uuid)yes-
booking.inviteeNamestringyes-
booking.inviteeEmailstring (email)yes-
booking.inviteeTimezonestringyes-
booking.startAtstring (date-time)yes-
booking.endAtstring (date-time)yes-
booking.status"confirmed" | "cancelled"yes-
booking.cancelReasonstring | nullyes-
booking.rescheduledFromIdstring (uuid) | nullyes-
booking.sessionIdstring (uuid)no-
booking.createdAtstring (date-time)yes-
manageTokenstringyes-
brandingbooleanyes-
demobooleanno-

Errors: invalid_request, not_found, slot_unavailable, invalid_slot, event_type_inactive, already_booked, rate_limited

curl -X POST "https://devalender.com/api/public/<handle>/<slug>/bookings" \
  -H "Content-Type: application/json" \
  -d '{"start":"2030-01-07T10:00:00Z","inviteeName":"string","inviteeEmail":"[email protected]","inviteeTimezone":"string"}'

GET /bookings/:id/manage

View a booking with its manage token. Auth: none.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Query parameters

FieldTypeRequiredDefault / limits
tokenstringyesmin 1 chars

Response 200

Body

FieldTypeRequiredDefault / limits
bookingobjectyes-
booking.idstring (uuid)yes-
booking.eventTypeIdstring (uuid)yes-
booking.hostIdstring (uuid)yes-
booking.inviteeNamestringyes-
booking.inviteeEmailstring (email)yes-
booking.inviteeTimezonestringyes-
booking.startAtstring (date-time)yes-
booking.endAtstring (date-time)yes-
booking.status"confirmed" | "cancelled"yes-
booking.cancelReasonstring | nullyes-
booking.rescheduledFromIdstring (uuid) | nullyes-
booking.sessionIdstring (uuid)no-
booking.createdAtstring (date-time)yes-
brandingbooleanyes-
demobooleanno-
eventTypeobjectyes-
eventType.slugstringyes-
eventType.titlestringyes-
eventType.durationMinutesintegeryes-9007199254740991–9007199254740991
eventType.locationKind"url" | "phone" | "in_person" | "custom"yes-
eventType.locationValuestringyes-
hostobjectyes-
host.handlestringyes-
host.displayNamestringyes-
host.timezonestringyes-
teamobjectno-
team.slugstringno-
team.namestringno-

Errors: not_found

curl -X GET "https://devalender.com/api/bookings/<id>/manage?token=string"

POST /bookings/:id/reschedule

Move a booking to another slot. Auth: none.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Query parameters

FieldTypeRequiredDefault / limits
tokenstringyesmin 1 chars

Request body

Option 1

FieldTypeRequiredDefault / limits
startstring (date-time)yes-

Option 2

FieldTypeRequiredDefault / limits
sessionIdstring (uuid)yes-

Response 200

Body

Option 1

FieldTypeRequiredDefault / limits
bookingobjectyes-
booking.idstring (uuid)yes-
booking.eventTypeIdstring (uuid)yes-
booking.hostIdstring (uuid)yes-
booking.inviteeNamestringyes-
booking.inviteeEmailstring (email)yes-
booking.inviteeTimezonestringyes-
booking.startAtstring (date-time)yes-
booking.endAtstring (date-time)yes-
booking.status"confirmed" | "cancelled"yes-
booking.cancelReasonstring | nullyes-
booking.rescheduledFromIdstring (uuid) | nullyes-
booking.sessionIdstring (uuid)no-
booking.createdAtstring (date-time)yes-
manageTokenstringyes-
brandingbooleanyes-

Option 2

FieldTypeRequiredDefault / limits
bookingobjectyes-
booking.idstring (uuid)yes-
booking.eventTypeIdstring (uuid)yes-
booking.hostIdstring (uuid)yes-
booking.inviteeNamestringyes-
booking.inviteeEmailstring (email)yes-
booking.inviteeTimezonestringyes-
booking.startAtstring (date-time)yes-
booking.endAtstring (date-time)yes-
booking.status"confirmed" | "cancelled"yes-
booking.cancelReasonstring | nullyes-
booking.rescheduledFromIdstring (uuid) | nullyes-
booking.sessionIdstring (uuid)no-
booking.createdAtstring (date-time)yes-

Errors: seat_not_reschedulable, invalid_request, not_found, slot_unavailable, invalid_slot, event_type_inactive, already_booked

curl -X POST "https://devalender.com/api/bookings/<id>/reschedule?token=string" \
  -H "Content-Type: application/json" \
  -d '{"start":"2030-01-07T10:00:00Z"}'

POST /bookings/:id/cancel

Cancel a booking. Auth: none.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Query parameters

FieldTypeRequiredDefault / limits
tokenstringyesmin 1 chars

Request body

FieldTypeRequiredDefault / limits
reasonstringnomax 500 chars

Response 200

Body

FieldTypeRequiredDefault / limits
bookingobjectyes-
booking.idstring (uuid)yes-
booking.eventTypeIdstring (uuid)yes-
booking.hostIdstring (uuid)yes-
booking.inviteeNamestringyes-
booking.inviteeEmailstring (email)yes-
booking.inviteeTimezonestringyes-
booking.startAtstring (date-time)yes-
booking.endAtstring (date-time)yes-
booking.status"confirmed" | "cancelled"yes-
booking.cancelReasonstring | nullyes-
booking.rescheduledFromIdstring (uuid) | nullyes-
booking.sessionIdstring (uuid)no-
booking.createdAtstring (date-time)yes-

Errors: invalid_request, not_found, booking_not_active, booking_in_past

curl -X POST "https://devalender.com/api/bookings/<id>/cancel?token=string" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string"}'

GET /bookings

List bookings, oldest first by default. Auth: API key.

Query parameters

FieldTypeRequiredDefault / limits
fromstring (date-time)no-
tostring (date-time)no-
status"confirmed" | "cancelled"no-
order"asc" | "desc"nodefault "asc"
limitintegernodefault 50; 1–200
cursorstringnomin 1 chars

Response 200

Body

FieldTypeRequiredDefault / limits
itemsobject[]yes-
items[].idstring (uuid)yes-
items[].eventTypeIdstring (uuid)yes-
items[].hostIdstring (uuid)yes-
items[].inviteeNamestringyes-
items[].inviteeEmailstring (email)yes-
items[].inviteeTimezonestringyes-
items[].startAtstring (date-time)yes-
items[].endAtstring (date-time)yes-
items[].status"confirmed" | "cancelled"yes-
items[].cancelReasonstring | nullyes-
items[].rescheduledFromIdstring (uuid) | nullyes-
items[].sessionIdstring (uuid)no-
items[].createdAtstring (date-time)yes-
nextCursorstring | nullyes-

Errors: invalid_request, unauthorized

curl -X GET "https://devalender.com/api/bookings" \
  -H "Authorization: Bearer dvl_..."

GET /bookings/:id

Get one booking. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Response 200

Body

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
eventTypeIdstring (uuid)yes-
hostIdstring (uuid)yes-
inviteeNamestringyes-
inviteeEmailstring (email)yes-
inviteeTimezonestringyes-
startAtstring (date-time)yes-
endAtstring (date-time)yes-
status"confirmed" | "cancelled"yes-
cancelReasonstring | nullyes-
rescheduledFromIdstring (uuid) | nullyes-
sessionIdstring (uuid)no-
createdAtstring (date-time)yes-

Errors: unauthorized, not_found

curl -X GET "https://devalender.com/api/bookings/<id>" \
  -H "Authorization: Bearer dvl_..."