# Bookings

Source: https://developer.nylas.com/docs/reference/api/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](/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</br>`https://www.googleapis.com/auth/...` | Microsoft Scopes</br>`https://graph.microsoft.com/...` |
| :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **POST** `/scheduling/bookings`</br>**DELETE** `/scheduling/bookings/<BOOKING_ID>`</br>**PATCH** `/scheduling/bookings/<BOOKING_ID>` | `/calendar.events` ☑️</br>`/calendar`                   | `Calendars.ReadWrite` ☑️                               |

For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).


## Endpoints

- **POST** `/v3/scheduling/bookings` - [Book an event](https://developer.nylas.com/docs/reference/api/bookings/post-bookings/)
- **GET** `/v3/scheduling/bookings/{booking_id}` - [Return a booking](https://developer.nylas.com/docs/reference/api/bookings/get-bookings-id/)
- **PUT** `/v3/scheduling/bookings/{booking_id}` - [Confirm a booking](https://developer.nylas.com/docs/reference/api/bookings/put-bookings-id/)
- **PATCH** `/v3/scheduling/bookings/{booking_id}` - [Reschedule a booking](https://developer.nylas.com/docs/reference/api/bookings/patch-bookings-id/)
- **DELETE** `/v3/scheduling/bookings/{booking_id}` - [Delete a booking](https://developer.nylas.com/docs/reference/api/bookings/delete-bookings-id/)