Skip to content
Skip to main content

Create, reschedule, and cancel bookings

Last updated:

A booking page is only half the job. Once a configuration exists, your app has to actually create bookings when someone picks a slot, and then handle the reschedules and cancellations that follow. Doing that against each provider’s calendar by hand is exactly what Scheduler avoids.

The Nylas bookings API manages that lifecycle through one resource. You create a booking against a configuration, then reschedule, confirm, or cancel it with calls keyed on the booking ID. The Scheduler booking diagram shows how the Configuration, Availability, and Bookings endpoints fit together.

How a Scheduler booking works

Every booking surface uses the same Configuration and the same Availability and Bookings endpoints. Collective configurations need every participant free, and round-robin configurations (max-fairness, max-availability) assign one host per booking.
Diagram as text
  • Your app: Create a Configuration: In the Dashboard (Scheduler) or with POST /v3/grants/{grant_id}/scheduling/configurations. Sets participants, open hours, and booking rules.
  • One of these paths (Guest opens a booking page):
    • Nylas-hosted page
      • Hosted Scheduling Page: Nylas hosts the page. No frontend code needed.
    • Embedded component
      • Scheduling component: <nylas-scheduling> embedded in your app, as HTML or React.
    • Your UI + API
      • Your own booking UI: Calls the Availability and Bookings endpoints directly.
  • Nylas: Calculate open slots: Checks participant calendars within open hours, applying buffers and minimum notice. (GET /v3/scheduling/availability)
  • Nylas: Re-check the slot and book: Confirms the selected slot is still free before booking. (POST /v3/scheduling/bookings)
    • Slot no longer free → Booking rejected: Returns an error. Nothing is created.
  • Provider: Event on organizer's calendar: Created in the organizer's booking.calendar_id, with conferencing if configured. (Slot still free)
    • If Notetaker is enabled → Notetaker joins: Joins the meeting to record and transcribe. Needs conferencing.
  • Nylas: Confirmations and webhook: Emails attendees unless disable_emails is set, and sends booking.created.

How do I create a booking?

Section titled “How do I create a booking?”

Send a POST /v3/scheduling/bookings request referencing the configuration_id from your Scheduler configuration, along with the chosen start_time, end_time, and the guest’s details. Both times must match a valid availability slot. Nylas books the slot on the organizer’s calendar and returns a booking_id. The slot length comes from the configuration, so a config set to 30 minutes produces a 30 minute event.

How do I reschedule, confirm, or cancel a booking?

Section titled “How do I reschedule, confirm, or cancel a booking?”

The booking ID gives you 3 lifecycle actions on /v3/scheduling/bookings/{booking_id}: PATCH reschedules it to a new time, PUT confirms or cancels a pending booking, and DELETE deletes it. Each updates or cancels the event on the organizer’s provider calendar across all 4 providers, so a cancellation removes the event in one call.

Use PATCH when a guest moves their slot and DELETE when they drop out, rather than editing the underlying calendar event directly, so Scheduler keeps its own state consistent.

Things to know about bookings

Section titled “Things to know about bookings”

Bookings flow through the configuration, so their behavior follows what you set there. A booking lands on the organizer’s calendar across all 4 providers, and the meeting length and conferencing come from the configuration rather than the booking call, which keeps every booking against a page consistent. Pending bookings wait for a PUT confirmation when your flow requires approval.

To map booking IDs back to calendar events, see retrieve booking IDs. The booking lifecycle also emits the booking.created, booking.rescheduled, and booking.cancelled webhooks, 3 of the 5 booking triggers you can subscribe to (the others are booking.pending and booking.reminder).

What’s next

Section titled “What’s next”