Bookings (cal-api-version: 2024-08-13): create, list with filters and take/skip paging, get, confirm, decline, cancel, reschedule, and mark absences (no-shows).
Context Vars
cal-com.api.key
Values
DEFAULT_PAGE_SIZE
DEFAULT_PAGE_SIZE: Int 100
Functions
build-absent-body
fn (host: Bool?, absent-emails: Vec): Map
Build the mark-absent body: host (Bool, optional) and attendees as
[{email, absent}] from a list of absent attendee emails. Unset parts
are omitted. Exposed for testing.
Example
::cal-com::bookings/build-absent-body(true, ["ada@example.com"]) // {host: true, attendees: [{email: "ada@example.com", absent: true}]}
::cal-com::bookings/build-absent-body(null, []) // {}
build-list-query
fn (options: Map): Str
Build the GET /bookings query string. options takes the API's own
filter names: status (Str or Vec of "upcoming", "recurring",
"past", "cancelled", "unconfirmed"), attendeeEmail,
attendeeName, eventTypeId, eventTypeIds (Vec), afterStart,
beforeEnd, afterCreatedAt, beforeCreatedAt, afterUpdatedAt,
beforeUpdatedAt (ISO 8601), sortStart/sortEnd/sortCreated
("asc"/"desc"), take and skip. Nulls are dropped and Vecs are
comma-joined. Exposed for testing.
Example
::cal-com::bookings/build-list-query({take: 50, attendeeName: null}) // "?take=50"
cancel-booking
fn (uid: Str, reason: Str): Any
fn (uid: Str, options: Map): Any
fn (uid: Str, options: Map, opts: Map): Any
POST /bookings/{uid}/cancel - Cancel a booking. The 2-arity form
takes a reason; the Map form takes the API's body: cancellationReason,
cancelSubsequentBookings (recurring), or seatUid (cancel one seat
of a seated booking).
Example
::cal-com::bookings/cancel-booking(::cal-com::usersID, "The customer asked to cancel.")
// One seat of a seated booking
::cal-com::bookings/cancel-booking(::cal-com::usersID, {seatUid: "seat_1"})
collect-pages
fn (fetch: Fn, options: Map, skip: Int, limit: Int, acc: Vec): Vec
Collect take/skip pages from fetch (a Fn taking the options Map,
returning a {data, pagination} envelope) until limit items, an
empty page, or pagination.hasNextPage false. Each request asks for
at most the remaining count. Exposed for testing; list-all-bookings
uses it.
Example
::cal-com::bookings/collect-pages((options) { {data: [1, 2], pagination: {hasNextPage: false}} }, {}, 0, 10, []) // [1, 2]
::cal-com::bookings/collect-pages((options) { {data: [1, 2], pagination: {hasNextPage: true}} }, {}, 0, 1, []) // [1]
confirm-booking
fn (uid: Str): Any
fn (uid: Str, opts: Map): Any
POST /bookings/{uid}/confirm - Confirm a booking that is waiting for approval (event types that require confirmation). Must be called by the booking's owner.
Example
::cal-com::bookings/confirm-booking(::cal-com::usersID)
create-booking
fn (booking: Map): Any
fn (booking: Map, opts: Map): Any
POST /bookings - Book a slot. booking: start (UTC ISO 8601 from
get-slots), attendee ({name, email, timeZone, phoneNumber?, language?}), and either eventTypeId or eventTypeSlug with
username/teamSlug. Optional: guests (emails), metadata,
bookingFieldsResponses, lengthInMinutes, location. Booking a
recurring event type takes recurrenceCount. Unset fields are
omitted.
Example
::cal-com::bookings/create-booking({
eventTypeId: 123,
start: "2026-07-10T15:00:00Z",
attendee: {name: "Ada Lovelace", email: "ada@example.com", timeZone: "America/Chicago"}
})
decline-booking
fn (uid: Str): Any
fn (uid: Str, opts: Map): Any
fn (uid: Str, reason: Str): Any
fn (uid: Str, reason: Str, opts: Map): Any
POST /bookings/{uid}/decline - Decline a booking that is waiting for
approval, optionally with a reason the attendee sees.
Example
::cal-com::bookings/decline-booking(::cal-com::usersID, "Outside our service area.")
get-booking
fn (uid: Str): Any
fn (uid: Str, opts: Map): Any
GET /bookings/{uid} - One booking by uid.
Example
booking ::cal-com::bookings/get-booking(::cal-com::usersID)
booking.status
list-all-bookings
fn (options: Map, limit: Int): Vec
fn (options: Map, limit: Int, opts: Map): Vec
Collect bookings across pages (take/skip) until limit bookings or
the last page. options takes the same filters as list-bookings
(any take/skip in it are overridden). Returns a Vec of bookings.
Example
past ::cal-com::bookings/list-all-bookings({status: "past", afterStart: "2026-06-01T00:00:00Z"}, 500)
list-bookings
fn (): Any
fn (options: Map): Any
fn (options: Map, opts: Map): Any
GET /bookings - One page of the API key owner's bookings. Returns
the envelope {status, data, pagination}; pagination carries
totalItems, remainingItems, hasNextPage and friends. Page with
take (default 100) and skip. See build-list-query for filters,
or list-all-bookings to collect several pages.
Example
page ::cal-com::bookings/list-bookings({status: ["upcoming", "unconfirmed"], afterStart: "2026-07-01T00:00:00Z", take: 50})
page.data
page.pagination.hasNextPage
mark-absent
fn (uid: Str, absent-emails: Vec): Any
fn (uid: Str, body: Map): Any
fn (uid: Str, body: Map, opts: Map): Any
POST /bookings/{uid}/mark-absent - Record no-shows after a meeting.
The Map form takes the API's body directly: host (Bool) and
attendees ([{email, absent}], absent: false to undo). The
2-arity form marks the listed attendee emails absent. Must be called
by the booking's owner.
Example
::cal-com::bookings/mark-absent("bk_abc123", ["ada@example.com"])
::cal-com::bookings/mark-absent("bk_abc123", {host: true})
reschedule-booking
fn (uid: Str, new-start: Str): Any
fn (uid: Str, new-start: Str, options: Map): Any
fn (uid: Str, new-start: Str, options: Map, opts: Map): Any
POST /bookings/{uid}/reschedule - Move a booking to a new start
(UTC ISO 8601). options: reschedulingReason, rescheduledBy
(email), seatUid (seated bookings). Returns the new booking; the old
uid is cancelled.
Example
moved ::cal-com::bookings/reschedule-booking(::cal-com::usersID, "2026-07-11T15:00:00Z", {reschedulingReason: "Conflict on the original day."})
moved.uid