---
title: "Book an event"
method: POST
path: "/v3/scheduling/bookings"
tags: ["Bookings"]
---

# Book an event

`POST /v3/scheduling/bookings`

Books an event with the participants listed in the session's
[Configuration object](/docs/reference/api/configurations/), using the details from the
Configuration. The `start_time` and `end_time` must correspond to a valid time slot returned by
the
[Scheduling Availability endpoint](/docs/reference/api/availability/get-availability/)
using the same Configuration.

Nylas validates the session ID and uses it to retrieve the related Configuration object. If you
created a public Configuration, you don't need to include the `Authorization` request header with
a session ID, but you do need to pass the Configuration object ID as a query parameter.

## Request body

- BookingCreate
  - `start_time` integer, required — The event's start time, in seconds using the Unix timestamp format.
  - `end_time` integer, required — The event's end time, in seconds using the Unix timestamp format.
  - `participants` object[] — An array of objects that include a list of participant email addresses from the Configuration object to include in the booking. If not provided, Nylas includes all participants from the Configuration object.
    - `email` string — The participant's email address.
  - `guest` object, required — Details about the guest that is creating the booking. The guest `name` and `email` are required.
    - `email` string — The guest's email address.
    - `name` string — The guest's name.
  - `timezone` string — The guest's timezone, used in email notifications. If not provided, Nylas uses the timezone from the [Configuration object](/docs/reference/api/configurations/).
  - `email_language` 'en' | 'fr' | 'de' | 'es' | 'nl' | 'sv' | 'ja' | 'zh' — The language of the guest email notifications.
  - `additional_guests` object[] — An array of objects that include a list of additional guest email addresses to include in the booking.
    - `email` string — The additional guest's email address.
    - `name` string — The additional guest's name.
  - `additional_fields` object — A dictionary of additional field keys mapped to the values populated by the guest in the booking form.

## Response `200`

Create a new booking

- object
  - `request_id` string — The request ID.
  - `data` object — The response object.
    - `booking_id` string, required — The unique ID of the booking.
    - `event_id` string, required — The unique ID of the event object associated with the booking.
    - `title` string, required — The title of the event.
    - `organizer` object, required — The participant that is designated as the organizer of the event.
      - `email` string — The organizer's email address.
      - `name` string — The organizer's name.
    - `status` 'booked' | 'pending' | 'cancelled', required — The current status of the booking.
    - `description` string — The description of the event.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `429` — Rate Limit
- `504` — Provider Failure

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)