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.
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.
curl --compressed --request POST \ --url 'https://api.us.nylas.com/v3/scheduling/bookings' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \ --header 'Content-Type: application/json' \ --data '{ "start_time": 1709643600, "end_time": 1709645400, "participants": [], "guest": { "name": "Jane Doe", "email": "[email protected]" } }'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”- Create a Scheduler booking config to define the page bookings run against
- Scheduler overview for the full bookings reference
- Retrieve booking IDs to link bookings to calendar events
- Get real-time updates with webhooks for booking.created and booking.cancelled events