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

Optional
  • 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