Only show these results:

Check free/busy information

📝 This page discusses both Nylas v2.x and v3. For more information about the newest version, see the Nylas v3 documentation.

Nylas offers multiple ways to get information about your 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 (API v3 and API v2), which returns simple information about blocks of time on an end user's primary calendar when they are booked and not available.

ℹ️ Free/Busy Status is available for Entry, Core, and Plus plans.

How the Free/Busy endpoint works

When you make a request to the Free/Busy endpoint (API v3 and API v2), 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 that's on their calendar (for example, an event that's automatically added from an email invitation), providers handle it differently. Google marks the 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 for a user outside of your organization, they must have published or made their calendar's free/busy information public.

A calendar UI displaying the simple busy data returned by the free/busy endpoint.

If the end user is fully booked (there are no available time slots on their calendar), Nylas returns an empty time_slots array, as in the code snippet below.

[{
"email": "[email protected]",
"object": "free_busy",
"time_slots": []
}]

Nylas recommends you use the Free/Busy endpoint when you need to know the times an end user's calendar is booked. If you need to do any of the following tasks, Nylas recommends you use the Availability endpoint (API v3 and API v2) instead:

  • Compare end users' schedules.
  • Get Free/Busy information for Virtual Calendars.
  • Check the status of room resources.

You can use the Free/Busy endpoint to check the calendars of multiple users in the same call, but Nylas returns their individual busy data and does not compare or combine it.

🔍 Nylas returns a Free-Busy object when you make requests to the v2 Availability endpoint. You can use this object to manually add busy data for users outside of your organization. The object does not call the Free/Busy endpoint — it's just named free_busy because the data represents the same information, in the same format.

Request busy data for one user

The following code snippets are examples of POST requests to fetch a single end user's busy data, and the responses Nylas returns.

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_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1682467200,
"end_time": 1682550000,
"emails": ["[email protected]"]
}'
curl --request POST \
--url https://api.nylas.com/calendars/free-busy \
--header 'Authorization: Bearer <NYLAS_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": "1409594400",
"end_time": "1409598000",
"emails": [
"string"
],
"calendars": [
{
"account_id": "3aols9hb9fkqtso7zkzcmwgwv",
"calendar_ids": [
"string"
]
}
]
}'
[{
"email": "[email protected]",
"object": "free_busy",
"calendar_id": "string",
"time_slots": [
{
"end_time": 1600907400,
"object": "time_slot",
"start_time": 1600890568,
"status": "busy"
},
{
"end_time": 1600984800,
"object": "time_slot",
"start_time": 1600979400,
"status": "busy"
}
]
}]

Request busy data for multiple users

The following code snippets are examples of requests for multiple end users' busy data, and the responses Nylas returns. You can use these requests 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/<GRANT_ID>/calendars/free-busy \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1682467200,
"end_time": 1682550000,
"emails": [
"[email protected]",
"[email protected]",
"[email protected]"
]
}'
{
"request_id": "dd3ec9a2-8f15-403d-b269-32b1f1beb9f5",
"data": [
{
"email": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"error": "Unable to resolve e-mail address [email protected] to an Active Directory object.",
"object": "error"
}
]
}
curl --request POST \
--url https://api.nylas.com/calendars/free-busy \
--header 'Authorization: Bearer <NYLAS_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": "1633374000",
"end_time": "1633381200",
"emails": [],
"calendars": [
{
"account_id": "exampleaccountid1",
"calendar_ids": [
"examplecalendaridA",
"examplecalendaridB"
]
},
{
"account_id": "exampleaccountid2",
"calendar_ids": [
"examplecalendaridC",
]
}
]
}'
[
{
"calendar_id": "examplecalendaridA",
"email": "[email protected]",
"object": "free_busy",
"time_slots": [{
"end_time": 1633379400,
"object": "time_slot",
"start_time": 1633377600,
"status": "busy"
}]
},
{
"calendar_id": "examplecalendaridB",
"email": "[email protected]",
"object": "free_busy",
"time_slots": [
{
"end_time": 1633374900,
"object": "time_slot",
"start_time": 1633371300,
"status": "busy"
},
{
"end_time": 1633383900,
"object": "time_slot",
"start_time": 1633380300,
"status": "busy"
}
]
},
{
"calendar_id": "examplecalendaridC",
"email": "[email protected]",
"object": "free_busy",
"time_slots": [
{
"end_time": 1633377600,
"object": "time_slot",
"start_time": 1633374000,
"status": "busy"
},
{
"end_time": 1633377600,
"object": "time_slot",
"start_time": 1633374000,
"status": "busy"
}
]
}
]