Nylas Bookings API

Nylas Scheduler uses the `/v3/scheduling/bookings` endpoint to manage bookings. Bookings work the same way when the organizer is an [Agent Account](/docs/v3/scheduler/agent-accounts/): the event is created on the Agent Account's primary calendar, and the confirmation, reschedule, cancellation, and reminder email all send from the Agent Account's own address. Each of those messages counts against the account's [daily send quota](/docs/v3/agent-accounts/send-limits/#sending-limits). ## 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](/docs/reference/api/bookings/put-bookings-id/) 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](/docs/reference/api/bookings/post-bookings/). 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. | Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` | | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- | | **POST** `/scheduling/bookings`**DELETE** `/scheduling/bookings/`**PATCH** `/scheduling/bookings/` | `/calendar.events` ☑️`/calendar` | `Calendars.ReadWrite` ☑️ | For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).