Using the Scheduler API

This page explains how to use the v3 Nylas Scheduler API. You'll learn how to do the following tasks:

Create a Configuration object.
Create a session.
Get availability.
Create a booking.
Manage existing bookings.

Before you begin

To follow along with the samples on this page, you first need to sign up for a Nylas developer account, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account's data.

Create a Configuration object

The Configuration object defines the settings and preferences for an event. You can create a Configuration object by making a POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations request, as in the example below.

By default, Nylas creates a public configuration that doesn't require a session. To create a private configuration, set requires_session_auth to true.

The response includes the ID of the Configuration object, which Nylas uses to associate the object with the session.

Request
Response (JSON)

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "requires_session_auth": false,
    "participants": [
      {
        "name": "Test",
        "email": "nylas_test_8",
        "is_organizer": true,
        "availability": {
          "calendar_ids": [
            "primary"
          ]
        },
        "booking": {
          "calendar_id": "primary"
        }
      }
    ],
    "availability": {
      "duration_minutes": 30
    },
    "event_booking": {
      "title": "My test event"
    }
  }'

{
  "ID": "AAAA-BBBB-1111-2222",
  "participants": [
    {
      "name": "Nylas",
      "email": "nylas@example.com",
      "is_organizer": true,
      "availability": {
        "calendar_ids": [
          "primary"
      ]},
      "booking": {
        "calendar_id": "primary"
  }}],
  "availability": {
    "duration_minutes": 30
  },
  "event_booking": {
    "title": "My test event"
  }
}

Create a session

Next, create a session token by making a POST /v3/scheduling/sessions request, and include the Configuration object ID that you generated in the previous step. Nylas recommends you set a Time-to-Live (TTL) value for each session, and refresh the sessions as they expire.

If you created a public configuration, no session is required.

The response includes the ID of the session.

Request
Response (JSON)

curl --request POST \
  --url "https://api.us.nylas.com/v3/scheduling/sessions" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "configuration_id": "AAAA-BBBB-1111-2222",
    "time_to_live": 10
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "session_id": "XXXX-YYYY-1111-2222"
  }
}

Get availability

Now that you have a Configuration object and a session, you can get available time slots for a set of end users based on the availability rules you defined in the Configuration object. The /v3/scheduling/availability endpoint validates the provided 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 must pass the Configuration object ID as a query parameter.

📝 Note: The response only includes the order property for round-robin events.

Request: Private configuration
Request: Public configuration
Response (JSON)

curl --request GET \
  --url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
  --header 'Content-Type: application/json'

curl --request GET \
  --url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200&configuration_id=<SCHEDULER_CONFIG_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
  --header 'Content-Type: application/json'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "order": [
      "user1@example.com",
      "user2@example.com"
    ],
    "time_slots": [
      {
        "emails": [
          "user2@example.com",
          "user1@example.com"
        ],
        "start_time": 1659367800,
        "end_time": 1659369600
      },
      {
        "emails": [
          "user1@example.com"
        ],
        "start_time": 1659376800,
        "end_time": 1659378600
      }
    ]
  }
}

Create a booking

When you have availability information, you can book an event with the participants and details you defined in the Configuration object. The /v3/scheduling/bookings endpoint validates the provided 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 must pass the Configuration object ID as a query parameter.

📝 Note: The start_time and end_time values must correspond to a valid time slot returned by the /v3/scheduling/availability endpoint that uses the same Configuration object.

The response includes the booking ID.

Request: Private configuration
Request: Public configuration
Response (JSON)

curl --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'

curl --request GET \
  --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"
    }
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "booking_id": "AAAA-XXXX-1111-2222"
  }
}

Manage existing bookings

When you have the booking ID, you can reschedule or delete an existing booking. Rescheduling and deleting bookings affects the events created on the provider's side. For example, if you reschedule a booking, Scheduler also updates the associated event on the provider.

If you created a public configuration, you don't need to include the Authorization request header with a session ID, but you must pass the Configuration object ID as a query parameter.

The following code samples show a PATCH /scheduling/bookings/<BOOKING_ID> request that updates the scheduled time for the booking.

Request: Private configuration
Request: Public configuration
Response (JSON)

curl --request PATCH \
  --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
  --header 'Content-Type: application/json' \ 
  --data '{
    "start_time": 1708714800,
    "end_time": 1708722000
  }'

curl --request PATCH \
  --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": 1708714800,
    "end_time": 1708722000
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88"
}

The following DELETE /v3/scheduling/bookings/<BOOKING_ID> request deletes an existing booking using its ID.

Request: Private configuration
Request: Public configuration
Response (JSON)

curl --request DELETE \
  --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
  --header 'Content-Type: application/json'

curl --request DELETE \
  --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90"
}