Edit

Share via

Outlook calendar API overview

  • Article

Outlook calendar is part of the Outlook messaging hub in Microsoft 365 that also lets you manage emails and contacts, find information about users in an organization, initiate online conversations, share files, and collaborate in groups.

Why integrate with Outlook calendar?

The rich features of Outlook calendar and its API open up many app opportunities. The following sections list a few of them.

Reach hundreds of millions of customers and build rich scenarios

Many millions of customers use Outlook calendar as part of an integrated hub that lets them effectively communicate and get things done. They can set up meetings, manage emails, find information about contacts and other users, and initiate conversations or online meetings all in one place, be it on the web, mobile, or desktop. Microsoft Graph not only connects apps to the calendar, mail, and contacts data of these customers, it enables apps to integrate with the best of Microsoft 365 and support a wide range of scenarios that enhance productivity and collaboration.

Most features in the Outlook calendar API apply to calendars in personal Microsoft accounts and work or school accounts.

** Denotes features below that are specifically applicable to Outlook calendars in only work or school accounts.

Automate appointment organization and calendaring

Customers like how Outlook lets them organize their time for work, family, and personal activities. Microsoft Graph REST API keeps close parity with the customer experience, letting apps create, manage, and respond to events just as naturally:

  • In Outlook, customers can create individual calendars for work, family, and other purposes, and organize them in calendar groups. They can turn on the free Birthdays and Holiday calendar to remind them of contacts' birthdays and local holidays. They can add calendars that match their interests, such as calendars for sport teams and TV programs. Customers can select and overlay calendars, and see their events in the same view. Through the calendar API, your app can similarly organize calendars in calendar groups, and interact with interesting calendars just like any other calendar in the user's mailbox.

  • Outlook customers can apply categories to events, messages, contacts, tasks, and group posts in a consistent way to enhance organization and discovery. The calendar API lets you access and define a user's master list of categories, which opens up additional creative scenarios. For example, an athletic club can organize a sports tournament and offer an app that differentiates emails and events for each sport with their own color category. For last-minute news such as unforeseen timetable changes, the app can also set the importance property of those events and emails to alert customers.

  • In a calendar folder, you can create and update single instance events, or schedule and maintain recurring events. You can let your customers respond to meeting requests, and snooze or dismiss reminders using the associated event navigation property.

Help customers stay synchronized and navigate their day

The calendar API helps customers navigate their day and enhance productivity:

Enhance collaboration

  • In Outlook, customers can share calendars with one another and give permissions to read, write, or delete calendar contents. Or, they can delegate a calendar to let another customer respond to meeting requests on their behalf. Programmatically, while you cannot initiate a share or delegate action on behalf of a user, you can use a set of properties to verify the sharing status and enable scenarios around shared or delegated calendars: canEdit, canShare, canViewPrivateItems, isShared, and isSharedWithMe.
  • The calendar API lets you get calendar items of the signed-in user, or users who have shared or delegated their calendars to the signed-in user. For example, if Garth has shared a calendar with John, or if Garth has delegated access to John, then delegated permissions from John would give you read access to Garth's shared calendar and contents as well.
  • Microsoft 365 groups make it convenient for group members to collaborate and access group conversations and calendars right in Outlook. Aside from a few minor differences between group calendars and user calendars, the calendar API lets you interact with group calendars just like user calendars. See the calendar resource for more information**.

Schedule smart

Outlook and the calendar API offer many smart conveniences to schedule events:

  • Through Outlook calendar app settings, customers can enable automatic adding of events from emails, such as flight, hotel, or dining reservations, and billing invoices. Once added, you can interact with these events just like any other event objects in the user's mailbox, and build creative scenarios upon this Outlook capability.
  • In Outlook, booking a meeting room is as straight-forward as adding an attendee to the event. The calendar API represents a meeting room as an emailAddress object. You can get rooms and get room lists that are available in a tenant. To organize a meeting in a specific room, assign it to the location property of the event.**
  • You can look up the free/busy information for users and resources for a specific time period. You can then use this data to apply to different scenarios including resource planning and event scheduling.**
  • If your scenario involves scheduling meetings at an optimal time, you can consider using findMeetingTimes to identify possible times or locations to meet. The findMeetingTimes function considers the free/busy status of the attendees, and any preferred rooms, time, and other constraints you provide. If the first try doesn't return a common meeting time, check the reason, adjust your criteria and call findMeetingTimes again.**

Teleconference across multiple locations and time zones

With globalization, today's business meetings often involve attendees participating from different locations and time zones. Here's how you can use the calendar API to manage such meetings:

  • As an example in Outlook, customers can organize a meeting and include attendees joining from a conference room in Seattle, a coffee shop in Paris, and a home office in China. Programmatically, the event locations property, which is a collection of location objects, can reflect this level of details in displayName and locationType for each location. See an example.
  • Outlook gives customers the flexibility to organize events and specify a time zone for each of the start and end times of an event. To support this flexibility, by default, the calendar API returns the start and end times of an event in UTC, and provides the originalStartTimeZone and originalEndTimeZone properties to note the time zones used when the event was created.
  • Alternatively, you can specify the Prefer: outlook.timezone="{time zone name}" header so that a GET event operation returns start and end in the time zone you specify. The time zone name can be any of those supported by Windows, as well as those on this list. See an example of the Prefer header in use.
  • Organizations that support online meeting providers, such as Microsoft Teams and Skype, can set up Outlook calendars to use these providers. You can conveniently organize or attend events in these calendars as online meetings.

Build apps with location awareness and provide intelligent context

Use the places API to help users navigate to a place, or provide an intelligent solution based on the user's location. The following are some example scenarios:

  • Incorporate place details in calendar events to help users navigate their day and enhance productivity.**
  • Catering applications can use the places API to assist venue navigation and set up.**
  • Automate emailing pre-meeting details to attendees and include a map on how to get to a room.**
  • Set up reception bot assistants to provide information about specific rooms in a building.**

Depending on your app scenario, you can use the places API within the context of Outlook, or independent of Outlook.

Take advantage of social intelligence and other developer conveniences in Microsoft Graph

Use the people API in Microsoft Graph to connect to people data which is based on a user's communication and collaboration patterns and business relationships. You can implement controls such as a people picker and suggest persons relevant to the user when organizing meetings on the user's behalf.

Save overhead in storing and managing app data in external data stores. With Microsoft Graph, you can store custom app data as open extensions in individual resource instances. If you require the data to be typed or would like to be able to share the typed schema, you can store custom app data in schema extensions.

Where is the data?

The Microsoft Graph API supports accessing data in users' primary mailboxes and in shared mailboxes. The data can be calendar, mail, or personal contacts stored in a mailbox in the cloud on Exchange Online as part of Microsoft 365.

The API does not support accessing in-place archive mailboxes, not on Exchange Online nor on Exchange Server.

API reference

Looking for the API reference for this service?

Related content