Check free/busy information in Nylas v2

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 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 Free, Entry, Core, and Plus plans.

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 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.

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": "jane.doe@example.com",
  "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 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 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.

Request
Response (JSON)

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": "jane.doe@example.com",
  "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.

Request
Response (JSON)

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": "account1@example.com",
    "object": "free_busy",
    "time_slots": [{
      "end_time": 1633379400,
      "object": "time_slot",
      "start_time": 1633377600,
      "status": "busy"
    }]
  },
  {
    "calendar_id": "examplecalendaridB",
    "email": "account1@example.com",
    "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": "account2@example.com",
    "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"
      }
    ]
  }
]