Bookings

Nylas Scheduler uses the /v3/scheduling/bookings endpoint to manage bookings.

Booking types

Nylas Scheduler supports two booking types, booking and organizer-confirmation.

booking represents a regular booking flow. When the booking type is organizer-confirmation, Nylas creates an event marked "Pending" in the organizer's calendar. It then sends an confirmation request email to the organizer, which includes a link to a page where the organizer can confirm or cancel the booking.

Finalizing pending bookings

The PUT /v3/scheduling/bookings/{booking_id} request allows the organizer to confirm or cancel a pending booking.

Booking flow

The Scheduling Component provides information about the selected time slot, and any additional information that the user added, to the /v3/scheduling/bookings endpoint. The Bookings endpoint performs the following tasks:

1. Validates the provided session ID and uses it to retrieve the related Configuration object.
2. Confirms if the selected time slot is still available.
3. Retrieves the booking participant's grant_id, using the list of participants' email addresses in the Configuration object.
4. Creates an event.
   If the booking type is set to organizer-confirmation, a placeholder event is created in the organizer's calendar.
5. Creates a booking entry in the database and maps the provider's event ID and Scheduler's booking_id. If the booking type is set to organizer-confirmation, a booking entry with the pending status is created. The booking entry includes the placeholder event's booking_id and the additional_fields data provided in the request.
6. Nylas creates a booking reference based on the configuration ID and the booking ID. You can use the booking reference to reschedule and cancel the event.
7. (Optional) Emits a booking (booking.created) or a pending booking (booking.pending) webhook, depending on the booking type.

Bookings scopes

The table below lists the Bookings endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.

For more information about scopes, see Using scopes to request user data.