# Book an event

> **POST** `https://api.us.nylas.com/v3/scheduling/bookings`

Source: https://developer.nylas.com/docs/reference/api/bookings/post-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.

**Authentication:** SCHEDULER_SESSION_TOKEN

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `timezone` | string | No | The timezone to use for the booking. If not provided, Nylas uses the timezone from the Configuration object. |
| `configuration_id` | string | No | The ID of the Configuration object whose settings are used for calculating availability. If you're using session authentication (`requires_session_auth` is set to `true`), `configuration_id` is not required. |
| `slug` | string | No | The slug of the Configuration object. You can use this with the `client_id` instead of using the `configuration_id`. If you're using session authentication (`requires_session_auth` is set to `true`) or using the `configuration_id`, `slug` is not required. |
| `client_id` | string | No | The client ID that was used to create the Configuration object. `client_id` is required only if you're using `slug`. |

## Request body

Content-Type: application/json

- `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` (array) - 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` (string) - The language of the guest email notifications.
- `additional_guests` (array) - 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.

## Responses

### 200 - Create a new booking

- `request_id` (string) - The request ID.
- `data` (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` (string) **(required)** - The current status of the booking.
  - `description` (string) - The description of the event.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 404 - Not Found

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The raw error from the provider, if available
    - `code` (string)
    - `message` (string)

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 504 - Provider Failure

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL (Public)

```bash
curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/scheduling/bookings?configuration_id=<SCHEDULER_CONFIG_ID>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": 1709643600,
    "end_time": 1709645400,
    "participants": [],
    "guest": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  }'
```

### cURL (Private)

```bash
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": "jane.doe@example.com"
    }
  }'
```

### Node.js SDK (Public)

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function createBooking() {
  try {
    const booking = await nylas.scheduler.bookings.create({
      queryParams: {
        configurationId: "<SCHEDULER_CONFIG_ID>",
      },
      requestBody: {
        startTime: 1763119800,
        endTime: 1763121600,
        guest: {
          name: "Jane Doe",
          email: "jane.doe@example.com",
        },
      },
    });
    console.log("Created Booking", booking);
  } catch (error) {
    console.error("Error creating booking", error);
  }
}
createBooking();

```

### Python SDK

```python
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>",
)

booking = nylas.scheduler.bookings.create(
    request_body={
        "start_time": 1763119800,
        "end_time": 1763121600,
        "guest": {
            "name": "Jane Doe",
            "email": "jane.doe@example.com",
        },
    },
    query_params={
        "configuration_id": "<SCHEDULER_CONFIG_ID>",
    },
)

print("Created booking:", booking)

```

### Node.js SDK (Private)

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function createBooking() {
  try {
    const booking = await nylas.scheduler.bookings.create({
      requestBody: {
        startTime: 1763119800,
        endTime: 1763121600,
        guest: {
          name: "Jane Doe",
          email: "jane.doe@example.com",
        },
      },
    });
    console.log("Created Booking", booking);
  } catch (error) {
    console.error("Error creating booking", error);
  }
}
createBooking();

```

### Ruby SDK (Public)

```ruby
# Load gems
require 'nylas'

# Initialize Nylas client
nylas = Nylas::Client.new(
  api_key: "<NYLAS_API_KEY>"
)

request_body = {
  "start_time": 1709643600,
  "end_time": 1709645400,
  "participants": [],
  "guest": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  }
}

booking, _request_ids = nylas.scheduler.bookings.create(request_body: request_body, query_params: { configuration_id: "<SCHEDULER_CONFIG_ID>" })

puts booking
```

### Ruby SDK (Private)

```ruby
# Load gems
require 'nylas'

# Initialize Nylas client
nylas = Nylas::Client.new(
  api_key: "<SCHEDULER_SESSION_ID>"
)

request_body = {
  "start_time": 1709643600,
  "end_time": 1709645400,
  "participants": [],
  "guest": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  }
}

booking, _request_ids = nylas.scheduler.bookings.create(request_body: request_body)

puts booking
```

### Java SDK (Public)

```java
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.BookingGuest;
import com.nylas.models.CreateBookingQueryParams;
import com.nylas.models.CreateBookingRequest;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;

public class CreateBookingPublic {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    BookingGuest guest = new BookingGuest("jane.doe@example.com", "Jane Doe");

    CreateBookingRequest requestBody = new CreateBookingRequest.Builder()
        .startTime("1763119800")
        .endTime("1763121600")
        .guest(guest)
        .build();

    // Public Configuration objects need the configuration ID as a query parameter.
    CreateBookingQueryParams queryParams = new CreateBookingQueryParams.Builder()
        .configurationId("<SCHEDULER_CONFIG_ID>")
        .build();

    Response<Booking> booking = nylas.scheduler().bookings().create(requestBody, queryParams);

    System.out.println("Created booking: " + booking.getData());
  }
}

```

### Java SDK (Private)

```java
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.BookingGuest;
import com.nylas.models.CreateBookingRequest;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;

public class CreateBooking {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    // Use a Scheduler session ID as the API key for session-authenticated bookings.
    NylasClient nylas = new NylasClient.Builder("<SCHEDULER_SESSION_ID>").build();

    BookingGuest guest = new BookingGuest("jane.doe@example.com", "Jane Doe");

    CreateBookingRequest requestBody = new CreateBookingRequest.Builder()
        .startTime("1763119800")
        .endTime("1763121600")
        .guest(guest)
        .build();

    Response<Booking> booking = nylas.scheduler().bookings().create(requestBody);

    System.out.println("Created booking: " + booking.getData());
  }
}

```

### Kotlin SDK (Public)

```kotlin
import com.nylas.NylasClient
import com.nylas.models.BookingGuest
import com.nylas.models.CreateBookingQueryParams
import com.nylas.models.CreateBookingRequest

fun main() {
  val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()

  val guest = BookingGuest(email = "jane.doe@example.com", name = "Jane Doe")

  val requestBody = CreateBookingRequest.Builder()
      .startTime("1763119800")
      .endTime("1763121600")
      .guest(guest)
      .build()

  // Public Configuration objects need the configuration ID as a query parameter.
  val queryParams = CreateBookingQueryParams.Builder()
      .configurationId("<SCHEDULER_CONFIG_ID>")
      .build()

  val booking = nylas.scheduler().bookings().create(requestBody, queryParams)

  println("Created booking: ${booking.data}")
}

```

### Kotlin SDK (Private)

```kotlin
import com.nylas.NylasClient
import com.nylas.models.BookingGuest
import com.nylas.models.CreateBookingRequest

fun main() {
  // Use a Scheduler session ID as the API key for session-authenticated bookings.
  val nylas = NylasClient.Builder("<SCHEDULER_SESSION_ID>").build()

  val guest = BookingGuest(email = "jane.doe@example.com", name = "Jane Doe")

  val requestBody = CreateBookingRequest.Builder()
      .startTime("1763119800")
      .endTime("1763121600")
      .guest(guest)
      .build()

  val booking = nylas.scheduler().bookings().create(requestBody)

  println("Created booking: ${booking.data}")
}

```