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
| Field | Type | Required | Default / limits |
|---|---|---|---|
handle | string | yes | - |
slug | string | yes | - |
Request body
| Field | Type | Required | Default / limits |
|---|---|---|---|
start | string (date-time) | yes | - |
inviteeName | string | yes | 1–100 chars |
inviteeEmail | string (email) | yes | - |
inviteeTimezone | string | yes | min 1 chars |
Response 201
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
booking | object | yes | - |
booking.id | string (uuid) | yes | - |
booking.eventTypeId | string (uuid) | yes | - |
booking.hostId | string (uuid) | yes | - |
booking.inviteeName | string | yes | - |
booking.inviteeEmail | string (email) | yes | - |
booking.inviteeTimezone | string | yes | - |
booking.startAt | string (date-time) | yes | - |
booking.endAt | string (date-time) | yes | - |
booking.status | "confirmed" | "cancelled" | yes | - |
booking.cancelReason | string | null | yes | - |
booking.rescheduledFromId | string (uuid) | null | yes | - |
booking.sessionId | string (uuid) | no | - |
booking.createdAt | string (date-time) | yes | - |
manageToken | string | yes | - |
branding | boolean | yes | - |
demo | boolean | no | - |
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
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string | yes | - |
Query parameters
| Field | Type | Required | Default / limits |
|---|---|---|---|
token | string | yes | min 1 chars |
Response 200
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
booking | object | yes | - |
booking.id | string (uuid) | yes | - |
booking.eventTypeId | string (uuid) | yes | - |
booking.hostId | string (uuid) | yes | - |
booking.inviteeName | string | yes | - |
booking.inviteeEmail | string (email) | yes | - |
booking.inviteeTimezone | string | yes | - |
booking.startAt | string (date-time) | yes | - |
booking.endAt | string (date-time) | yes | - |
booking.status | "confirmed" | "cancelled" | yes | - |
booking.cancelReason | string | null | yes | - |
booking.rescheduledFromId | string (uuid) | null | yes | - |
booking.sessionId | string (uuid) | no | - |
booking.createdAt | string (date-time) | yes | - |
branding | boolean | yes | - |
demo | boolean | no | - |
eventType | object | yes | - |
eventType.slug | string | yes | - |
eventType.title | string | yes | - |
eventType.durationMinutes | integer | yes | -9007199254740991–9007199254740991 |
eventType.locationKind | "url" | "phone" | "in_person" | "custom" | yes | - |
eventType.locationValue | string | yes | - |
host | object | yes | - |
host.handle | string | yes | - |
host.displayName | string | yes | - |
host.timezone | string | yes | - |
team | object | no | - |
team.slug | string | no | - |
team.name | string | no | - |
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
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string | yes | - |
Query parameters
| Field | Type | Required | Default / limits |
|---|---|---|---|
token | string | yes | min 1 chars |
Request body
Option 1
| Field | Type | Required | Default / limits |
|---|---|---|---|
start | string (date-time) | yes | - |
Option 2
| Field | Type | Required | Default / limits |
|---|---|---|---|
sessionId | string (uuid) | yes | - |
Response 200
Body
Option 1
| Field | Type | Required | Default / limits |
|---|---|---|---|
booking | object | yes | - |
booking.id | string (uuid) | yes | - |
booking.eventTypeId | string (uuid) | yes | - |
booking.hostId | string (uuid) | yes | - |
booking.inviteeName | string | yes | - |
booking.inviteeEmail | string (email) | yes | - |
booking.inviteeTimezone | string | yes | - |
booking.startAt | string (date-time) | yes | - |
booking.endAt | string (date-time) | yes | - |
booking.status | "confirmed" | "cancelled" | yes | - |
booking.cancelReason | string | null | yes | - |
booking.rescheduledFromId | string (uuid) | null | yes | - |
booking.sessionId | string (uuid) | no | - |
booking.createdAt | string (date-time) | yes | - |
manageToken | string | yes | - |
branding | boolean | yes | - |
Option 2
| Field | Type | Required | Default / limits |
|---|---|---|---|
booking | object | yes | - |
booking.id | string (uuid) | yes | - |
booking.eventTypeId | string (uuid) | yes | - |
booking.hostId | string (uuid) | yes | - |
booking.inviteeName | string | yes | - |
booking.inviteeEmail | string (email) | yes | - |
booking.inviteeTimezone | string | yes | - |
booking.startAt | string (date-time) | yes | - |
booking.endAt | string (date-time) | yes | - |
booking.status | "confirmed" | "cancelled" | yes | - |
booking.cancelReason | string | null | yes | - |
booking.rescheduledFromId | string (uuid) | null | yes | - |
booking.sessionId | string (uuid) | no | - |
booking.createdAt | string (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
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string | yes | - |
Query parameters
| Field | Type | Required | Default / limits |
|---|---|---|---|
token | string | yes | min 1 chars |
Request body
| Field | Type | Required | Default / limits |
|---|---|---|---|
reason | string | no | max 500 chars |
Response 200
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
booking | object | yes | - |
booking.id | string (uuid) | yes | - |
booking.eventTypeId | string (uuid) | yes | - |
booking.hostId | string (uuid) | yes | - |
booking.inviteeName | string | yes | - |
booking.inviteeEmail | string (email) | yes | - |
booking.inviteeTimezone | string | yes | - |
booking.startAt | string (date-time) | yes | - |
booking.endAt | string (date-time) | yes | - |
booking.status | "confirmed" | "cancelled" | yes | - |
booking.cancelReason | string | null | yes | - |
booking.rescheduledFromId | string (uuid) | null | yes | - |
booking.sessionId | string (uuid) | no | - |
booking.createdAt | string (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
| Field | Type | Required | Default / limits |
|---|---|---|---|
from | string (date-time) | no | - |
to | string (date-time) | no | - |
status | "confirmed" | "cancelled" | no | - |
order | "asc" | "desc" | no | default "asc" |
limit | integer | no | default 50; 1–200 |
cursor | string | no | min 1 chars |
Response 200
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
items | object[] | yes | - |
items[].id | string (uuid) | yes | - |
items[].eventTypeId | string (uuid) | yes | - |
items[].hostId | string (uuid) | yes | - |
items[].inviteeName | string | yes | - |
items[].inviteeEmail | string (email) | yes | - |
items[].inviteeTimezone | string | yes | - |
items[].startAt | string (date-time) | yes | - |
items[].endAt | string (date-time) | yes | - |
items[].status | "confirmed" | "cancelled" | yes | - |
items[].cancelReason | string | null | yes | - |
items[].rescheduledFromId | string (uuid) | null | yes | - |
items[].sessionId | string (uuid) | no | - |
items[].createdAt | string (date-time) | yes | - |
nextCursor | string | null | yes | - |
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
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string | yes | - |
Response 200
Body
| Field | Type | Required | Default / limits |
|---|---|---|---|
id | string (uuid) | yes | - |
eventTypeId | string (uuid) | yes | - |
hostId | string (uuid) | yes | - |
inviteeName | string | yes | - |
inviteeEmail | string (email) | yes | - |
inviteeTimezone | string | yes | - |
startAt | string (date-time) | yes | - |
endAt | string (date-time) | yes | - |
status | "confirmed" | "cancelled" | yes | - |
cancelReason | string | null | yes | - |
rescheduledFromId | string (uuid) | null | yes | - |
sessionId | string (uuid) | no | - |
createdAt | string (date-time) | yes | - |
Errors: unauthorized, not_found
curl -X GET "https://devalender.com/api/bookings/<id>" \
-H "Authorization: Bearer dvl_..."