Check free/busy information
The Nylas APIs offer multiple ways to get information about end users' availability, so you can book meetings or run other time-based operations. The simplest way to do so is using the Free/Busy endpoint, which returns simple information about blocks of time when they're booked on their primary calendar and not available.
How the Free/Busy endpoint works
When you make a request to the Free/Busy endpoint, Nylas returns a simple list of time slots during which the end user's primary calendar is booked, and they're not available.
When an end user hasn't accepted an event on their calendar (for example, an event that's automatically added from an email invitation), providers handle it differently. Google marks that calendar as busy during that time span, while Microsoft marks it as free.
If you're querying a user within your organization, free/busy information is usually public. If you're querying a user outside of your organization, they must have published or made their calendar's free/busy information public.
If the end user is fully booked (there are no available time slots on their calendar), Nylas returns an empty time_slots array.
[{
"email": "jane.doe@example.com",
"object": "free_busy",
"time_slots": []
}] Nylas recommends you use the Free/Busy endpoint when you need to know the times when an end user's calendar is booked. If you need to do any of the following tasks, Nylas recommends you use the Availability endpoint instead:
- Compare end users' schedules.
- Check the status of room resources.
For more information, see Check calendar availability.
You can use the Free/Busy endpoint to check multiple end users' calendars in the same call, but Nylas returns their individual busy data and does not compare or combine it.
Request busy data for a user
The following code snippet fetches a single end user's busy data.
curl --request POST \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1682467200,
"end_time": 1682550000,
"emails": ["aristotle@example.com"]
}' Request busy data for multiple users
The following example fetches busy data for multiple end users and shows the type of response you can expect from Nylas. You can use this request to view shared time slots for individuals using different providers, across multiple accounts and calendars.
curl --request POST \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1682467200,
"end_time": 1682550000,
"emails": [
"aristotle@example.com",
"nyla@example.com",
"jane@example.com"
]
}' {
"request_id": "dd3ec9a2-8f15-403d-b269-32b1f1beb9f5",
"data": [
{
"email": "aristotle@example.com",
"time_slots": [
{
"start_time": 1690898400,
"end_time": 1690902000,
"status": "busy",
"object": "time_slot"
},
{
"start_time": 1691064000,
"end_time": 1691067600,
"status": "busy",
"object": "time_slot"
}
],
"object": "free_busy"
},
{
"email": "nyla@example.com",
"time_slots": [
{
"start_time": 1690898400,
"end_time": 1690902000,
"status": "busy",
"object": "time_slot"
},
{
"start_time": 1691064000,
"end_time": 1691067600,
"status": "busy",
"object": "time_slot"
}
],
"object": "free_busy"
},
{
"email": "jane@example.com",
"error": "Unable to resolve e-mail address jane@example.com to an Active Directory object.",
"object": "error"
}
]
}