Using virtual calendars in Nylas v2

This page describes how to authenticate a virtual account and virtual calendar, and how to add an event to your new calendar.

Before you begin

Before you can create a virtual calendar, you need the following prerequisites:

A Nylas account.
A Nylas application.
Your Nylas application's client ID and secret.

Keep in mind

Virtual calendars use Native auth only.
Virtual calendars can interact with the Account, Calendar, and Events endpoints only.
Each virtual account can have only one virtual calendar.

Authenticate a virtual account

Before you can create a virtual calendar, you need a virtual account to represent its "owner". Virtual accounts use Native auth. You can use the same auth process each time you need to create a virtual account for a virtual calendar.

Follow the steps below to authenticate a Connected Account for your new virtual calendar in Nylas v2:

Make a Send Authorization request to start the authentication process.
```
curl --location --request POST 'https://api.nylas.com/connect/authorize' \
  --data-raw '{
    "client_id": "9df4ff17888f4729ad4e1463d2547d",
    "provider": "nylas",
    "scopes": "calendar",
    "email": "virtual_account_unique_id",
    "name": "Virtual Calendar",
    "settings": {}
  }'   
```
- client_id: The client ID of your Nylas application.
- provider: The calendar's provider. For virtual calendars, this is always nylas.
- scopes: The scopes that the calendar is granted. Virtual calendars have the calendar scope only.
- email: A unique string representing the calendar's email address in requests to the Calendar and Events endpoints.
  
  ⚠️ The email field is a unique identifier for the virtual calendar. It can be anything as long as it's a unique string. Nylas recommends you do not use an existing email address for this field.
- name: The name of the virtual calendar.
- settings: When making a POST request, this field is required, but is always passed as an empty object.
Nylas returns a JSON code that you use in the next step.
```
{
  "code": "HYL7zY1M1LpJ8iKAYKsx7RM1Wchz4b"
}   
```

Make an Exchange Token request that includes the code that Nylas returns in the previous step.

curl --location --request POST '<https://api.nylas.com/connect/token>' \
  --data-raw '{
    "client_id": "9df4ff17888f4729ad4e1463d2547d",
    "client_secret": "dcc0bb54d8ae4c1ab95dc76694084b",
    "code": "HYL7zY1M1LpJ8iKAYKsx7RM1Wchz4b"
  }'

client_id: Your Nylas application's client ID.
client_secret: Your Nylas application's client secret.
code: The code response from the previous step.

Nylas returns a JSON response that includes the virtual account's access_token. You need this to authorize the Connected Account for API requests.

{
  "access_token": "938134d41cf0465590b1cf0de1decd",
  "account_id": "dc41c2a1ce6840deba3cd41468fb75",
  "billing_state": "paid",
  "email_address": "virtual_account_unique_id",
  "id": "d38b60fb69ee40b3a11fa686c83987",
  "linked_at": 1598290473,
  "name": "Virtual Calendar Test",
  "object": "account",
  "organization_unit": "folder",
  "provider": "nylas",
  "sync_state": "running"
}

The virtual account is created. It's displayed as its own entry in the Nylas Dashboard.

Create a virtual calendar

Now that you have a virtual account in Nylas, you can create a virtual calendar for the Connected Account or grant.

The steps below show how to create a virtual calendar in Nylas v2.

🔍 The following API requests use the Bearer authorization method. Be sure to pass the access token that you received when authenticating the virtual account.

Make a POST /calendars request that includes the virtual account's <ACCESS_TOKEN>.
```
curl --location --request POST 'https://api.nylas.com/calendars' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --data-raw '{
    "name":"Marie Radiation Services",
    "description":"Keep track of important customer appointments",
    "location":"Warsaw, Poland",
    "timezone":"Europe/Warsaw"
  }'   
```
- name: The name of the calendar.
- description: A brief description of the calendar.
- location: A string representing the geographic location of the calendar.
- timezone: An IANA-formatted string (for example, America/New_York) representing the time zone of the calendar. If blank, no time zone is assigned to the calendar.

Nylas returns a JSON response that includes the virtual calendar's id. This is required to add events to it.

{
  "account_id": "dc41c2a1ce6840deba3cd41468fb75",
  "description": "Keep track of important customer appointments",
  "id": "ac1046f1dd1746d6a979b53c973c56",
  "is_primary": null,
  "location": "Warsaw, Poland",
  "name": "Marie Radiation Services",
  "object": "calendar",
  "read_only": false,
  "timezone": "Europe/Warsaw"
}

The virtual calendar is created and associated with your virtual account.

Create an event on a virtual calendar

Now that you have both a virtual account and a virtual calendar associated with it, you can start creating events.

⚠️ Virtual calendars do not send invitations to event participants. To send invites for events on virtual calendars, use the Generate ICS endpoint.

The following steps show how to add an event to a virtual calendar in Nylas v2.

Make a POST /events request that includes the virtual account's <ACCESS_TOKEN> and the virtual calendar's calendar_id.
```
curl --location --request POST 'https://api.nylas.com/events' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --data-raw '{
    "title":"Good Flow Yoga",
    "when": {
      "start_time": 1598281200,
      "end_time": 1598284800
    },
    "location": "Yoga Studio 5 Westlake",
    "calendar_id": "ac1046f1dd1746d6a979b53c973c56",
    "participants": [{
      "email": "[email protected]",
      "name": "Katherine Johnson"
    }]
  }'   
```
- title: The title of the event.
- when: The event's start and end times. These times are represented as a Unix timestamp.
- location: The location of the event (for example, a physical address or the name of a meeting room).
- calendar_id: The ID of the virtual calendar.
- participants: An array of objects representing the event's participants. Each object must include the person's name and email address.

Nylas returns the new event as a JSON object.

{
  "account_id": "dc41c2a1ce6840deba3cd41468fb75",
  "busy": true,
  "calendar_id": "ac1046f1dd1746d6a979b53c973c56",
  "description": null,
  "ical_uid": null,
  "id": "dc41c2a1ce6840deba3cd41468fb75",
  "location": "Yoga Studio 5 Westlake",
  "message_id": null,
  "object": "event",
  "owner": "Virtual Calendar Test <virtual_calendar_email>",
  "participants": [{
    "comment": null,
    "email": "[email protected]",
    "name": "Katherine Johnson",
    "status": "noreply"
  }],
  "read_only": false,
  "status": "confirmed",
  "title": "Good Flow Yoga",
  "when": {
    "end_time": 1598284800,
    "object": "timespan",
    "start_time": 1598281200
  }
}

The event is created and added to the virtual calendar.