Version:
Only show these results:

Virtual calendar availability in Nylas v2

This page describes how to use the Availability endpoints with virtual calendars. While Nylas currently doesn't directly support availability or consecutive availability for virtual calendars, you can still use virtual calendars for booking meetings and checking for a free time.

Get a list of events

First, make a GET /events request that includes the expand_recurring and busy parameters. This ensures that Nylas fetches all events in a series, and events where the calendar is confirmed as busy.

curl --request GET \
  --url 'https://api.nylas.com/events?expand_recurring=true&busy=true' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_ACCESS_TOKEN>' \

Convert events to Time Slots

As part of the JSON response, Nylas returns the times for each event in its when object, as in the following example.

[{
  "account_id": "1wkrvki9owclp1k6d5t239d6x",
  "busy": true,
  "calendar_id": "5u8xdd75azkoemrhzjhlllt0t",
  "description": null,
  "ical_uid": "492fde66ba2444b9b4804c75c7617cb9@example.com",
  "id": "eyd8ioauo5ojugofckz50j6h8",
  "location": "Yoga Studio 5 Westlake",
  "message_id": null,
  "object": "event",
  "owner": "Virtual Calendar <virtual_account_unique_id>",
  "participants": [{
    "comment": null,
    "email": "kat.j@example.com",
    "name": "Katherine Johnson",
    "phone_number": null,
    "status": "noreply"
  }],
  "read_only": false,
  "reminders": null,
  "status": "confirmed",
  "title": "Good Flow Yoga",
  "when": {
    "end_time": 1628539200,
    "object": "timespan",
    "start_time": 1628535600
  }
}]

You can use the start_time and end_time values to convert events to time_slots. Nylas uses Time Slots as part of the free_busy object in the /calendars/availability endpoint. The result is similar to the example below.

"time_slots": [{
  "start_time": 1628535600,
  "end_time": 1628539200,
  "object": "time_slot",
  "status": "busy"
}]

Pass Time Slots to Availability endpoint

Finally, pass the Time Slots from the previous step to the /calendars/availability endpoint in the free_busy object.

curl --request POST \
  --url https://api.nylas.com/calendars/availability \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_ACCESS_TOKEN>' \
  --data-raw '{
    "duration_minutes": 30,
    "start_time": 1628535600,
    "end_time": 1628539200,
    "interval_minutes": 10,
    "emails": [
      "<email@example.com>"
    ],
    "free_busy": [{
      "email": "My virtual calendar",
      "object": "free/busy",
      "time_slots": [{
        "start_time": 1628535600,
        "end_time": 1628539200,
        "object": "time_slot",
        "status": "busy"
      }]
    }]
  }'

Nylas returns a JSON response that contains available time slots for both the virtual calendar and any email addresses that you pass in.