Using the Scheduler API
This feature is a private preview release and should be used with caution. It may contain bugs, and its features and implementation will likely change before it is generally available.
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 a scheduling session. You can create a configuration object by making a POST /v3/scheduling/configurations request, as in the example below. The response includes the ID of the configuration object, which Nylas uses to associate the object with the session.
curl --request POST \
--url "https://api.us.nylas.com/v3/scheduling/configurations" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json'
--data '{
"version": "1.0.0",
"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",
"version": "1.0.0",
"participants": [
{
"name": "Nylas",
"email": "[email protected]",
"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. When you create a session, you must 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.
The response includes the ID of the session.
curl --request POST \
--url "https://api.us.nylas.com/v3/scheduling/sessions" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \
--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.
📝 Note: The response only includes the order property for round-robin events.
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 <SESSION_ID>' \
--header 'Content-Type: application/json' {
"request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
"data": {
"order": [
"[email protected]",
"[email protected]"
],
"time_slots": [
{
"emails": [
"[email protected]",
"[email protected]"
],
"start_time": 1659367800,
"end_time": 1659369600
},
{
"emails": [
"[email protected]"
],
"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.
📝 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.
curl --request GET \
--url 'https://api.us.nylas.com/v3/scheduling/bookings' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SESSION_ID>' \
--header 'Content-Type: application/json'
--data '{
"start_time": 1709643600,
"end_time": 1709645400,
"participants": [],
"guest": {
"name": "Jane Doe",
"email": "[email protected]"
}
}' {
"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.
The following code samples show a PATCH /v3/scheduling/bookings/<BOOKING_ID> request that updates the scheduled time for the booking.
curl --request PATCH \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SESSION_ID>' \
--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.
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SESSION_ID>' \
--header 'Content-Type: application/json' {
"request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90"
}