You need to schedule a conference room, a rental, or a piece of equipment, but none of those has an email account to connect. Booking them against a real user’s calendar gets messy fast, and you don’t want a fake mailbox just to hold availability.
Virtual calendars solve this. A virtual calendar is a Nylas-hosted calendar that isn’t tied to any provider account, so you can create, book, and free-up time on a resource using the same Events API you already use for people.
What’s a virtual calendar?
Section titled “What’s a virtual calendar?”A virtual calendar is a calendar Nylas hosts directly, with no connected provider behind it. It’s built for entities that need a schedule but have no mailbox: meeting rooms, equipment, or service providers. Each virtual account shows up in your dashboard as a grant whose provider is “Virtual calendar”, and you drive it with the same event endpoints you use for the other 4 providers.
How do I create a virtual calendar?
Section titled “How do I create a virtual calendar?”Setting up a virtual calendar takes 2 requests. First, create a virtual calendar connector for your application, then create a virtual account against it, which returns a grant. The first virtual calendar you create for that account automatically becomes its primary calendar, which you can reference with the primary keyword instead of a calendar ID.
The request below creates the virtual calendar connector your application needs once.
curl --request POST \ --url "https://api.us.nylas.com/v3/connectors" \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --data '{ "provider": "virtual-calendar" }'After the connector exists, create a virtual account to get a grant ID, then use the standard Events API to add bookings.
Things to know about virtual calendars
Section titled “Things to know about virtual calendars”A few rules are specific to virtual calendars. The first calendar on a virtual account is permanently the primary: you can’t change which one is primary, and you can’t delete it, so plan that first calendar carefully. After setup, everything is standard, so the 4 providers’ event behaviors don’t apply and you avoid their quirks entirely.
Each virtual account can hold up to 10 virtual calendars, and the accounts never expire, so there’s no grant.expired handling to build. Because there’s no real provider, there are no OAuth scopes or provider rate limits to manage, just your API key. For the complete connector and account flow, see virtual calendars.
What’s next
Section titled “What’s next”- Virtual calendars reference for the full connector and account setup
- Create Google events using the same Events API on a virtual calendar
- Find open meeting times across calendars to check resource availability
- Create and list calendars to manage calendars on the virtual account