[DEPRECATED] Outlook Calendar REST API reference (version 2.0)

Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Note

Version 2.0 of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. The v2.0 REST endpoint will be fully decommissioned in March 2024, and the v2.0 documentation will be removed shortly afterwards. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

The Calendar API provides access to events, calendar, and calendar group data secured by Azure Active Directory on Office 365, and to similar data in Microsoft accounts specifically in these domains: Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.

Note

• The exception is the API to find meeting times, which applies to only Office 365 mailboxes (on Azure AD) and not to Microsoft accounts.
• For simplicity of reference, the rest of this article uses Outlook.com to include these Microsoft account domains.

Not interested in v2.0 of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.

All Calendar API operations

Event operations

An event represents an appointment or meeting on the user's calendar. An event can be a series master (for recurring events), an occurrence, a single instance, or an exception.

• Get events
• Sync events
• Find meeting times
• Create events
• Update events
• Respond to events
• Delete events
• Get attachments
• Create attachments
• Delete attachments
• Get reminders
• Snooze reminders
• Dismiss reminders

Calendar operations

A calendar serves as a container for events. A user can have multiple calendars. In Office 365, each calendar can be assigned to a calendar group.

• Get calendars
• Create calendars
• Update calendars
• Delete calendars

Calendar group operations

Calendar groups are a way to organize multiple calendars. Users can add multiple calendars into a single calendar group in Outlook or Outlook Web App. This makes it easier for users to quickly view all calendars within the group.

Note

Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut. You cannot delete that calendar group, or create another calendar group.

• Get calendar groups
• Create calendar groups
• Update calendar groups
• Delete calendar groups

See also

• REST API event resource
• REST API calendar resource
• REST API calendar group resource

Using the Calendar REST API

Authentication

Like other Outlook REST API, for every request to the Calendar API, you should include a valid access token. Getting an access token requires you to have registered and identified your app, and obtained the appropriate authorization.

You can find out more about some streamlined registration and authorization options for you. Keep this in mind as you proceed with the specific operations in the Calendar API.

Scopes to access shared calendars

Office 365 and Outlook.com calendars support sharing. A user who created a calendar can share the calendar with other users. The following scopes are required to access a calendar that has been shared with that user:

• For read access: https://outlook.office.com/calendars.read.shared
• For read/write access: https://outlook.office.com/calendars.readwrite.shared

Version of API

The Calendar REST API is supported in all versions of the Outlook REST API. The functionality may differ depending on the specific version.

Target user

The Calendar API requests are always performed on behalf of the current user.

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.

Get events

Get an event collection or an event.

An event body can be in either text or HTML.

You can use the Prefer: outlook.body-content-type header to specify the desired format returned in the Body property in a GET request:

• Specify Prefer: outlook.body-content-type="text" to get an event body returned in text format.
• Specify Prefer: outlook.body-content-type="html", or just skip the header, to return the event body in HTML format.

If you specify either header, the response will include the corresponding Preference-Applied header as confirmation:

• For text format requests: Preference-Applied: outlook.body-content-type="text"
• For HTML format requests: Preference-Applied: outlook.body-content-type="html"

All operations that get calendar events can use the Prefer: outlook.timezone HTTP header to specify the time zone for start and end times in the response. For example, the following Prefer: outlook.timezone header sets the start and end times in the response to Eastern Standard Time.

Prefer: outlook.timezone="Eastern Standard Time"

If you do not specify the Prefer: outlook.timezone header the start and end times in the response are returned in UTC. See this list for the supported time zone names.

You can use the OriginalStartTimeZone and OriginalEndTimeZone properties on the Event resource to find out the time zone used when the event was created.

• Get a calendar view
• Get series master and single events
• Get event instances)
• Get an event

Get a calendar view

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get the occurrences, exceptions, and single instances of events in a calendar view defined by a time range, from the user's primary calendar (../me/calendarview) or from a different calendar.

GET https://outlook.office.com/api/v2.0/me/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}
GET https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}

Required parameter	Type	Description
Header parameters
Prefer:	outlook.timezone	The default time zone for events in the response.
URL parameters
calendar_id	string	The calendar ID, if you're getting a calendar view from a specific calendar.
start_datetime	datetimeoffset	The date and time when the event starts.
end_datetime	datetimeoffset	The date and time when the event ends.

Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.

See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.

Note

By default, each event in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.

For example, get the calendar view for the month of October, returning only the Subject property for each event. Assuming that the Prefer: outlook.timezone header is not included in the request, the time zone will be UTC.

GET https://outlook.office.com/api/v2.0/me/calendarview?startDateTime=2014-10-01T01:00:00&endDateTime=2014-10-31T23:00:00&$select=Subject

Response type

The expanded events within the specified time range.

Get series master and single events

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get a collection of series master and single instance events from the user's primary calendar (../me/events) or from a different calendar. To get expanded event instances, you can get the calendar view or get the instances of an event.

GET https://outlook.office.com/api/v2.0/me/events
GET https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}/events

Required parameter	Type	Description
Header parameters
Prefer:	outlook.timezone	The default time zone for events in the response.
URL parameters
calendar_id	string	The calendar ID, if you're getting events from a specific calendar.

Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.

See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.

Note

Each event in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See the next example. See OData query parameters for filtering, sorting, and paging parameters.

The following example shows how to use $select to specify returning only the Subject, Organizer, Start and End properties of each event in the response. Refer to the first sample response in Get an event (REST) for a full list of properties that would be returned for an event if you don't use $select.

Sample request

GET https://outlook.office.com/api/v2.0/me/events?$select=Subject,Organizer,Start,End

Sample response

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer,Start,End)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI28tEyDAAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAA/LpDWw==\"",
            "Id": "AAMkAGI28tEyDAAA=",
            "Subject": "Scrum",
            "Start": {
                "DateTime": "2015-11-02T17:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2015-11-02T17:30:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "user0TestUser",
                    "Address": "user0@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI28tEyCAAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAA/LpDWg==\"",
            "Id": "AAMkAGI28tEyCAAA=",
            "Subject": "team lunch",
            "Start": {
                "DateTime": "2015-11-02T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2015-11-03T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "user0TestUser",
                    "Address": "user0@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2ADTG93AAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x49w==\"",
            "Id": "AAMkAGI2G93AAA=",
            "Subject": "Weekly Meeting on Contoso Project",
            "Start": {
                "DateTime": "2014-10-13T21:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2014-10-13T22:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "Alex D",
                    "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG92AAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x49g==\"",
            "Id": "AAMkAGI2TG92AAA=",
            "Subject": "Daily Team Meeting",
            "Start": {
                "DateTime": "2014-10-13T18:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2014-10-13T18:30:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "Alex D",
                    "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG91AAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x47Q==\"",
            "Id": "AAMkAGI2TG91AAA=",
            "Subject": "Rob:Alex 1:1",
            "Start": {
                "DateTime": "2014-10-15T16:30:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": "2014-10-15T17:30:00Z",
            "Organizer": {
                "EmailAddress": {
                    "Name": "Alex D",
                    "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG90AAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x46g==\"",
            "Id": "AAMkAGI2TG90AAA=",
            "Subject": "Thanksgiving Holiday",
            "Start": {
                "DateTime": "2015-11-26T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2015-11-27T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "Alex D",
                    "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9zAAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x46Q==\"",
            "Id": "AAMkAGI2TG9zAAA=",
            "Subject": "Thanksgiving Holiday",
            "Start": {
                "DateTime": "2014-11-27T00:00:00"
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2014-11-28T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "Alex D",
                    "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9yAAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x49Q==\"",
            "Id": "AAMkAGI2TG9yAAA=",
            "Subject": "New Year's Day Holiday",
            "Start": {
                "DateTime": "2015-01-01T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2015-01-02T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "Alex D",
                    "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9xAAA=')",
            "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x45w==\"",
            "Id": "AAMkAGI2TG9xAAA=",
            "Subject": "Christmas Holiday",
            "Start": {
                "DateTime": "2014-12-25T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "End": {
                "DateTime": "2014-12-26T00:00:00",
                "TimeZone": "Pacific Standard Time"
            },
            "Organizer": {
                "EmailAddress": {
                    "Name": "Alex D",
                    "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
                }
            }
        }
    ]
}

Get event instances

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

You can get the instances (occurrences) of an event for a specified time range. If the event is a SeriesMaster type, this returns the occurrences and exceptions of the event in the specified time range.

GET https://outlook.office.com/api/v2.0/me/events/{event_id}/instances?startDateTime={start_datetime}&endDateTime={end_datetime}

Required parameter	Type	Description
Header parameters
Prefer:	outlook.timezone	The default time zone for events in the response.
URL parameters
event_id	string	The event ID.
start_datetime	datetimeoffset	The UTC date and time when the event starts.
end_datetime	datetimeoffset	The UTC date and time when the event ends.

Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.

See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.

Response type

The requested event collection.

Note

By default, each event in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.

For example, get the instances of a particular event for the month of October, include only the Subject, Start and End properties of each instance:

GET https://outlook.office.com/api/v2.0/me/events/AAMkAGE0MGM1Y2M5LWEAAA=/instances?startDateTime=2014-10-01T01:00:00Z&endDateTime=2014-10-31T23:00:00Z&$select=Subject,Start,End

Get an event

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get an event by ID.

GET https://outlook.office.com/api/v2.0/me/events/{event_id}

Required parameter	Type	Description
Header parameters
Prefer:	outlook.timezone	The default time zone for events in the response.
URL parameters
event_id	string	The event ID.

Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.

See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.

Sample request

GET https://outlook.office.com/api/v2.0/me/events/AAMkAGI2TG93AAA=

Sample response

    {
        "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
        "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG93AAA=')",
        "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48w==\"",
        "Id": "AAMkAGI2TG93AAA=",
        "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x48w==",
        "Categories": [],
        "CreatedDateTime": "2014-10-19T23:13:47.3959685Z",
        "LastModifiedDateTime": "2014-10-19T23:13:47.6772234Z",
        "Subject": "Weekly Meeting on Contoso Project",
        "BodyPreview": "Setting up some time to review the budget and planning on the Contoso Project",
        "Body": {
            "ContentType": "HTML",
            "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nSetting up some time to review the budget and planning on the Contoso Project\r\n</body>\r\n</html>\r\n"
        },
        "Importance": "Normal",
        "HasAttachments": false,
        "Start": {
            "DateTime": "2014-10-13T21:00:00",
            "TimeZone": "Pacific Standard Time"
        },
        "End": {
            "DateTime": "2014-10-13T22:00:00",
            "TimeZone": ""Pacific Standard Time"
        },
        "Location": {
            "DisplayName": "Alex's Office",
            "Address": null
        },
        "ShowAs": "Busy",
        "IsAllDay": false,
        "IsCancelled": false,
        "IsOrganizer": true,
        "ResponseRequested": true,
        "Type": "SeriesMaster",
        "SeriesMasterId": null,
        "Attendees": [
            {
                "EmailAddress": {
                    "Address": "janets@a830edad9050849NDA1.onmicrosoft.com",
                    "Name": "Janet Schorr"
                },
                "Status": {
                    "Response": "None",
                    "Time": "0001-01-01T00:00:00Z"
                },
                "Type": "Required"
            },
            {
                "EmailAddress": {
                    "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
                    "Name": "Pavel Bansky"
                },
                "Status": {
                    "Response": "None",
                    "Time": "0001-01-01T00:00:00Z"
                },
                "Type": "Required"
            }
        ],
        "Recurrence": {
            "Pattern": {
                "Type": "Weekly",
                "Interval": 1,
                "Month": 0,
                "Index": "First",
                "FirstDayOfWeek": "Sunday",
                "DayOfMonth": 0,
                "DaysOfWeek": [
                    "Monday"
                ]
            },
            "RecurrenceTimeZone": "Pacific Standard Time",
            "Range": {
                "Type": "NoEnd",
                "StartDate": "2014-10-13",
                "EndDate": "2014-11-13",
                "NumberOfOccurrences": 0
            }
        },
        "OriginalEndTimeZone": "Pacific Standard Time",
        "OriginalStartTimeZone": "Pacific Standard Time",
        "Organizer": {
            "EmailAddress": {
                "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
                "Name": "Alex D"
            },
        "OnlineMeetingUrl": null
        }
    }

Response type

The requested event.

Note

By default, the response includes all the properties of the event. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.

The following example shows how to use $select to specify returning only the Subject, Organizer, Start and End properties of the event.

Sample request

GET https://outlook.office.com/api/v2.0/me/events/AAMkAGI2TG93AAA=?$select=Subject,Organizer,Start,End

Sample response

    {
        "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
        "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG93AAA=')",
        "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48w==\"",
        "Id": "AAMkAGI2TG93AAA=",
        "Subject": "Weekly Meeting on Contoso Project",
        "Start": {
            "DateTime": "2014-10-13T21:00:00",
            "TimeZone": "Pacific Standard Time"
        },
        "End": {
            "DateTime": "2014-10-13T22:00:00",
            "TimeZone": ""Pacific Standard Time"
        },
        "Organizer": {
            "EmailAddress": {
                "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
                "Name": "Alex D"
            }
        }
    }

Sync events

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Synchronize and get new, updated, or deleted events in a specified time range from the user's primary calendar (../me/calendarview) or from a different calendar. Such a set of events in a time range is also known as a calendar view. The returned events may include occurrences and exceptions of a recurring series, and single instances.

Synchronizing a calendar view typically requires a round of two or more sync requests, each of which is a GET call. To synchronize a calendar view, use the GET method much like the way you get a calendar view, except that you include certain request headers, and deltaToken or a skipToken when appropriate.

Request headers

• You must specify the "Prefer: odata.track-changes" header in all sync requests except those that include a skipToken that is returned from a previous sync request. In the first response, look for the Preference-Applied: odata.track-changes header to confirm that the resource supports synchronizing before proceeding. (More information about a skipToken in sample second response data below.)

• You can specify the "Prefer: odata.maxpagesize={x}" header to indicate the maximum number of events that sync request returns.

Here's a typical round of synchronizing events in a calendar view:

1. Make the initial GET request with the mandatory Prefer: odata.track-changes header. The initial response to a sync request always returns a deltaToken. (The second and subsequent GET requests differ from the first GET request by including either a deltaToken or a skipToken received in a previous response.)

2. If the first response returns the Preference-Applied: odata.track-changes header, you can proceed with synchronizing.

   • Make a second GET request. Specify the Prefer: odata.track-changes header and the deltaToken returned from the first GET to determine if there are any additional events. The second request will return additional events, and either a skipToken if there are more events available, or a deltaToken if the last event has been synchronized, in which case you can stop.

   • Continue synchronizing by sending a GET call and including a skipToken that's returned from the previous call. Stop when you get a final response that contains an @odata.deltaLink header with a deltaToken again, which indicates the sync is complete.

Take a look at the syntax for the initial and subsequent calls in a round of sync.

To sync in the default calendar

Initial request:

GET https://outlook.office.com/api/v2.0/{user_context}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}

Second request, or first request of a subsequent round:

GET https://outlook.office.com/api/v2.0/{user_context}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}&$deltatoken={delta_token}

Third or subsequent request in the same round:

GET https://outlook.office.com/api/v2.0/{user_context}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}&$skiptoken={skip_token}

To sync in a specific calendar

Initial request:

GET https://outlook.office.com/api/v2.0/{user_context}/calendars('{calendar_id}')/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}

Second request, or first request of a subsequent round:

GET https://outlook.office.com/api/v2.0/{user_context}/calendars('{calendar_id}')/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}&$deltatoken={delta_token}

Third or subsequent request in the same round:

GET https://outlook.office.com/api/v2.0/{user_context}/calendars('{calendar_id}')/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}&$skiptoken={skip_token}

Parameters

Parameter	Type	Description
URL parameters
user_context	string	The user context. You can use the value of 'me' to indicate the context of the current user. You can also use the users/{upn} format where the upn is the user principal name which is typically the user's email address.
calendar_id	string	The calendar ID, if you're getting a calendar view from a specific calendar.
start_datetime	datetimeoffset	The date and time when the event starts.
end_datetime	datetimeoffset	The date and time when the event ends.
delta_token	string	The deltaToken string returned as part of the value for @odata.deltaLink in the previous sync response.
skip_token	string	The skipToken string returned as part of the value for @odata.nextLink in the previous sync response.

Note

• When specifying "Prefer: odata.track-changes" in the initial request, if the response supports sync, the response would include "Preference-applied: odata.track-changes" in the header.
• If you attempt to sync a resource that isn't supported, or if this is not the initial sync request, you will not see the "Preference-applied" header in the response.
• You can alter the change time window by changing the startdatetime and enddatetime query parameters.
• Each event in the response includes all its properties.
• For a recurring series, a sync response includes the entire event for the recurring master and exception events.
• Instances of a recurring series are abbreviated and contain only the Start and End properties. You can capture the remainder of the occurrence event information from the recurring master event. See Event resource for reference information.
• You cannot use the $filter, $count, $select, $skip, $top, and $search query parameters.

Response type

The expanded events and abbreviated events within the specified time range.

Example

The following example shows the initial and second sync requests to synchronize the default calendar for the user. Each request specifies to return only one full event at a time:

• The initial response returns one event, a deltaLink and deltaToken.
• The second request uses that deltatoken. The second response returns one event, a nextLink and skipToken.

To complete the sync, use the skipToken returned from the previous sync request until the sync response returns a deltaLink and deltaToken, in which case this round of sync is complete. Save the deltaToken for the next round of sync.

For more information, see Synchronize events in an Outlook calendar view.

Sample initial request

	GET https://outlook.office.com/api/v2.0/me/calendarview?startdatetime=2015-01-01T00:00:00Z&enddatetime=2015-04-10T00:00:00Z HTTP/1.1
	Authorization: Bearer <token>
	Prefer: odata.track-changes
	Prefer: odata.maxpagesize=1

Sample initial response data

Preference-Applied: odata.track-changes

	{
	    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/CalendarView",
	    "value": [
	        {
	            "@odata.id": "https://outlook.office.com/api/v2.0/Users('user0@contoso.com')/Events('asdas==')",
	            "@odata.etag": "W/\"L8Z+4Y4u7k+97uRKg==\"",
	            "Id": "AQMkANJAAAAA==",
	            "ChangeKey": "L8Z+AAAAARKg==",
	            "Categories": [
	            ],
	            "DateTimeCreated": "2015-04-10T17:54:49.2725912Z",
	            "DateTimeLastModified": "2015-04-10T17:54:49.3038538Z",
	            "Subject": "Discuss the Calendar REST API",
	            "BodyPreview": "I think it will meet our requirements!",
	            "Body": {
	                "ContentType": "HTML",
	                "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
	            },
	            "Importance": "Normal",
	            "HasAttachments": false,
	            "Start": {
                    "DateTime": "2015-04-05T18:00:00",
                    "TimeZone": "Pacific Standard Time"
                }
	            "End": {
                    "DateTime": "2015-04-05T19:00:00",
                    "TimeZone": "Pacific Standard Time"
                }
	            "ReminderMinutesBeforeStart": "15",
                "IsReminderOn": "true",
                "Location": {
	                "DisplayName": "",
	                "Address": null
	            },
	            "ResponseStatus": {
	                "Response": "Organizer",
	                "Time": "0001-01-01T00:00:00Z"
	            },
	            "ShowAs": "Busy",
	            "IsAllDay": false,
	            "IsCancelled": false,
	            "IsOrganizer": true,
	            "ResponseRequested": true,
	            "Type": "SingleInstance",
	            "SeriesMasterId": null,
	            "Attendees": [
	            ],
	            "Recurrence": null,
                "OriginalEndTimeZone": "Pacific Standard Time",
                "OriginalStartTimeZone": "Pacific Standard Time",
	            "Organizer": {
	                "EmailAddress": {
	                    "Address": "user0@contoso.com",
	                    "Name": "user0"
	                }
	            },
	            "iCalUId": "040000008200E9888E07599CCFA23",
	            "WebLink": "https://outlook.office.com/owa/?ItemID=AAAINJAAAAA%3D%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
                "OnlineMeetingUrl": null
	        }
	    ],
	    "@odata.deltaLink": "https://outlook.office.com/api/v2.0/me/calendarview/?startdatetime=2015-01-01T00%3a00%3a00Z&enddatetime=2015-04-10T00%3a00%3a00Z&%24deltatoken=v2%2cH4roCAAA%3d%2c1.0%2cFalse%2cA00%2c"
	}

Sample second request

	GET https://outlook.office.com/api/v2.0/me/calendarview?startdatetime=2015-01-01T00:00:00Z&enddatetime=2015-04-10T00:00:00Z&$deltatoken=v2%2cH4roCAAA%3d%2c1.0%2cFalse%2cA00%2c
	Authorization: Bearer <token>
	Prefer: odata.track-changes
	Prefer: odata.maxpagesize=1

Sample second response data

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/CalendarView/$delta",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('user0@contoso.com')/Events('AAMkAD0jAAA=')",
            "@odata.etag": "W/\"P2fd7QAAAAAVFA==\"",
            "Id": "AAMkADNkNmVlOTITVAAAAAA0jAAA=",
            "ChangeKey": "P2fdmIU1QAAAAAVFA==",
            "Categories": [
            ],
            "DateTimeCreated": "2015-04-15T18:59:11.0226221Z",
            "DateTimeLastModified": "2015-04-15T18:59:11.0694979Z",
            "Subject": "1 hour",
            "BodyPreview": "\u200b",
            "Body": {
                "ContentType": "HTML",
                "Content": "<html><body>content</body></html>"
            },
            "Importance": "Normal",
            "HasAttachments": false,
            "Start": {
                "DateTime": "2015-04-16T18:00:00",
                "TimeZone": "Pacific Standard Time"
            }
            "End": {
                "DateTime": "2015-04-16T19:00:00",
                "TimeZone": Pacific Standard Time"
            }
            "ReminderMinutesBeforeStart": "15",
            "IsReminderOn": "true",
            "Location": {
                "DisplayName": "",
                "Address": {
                    "Street": "",
                    "City": "",
                    "State": "",
                    "CountryOrRegion": "",
                    "PostalCode": ""
                }
             },
            "ResponseStatus": {
                "Response": "Organizer",
                "Time": "0001-01-01T00:00:00Z"
            },
            "ShowAs": "Busy",
            "IsAllDay": false,
            "IsCancelled": false,
            "IsOrganizer": true,
            "ResponseRequested": true,
            "Type": "SingleInstance",
            "SeriesMasterId": null,
            "Attendees": [
            ],
            "Recurrence": null,
            "OriginalEndTimeZone": "Pacific Standard Time",
            "OriginalStartTimeZone": "Pacific Standard Time",
            "Organizer": {
                "EmailAddress": {
                    "Address": "user0@contoso.com",
                    "Name": "user0"
                }
            },
            "iCalUId": "040000008200E09BB89A316862",
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADNkNmVlOAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
            "OnlineMeetingUrl": null
        }
    ],
    "@odata.nextLink": "https://outlook.office.com/api/v2.0/me/calendarview/?startdatetime=2015-01-01T00%3a00%3a00Z&enddatetime=2015-08-10T00%3a00%3a00Z&%24skipToken=530c9d02ae1a4d96804538bd4d381546"
}

Find meeting times

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read.shared
• wl.calendars
• wl.contacts_calendars

Find meeting time suggestions based on organizer and attendee availability, and time or location constraints specified as parameters.

This operation applies to only Office 365 mailboxes (on Azure AD) and not to Microsoft accounts.

POST https://outlook.office.com/api/{version}/me/findmeetingtimes

All the supported parameters are listed below. Depending on your scenario, specify the necessary parameters in the request body of the FindMeetingTimes action.

Parameter	Type	Description	Required?
Attendees	Collection(AttendeeBase)	Attendees or resources for the meeting. An empty collection causes FindMeetingTimes to look for free time slots for only the organizer.	Optional
IsOrganizerOptional	Edm.Boolean	Specify true if the organizer doesn't necessarily have to attend. The default is false.	Optional
LocationConstraint	LocationConstraint	The organizer's requirements about the meeting location, such as whether a suggestion for a meeting location is required, or there are specific locations only where the meeting can take place.	Optional
MaxCandidates	Edm.Int32	The maximum number of meeting suggestions to return in the response.	Optional
MeetingDuration	Edm.Duration	The length of the meeting expressed in ISO 8601 format for durations, for example, PT1H represents 1 hour. If no meeting duration is specified, FindMeetingTimes uses the default of 30 minutes.	Optional
MinimumAttendeePercentage	Edm.Double	The minimum required confidence for a time slot to be returned in the response. It is a % value ranging from 0 to 100.	Optional
ReturnSuggestionReasons	Edm.Boolean	Specify true to return a reason for each meeting suggestion in the SuggestionReason property. The default is false to not return that property.	Optional
TimeConstraint	TimeConstraint	Any time restrictions for a meeting, which can include the nature of the meeting (ActivityDomain) and possible meeting time periods (TimeSlots). FindMeetingTimes assumes ActivityDomain as Work if you don't specify this parameter.	Optional

FindMeetingTimes checks the free/busy status in the primary calendars of the organizer and attendees. Based on the specified parameters, the action suggests the best possible meeting times. The following table describes the restrictions you can specify in the TimeConstraint parameter.

ActivityDomain value in TimeConstraint	Suggestions for meeting times
Work	Suggestions are within the user's work hours which are defined in the user’s calendar configuration and can be customized by the user or administrator. The default work hours are Monday to Friday, 8am to 5pm in the time zone setting for the mailbox. This is the default value if no ActivityDomain is specified.
Personal	Suggestions are within the user's work hours, and Saturday and Sunday. The default is Monday to Sunday, 8am to 5pm, in the time zone set for the mailbox.
Unrestricted	Suggestions can be from all hours of a day, all days of a week.
Unknown	Do not use this value as it will be deprecated in the future. Currently behaves the same as Work. Change any existing code to use Work, Personal or Unrestricted as appropriate.

Response type

A MeetingTimeSuggestionsResult which includes a collection of meeting suggestions, each of type MeetingTimeSuggestion, and an EmptySuggestionsReason property.

Each suggestion is defined as a MeetingTimeSuggestion, with attendees having by default a confidence level of 50% to attend, or a specific % that you have specified in the MinimumAttendeePercentage parameter.

By default, each meeting time suggestion is returned in UTC. Apply the Prefer: outlook.timezone request header to have meeting time suggestions retuned in a different time zone, for example:

Prefer: outlook.timezone="Pacific Standard Time"

If FindMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the EmptySuggestionsReason property. Based on this value, you can better adjust the parameters and call FindMeetingTimes again.

Note

Currently, FindMeetingTimes assumes that any Attendee who is a person (as opposed to a resource) is a required attendee. So, specify Required for a person and Resource for a resource in the corresponding Type property, as part of the Attendees collection parameter.

Each example below calls FindMeetingTimes, and varies by attendee availability, time, and location constraints:

• Find time and location to meet with attendees
• Find time to meet at a known location, and get a reason for each suggestion
• Find time to meet but no attendee is available
• Find time to meet but only some attendees available
• Find free time slots for just the signed-in user

Find time and location to meet with specific attendees

Find times and locations to meet by specifying the following parameters in the request body:

• Attendees
• TimeConstraint
• MeetingDuration

Sample request

The following example suggests meeting times and locations taking into consideration the organizer's and attendee's availability during work hours in the requested meeting time range, and the requested length of time.

POST https://outlook.office.com/api/v2.0/me/findmeetingtimes

Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{
  "Attendees": [
    {
      "Type": "Required",
      "EmailAddress": {
        "Name": "Fanny",
        "Address": "fannyd@prosewareltd.onmicrosoft.com"
      }
    }
  ],
  "TimeConstraint": {
    "ActivityDomain":"Work",
    "Timeslots": [
       {
        "Start": {
          "DateTime": "2016-05-20T07:00:00",
          "TimeZone": "Pacific Standard Time"
        },
        "End": {
          "DateTime": "2016-05-20T17:00:00",
          "TimeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "MeetingDuration": "PT1H"
}

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
    "MeetingTimeSuggestions": [
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-20T10:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T11:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
                {
                    "Attendee": {
                        "Type": "Required",
                        "EmailAddress": {
                            "Name": "Fanny",
                            "Address": "fannyd@prosewareltd.onmicrosoft.com"
                        }
                    },
                    "Availability": "Free"
                }
            ],
            "Locations": [
               {
                    "DisplayName": "Tokyo conference room",
                    "LocationEmailAddress": "",
                    "LocationUri": "",
                    "Address": null,
                    "Coordinates": null
                }
            ]
        },
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-20T11:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T12:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
                {
                    "Attendee": {
                        "Type": "Required",
                        "EmailAddress": {
                            "Name": "Fanny",
                            "Address": "fannyd@prosewareltd.onmicrosoft.com"
                        }
                    },
                    "Availability": "Free"
                }
            ],
            "Locations": [
               {
                    "DisplayName": "Paris conference room",
                    "LocationEmailAddress": "",
                    "LocationUri": "",
                    "Address": null,
                    "Coordinates": null
                }
            ]
        }
    ],
    "EmptySuggestionsReason": ""
}

Find time to meet at a known location, and get a reason for each suggestion

Find time to meet at a pre-determined location, and request a reason for each suggestion, by specifying the following parameters in the request body:

• Attendees
• LocationConstraint
• TimeConstraint
• MeetingDuration
• ReturnSuggestionReasons

By setting the ReturnSuggestionReasons parameter, you also get an explanation for each suggestion in the SuggestionReason property, if FindMeetingTimes returns any suggestion.

Sample request

POST https://outlook.office.com/api/v2.0/me/findmeetingtimes

Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{
  "Attendees": [
    {
      "Type": "Required",
      "EmailAddress": {
        "Name": "Fanny",
        "Address": "fannyd@prosewareltd.onmicrosoft.com"
      }
    }
  ],
  "LocationConstraint": {
    "IsRequired": "false",
    "SuggestLocation": "false",
    "Locations": [
      {
        "ResolveAvailability": "false",
        "DisplayName": "Conf room Hood"
      }
    ]
  },
  "TimeConstraint": {
    "ActivityDomain":"Work",
    "Timeslots": [
      {
        "Start": {
          "DateTime": "2016-05-20T07:00:00",
          "TimeZone": "Pacific Standard Time"
        },
        "End": {
          "DateTime": "2016-05-20T17:00:00",
          "TimeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "MeetingDuration": "PT2H",
  "ReturnSuggestionReasons": "true"
}

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
    "MeetingTimeSuggestions": [
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-20T10:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T12:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
                {
                    "Attendee": {
                        "Type": "Required",
                        "EmailAddress": {
                            "Name": "Fanny",
                            "Address": "fannyd@prosewareltd.onmicrosoft.com"
                        }
                    },
                    "Availability": "Free"
                }
            ],
            "Locations": [
                {
                    "DisplayName": "Conf room Hood"
                }
            ],
            "SuggestionReason": "Suggested because it is one of the nearest times when all attendees are available."
        }
    ],
    "EmptySuggestionsReason": ""
}

Find time to meet but no attendee is available

Find time to meet at a pre-determined location, by specifying the following parameters in the request body:

• Attendees
• LocationConstraint
• TimeConstraint
• MeetingDuration

In this example, based on specified parameters and attendee availability, FindMeetingTimes cannot return any suggestions, and instead returns a reason AttendeesUnavailable in the EmptySuggestionsReason property.

See other possible reasons for not returning any meeting suggestions.

Sample request

POST https://outlook.office.com/api/v2.0/me/findmeetingtimes

Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{
  "Attendees": [
    {
      "Type": "Required",
      "EmailAddress": {
        "Name": "Fanny",
        "Address": "fannyd@prosewareltd.onmicrosoft.com"
      }
    }
  ],
  "LocationConstraint": {
    "IsRequired": "false",
    "SuggestLocation": "false",
    "Locations": [
      {
        "ResolveAvailability": "false",
        "DisplayName": "Conf room Hood"
      }
    ]
  },
  "TimeConstraint": {
    "Timeslots": [
      {
        "Start": {
          "DateTime": "2016-05-20T7:00:00",
          "TimeZone": "Pacific Standard Time"
        },
        "End": {
          "DateTime": "2016-05-20T14:00:00",
          "TimeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "MeetingDuration": "PT2H"
}

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
    "MeetingTimeSuggestions": [
    ],
    "EmptySuggestionsReason": "AttendeesUnavailable"
}

Find time to meet but only some attendees are available

Find time to meet at a pre-determined location, by specifying the following parameters in the request body:

• Attendees
• LocationConstraint
• TimeConstraint
• MeetingDuration
• ReturnSuggestionReasons
• MinimumAttendeePercentage

In this example, only one of the two attendees is available. Each meeting suggestion that FindMeetingTimes returns includes:

• The availability of each attendee
• A computed meeting Confidence which is the average % chance of the attendees attending. This value must meet the 60% requirement specified in MinimumAttendeePercentage.
• A SuggestionHint, since the ReturnSuggestionReasons parameter is set.

Find more information about the confidence of a meeting.

Sample request

POST https://outlook.office.com/api/v2.0/me/findmeetingtimes

Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{
  "Attendees": [
    {
      "Type": "Required",
      "EmailAddress": {
        "Name": "Fanny",
        "Address": "fannyd@prosewareltd.onmicrosoft.com"
      }
    },
   {
      "Type": "Optional",
      "EmailAddress": {
        "Name": "Dana",
        "Address": "danas@prosewareltd.onmicrosoft.com"
      }
    }
  ],
  "LocationConstraint": {
    "IsRequired": "false",
    "SuggestLocation": "false",
    "Locations": [
      {
        "ResolveAvailability": "false",
        "DisplayName": "Conf room Hood"
      }
    ]
  },
  "TimeConstraint": {
    "ActivityDomain":"Work",
    "Timeslots": [
      {
        "Start": {
          "DateTime": "2016-05-20T09:00:00",
          "TimeZone": "Pacific Standard Time"
        },
        "End": {
          "DateTime": "2016-05-20T17:00:00",
          "TimeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "MeetingDuration": "PT1H",
  "ReturnSuggestionReasons": "true",
  "MinimumAttendeePercentage": "60"
}

Sample response

Status code: 200

{
   "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
   "MeetingTimeSuggestions":[
      {
         "MeetingTimeSlot":{
            "Start":{
               "DateTime":"2016-05-20T10:00:00.0000000",
               "TimeZone":"Pacific Standard Time"
            },
            "End":{
               "DateTime":"2016-05-20T11:00:00.0000000",
               "TimeZone":"Pacific Standard Time"
            }
         },
         "Confidence":100.0,
         "OrganizerAvailability":"Free",
         "AttendeeAvailability":[
            {
               "Attendee":{
                  "Type":"Required",
                  "EmailAddress":{
                     "Name": "Fanny",
                     "Address":"fannyd@prosewareltd.onmicrosoft.com"
                  }
               },
               "Availability":"Free"
            },
            {
               "Attendee":{
                  "Type":"Required",
                  "EmailAddress":{
                     "Name": "Dana",
                     "Address":"danas@prosewareltd.onmicrosoft.com"
                  }
               },
               "Availability":"Free"
            }
         ],
         "Locations":[
            {
               "DisplayName":"Conf room Hood"
            }
         ],
         "SuggestionReason":"Suggested because it is one of the nearest times when most attendees are available."
      },
      {
         "MeetingTimeSlot":{
            "Start":{
               "DateTime":"2016-05-20T11:00:00.0000000",
               "TimeZone":"Pacific Standard Time"
            },
            "End":{
               "DateTime":"2016-05-20T12:00:00.0000000",
               "TimeZone":"Pacific Standard Time"
            }
         },
         "Confidence":74.5,
         "OrganizerAvailability":"Free",
         "AttendeeAvailability":[
            {
               "Attendee":{
                  "Type":"Required",
                  "EmailAddress":{
                     "Name": "Fanny",
                     "Address":"fannyd@prosewareltd.onmicrosoft.com"
                  }
               },
               "Availability":"Free"
            },
            {
               "Attendee":{
                  "Type":"Required",
                  "EmailAddress":{
                     "Name": "Dana",
                     "Address":"danas@prosewareltd.onmicrosoft.com"
                  }
               },
               "Availability":"Unknown"
            }
         ],
         "Locations":[
            {
               "DisplayName":"Conf room Hood"
            }
         ],
         "SuggestionReason":"Suggested because it is one of the nearest times when most attendees are available."
      }
   ],
   "EmptySuggestionsReason":""
}

Find free time slots for just the signed-in user

Find free time slots in the signed-in user's primary calendar any time of the week within a date range, by specifying the following parameters in the request body:

• TimeConstraint
• MeetingDuration

Sample request

This example looks for one-hour free time slots, as specified by MeetingDuration, in the signed-in user's primary calendar any time of the week within a date range specified by TimeConstraint.

POST https://outlook.office.com/api/v2.0/me/findmeetingtimes

Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{
  "Attendees": [],
  "TimeConstraint": {
    "ActivityDomain": "Unrestricted",
    "Timeslots": [
      {
        "Start": {
          "DateTime": "2016-05-20T06:00:00",
          "TimeZone": "Pacific Standard Time"
        },
        "End": {
          "DateTime": "2016-05-22T23:00:00",
          "TimeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "MeetingDuration": "PT1H"
}

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
    "MeetingTimeSuggestions": [
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-20T06:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T07:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
            ],
            "Locations": [
            ]
        },
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-21T09:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-21T10:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
            ],
            "Locations": [
            ]
        },
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-22T19:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-22T20:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
            ],
            "Locations": [
            ]
        }
    ],
    "EmptySuggestionsReason": ""
}

Get meeting rooms (preview)

This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.

Create events

• Create a calendar event

Create a calendar event

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Create an event in the user's primary calendar or a specific calendar by posting to the calendar's events endpoint. When the event is created, the server sends invitations to all attendees.

POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}/events

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID.

Sample request

POST https://outlook.office.com/api/v2.0/me/events
Content-Type: application/json

{
  "Subject": "Discuss the Calendar REST API",
  "Body": {
    "ContentType": "HTML",
    "Content": "I think it will meet our requirements!"
  },
  "Start": {
      "DateTime": "2014-02-02T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2014-02-02T19:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "janets@a830edad9050849NDA1.onmicrosoft.com",
        "Name": "Janet Schorr"
      },
      "Type": "Required"
    }
  ]
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeNheA==\"",
  "Id": "AAMkAGE4v1RAAA=",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeNheA==",
  "Categories": [],
  "CreatedDateTime": "2014-01-22T20:56:10.1058291Z",
  "LastModifiedDateTime": "2014-01-22T20:56:10.3402186Z",
  "Subject": "Discuss the Calendar REST API",
  "BodyPreview": "I think it will meet our requirements!",
  "Body": {
    "ContentType": "HTML",
    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
  },
  "Importance": "Normal",
  "HasAttachments": false,
  "Start": {
      "DateTime": "2014-02-02T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2014-02-02T19:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Location": {
    "DisplayName": "",
    "Address": null
  },
  "ShowAs": "Busy",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": true,
  "ResponseRequested": true,
  "Type": "SingleInstance",
  "SeriesMasterId": null,
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "janets@a830edad9050849NDA1.onmicrosoft.com",
        "Name": "Janet Schorr"
      },
      "Status": {
        "Response": "None",
        "Time": "0001-01-01T00:00:00Z"
      },
      "Type": "Required"
    }
  ],
  "Recurrence": null,
  "OriginalEndTimeZone": "Pacific Standard Time",
  "OriginalStartTimeZone": "Pacific Standard Time",
  "Organizer": {
    "EmailAddress": {
      "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "alexd"
    }
  },
  "OnlineMeetingUrl": null
}

Response type

The new event.

By default, the response includes all the properties of the new event. Use $select to specify only those properties you need for best performance. The Id property is always returned.

The following is an example to include only the Start and End properties of the new event in the response.

POST https://outlook.office.com/api/v2.0/me/events?$Select=Start,End

Update events

• Update a calendar event

Update a calendar event

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Change an event. Only the properties that you specify are changed. If the user is the organizer, the server sends meeting updates to all attendees.

PATCH https://outlook.office.com/api/v2.0/me/events/{event_id}

Required parameter	Type	Description
URL parameters
event_id	string	The event ID.

Specify any writable event properties in the request body.

Sample request

PATCH https://outlook.office.com/api/v2.0/me/events/AAMkAGE0M4v1OAAA=
Content-Type: application/json

{
  "Location": {
    "DisplayName": "Your office",
    "Address": null
  }
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE0M4v1OAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==\"",
  "Id": "AAMkAGE0M4v1OAAA=",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==",
  "Categories": [],
  "CreatedDateTime": "2014-01-22T20:49:05.5657528Z",
  "LastModifiedDateTime": "2014-01-22T21:14:17.4886416Z",
  "Subject": "Discuss the Calendar REST API",
  "BodyPreview": "I think it will meet our requirements!",
  "Body": {
    "ContentType": "HTML",
    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
  },
  "Importance": "Normal",
  "HasAttachments": false,
  "Start": {
      "DateTime": "2014-02-02T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2014-02-02T19:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Location": {
    "DisplayName": "Your office",
    "Address": null
  },
  "ShowAs": "Busy",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": true,
  "ResponseRequested": true,
  "Type": "SingleInstance",
  "SeriesMasterId": null,
  "Attendees": [],
  "Recurrence": null,
  "OriginalEndTimeZone": "Pacific Standard Time",
  "OriginalStartTimeZone": "Pacific Standard Time",
  "Organizer": {
    "EmailAddress": {
      "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "alexd"
    }
  },
  "OnlineMeetingUrl": null
}

Response type

The updated event. If the user is the organizer, the server sends meeting updates to all attendees.

By default, the response includes all the properties of the updated event. Use $select to specify only those properties you need for best performance. The Id property is always returned.

PATCH https://outlook.office.com/api/v2.0/me/events/AAMkAGE1MFKPQWAAA=?$select=Location

Respond to events

• Accept event
• Tentatively accept event
• Decline event

Accept event

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Accept the specified event.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/accept

Parameter	Type	Description
URL parameters
event_id	string	The event ID. Required.
Body parameters
Comment	string	Text included in the response. Optional.
SendResponse	boolean	true if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/v2.0/me/events('AAMkAGE1M2IyNGNmLTI5MT_bs88AAAXDJwEAAA=')/accept

Content-Type: application/json

{
  "Comment": "Great idea!",
  "SendResponse": "true"
}

Response

A successful response is indicated by an HTTP 202 Accepted response code.

Tentatively accept event

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Tentatively accept the specified event.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/tentativelyaccept

Parameter	Type	Description
URL parameters
event_id	string	The event ID. Required.
Body parameters
Comment	string	Text included in the response. Optional.
SendResponse	boolean	true if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/v2.0/me/events('AAMkAGE1M2IyNGNmLTI5MT_bs88AAAXDJwEAAA=')/tentativelyaccept

Content-Type: application/json

{
  "Comment": "I'll confirm later!",
  "SendResponse": "true"
}

Response

A successful response is indicated by an HTTP 202 Accepted response code.

Decline event

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Decline invitation to the specified event.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/decline

Parameter	Type	Description
URL parameters
event_id	string	The event ID. Required.
Body parameters
Comment	string	Text included in the response. Optional.
SendResponse	boolean	true if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/v2.0/me/events('AAMkAGE1M2IyNGNmLTI5MT_bs88AAAXDJwEAAA=')/decline

Content-Type: application/json

{
  "Comment": "Sorry, maybe next time!",
  "SendResponse": "true"
}

Response

A successful response is indicated by an HTTP 202 Accepted response code.

Forward events (preview)

This feature is currently available in only the beta version. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.

Delete events

• Delete a calendar event

Delete a calendar event

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Move an event to the Deleted Items folder of the signed-in user. If the event is a meeting and the signed-in user is the organizer, the server sends cancellations to all attendees.

DELETE https://outlook.office.com/api/v2.0/me/events/{event_id}

Required parameter	Type	Description
URL parameters
event_id	string	The event ID.

Sample request

DELETE https://outlook.office.com/api/v2.0/me/events/AAMkAGE0M4v1OAAA=

Sample response

Status code: 204

Cancel events (preview)

This feature is currently available in only the beta version. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.

Get attachments

You can get an attachment collection or get an attachment.

• Get an attachment collection
• Get an attachment

Get an attachment collection

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get the attachments from a particular event.

Note

See OData query parameters for filtering, sorting, and paging parameters.

GET https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments

Required parameter	Type	Description
URL parameters
event_id	string	The event ID.

Response type

An attachment collection which can be of the type FileAttachment or ItemAttachment.

Sample request

GET https://outlook.office.com/api/v2.0/me/events/AAMkAGI2NGTG9yAAA=/attachments

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events('AAMkAGI2NG9yAAA%3D')/Attachments",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.FileAttachment",
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2NGTG9yAAA=')/Attachments('AAMkAGI2NGLwydGuOzcHf1FBlo=')",
            "Id": "AAMkAGI2NGLwydGuOzcHf1FBlo=",
            "LastModifiedDateTime": "2014-10-22T00:30:26Z",
            "Name": "Company Party.docx",
            "ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "Size": 11647,
            "IsInline": false,
            "ContentId": null,
            "ContentLocation": null,
            "ContentBytes": "UEsDBBQABgAIAAAAIQDfpNJs...AAF4pAAAAAA=="
        }
    ]
}

Get an attachment

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get an attachment from a particular event.

GET https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments/{attachment_id}

Required parameter	Type	Description
URL parameters
event_id	string	The event ID.
attachment_id	string	The attachment ID.

Note

See OData query parameters for filtering, sorting, and paging parameters.

Response type

The requested file attachment or item attachment.

Sample request

GET https://outlook.office.com/api/v2.0/me/events/AAMkAGI2WRAAADTG9yAAA=/attachments/AAMkAGI2TG9yAAABEgAQALxJtn1LwydGuOzcHf1FBlo=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events('AAMkAGI2WRAAADTG9yAAA%3D')/Attachments/$entity",
    "@odata.type": "#Microsoft.OutlookServices.FileAttachment",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2WRAAADTG9yAAA=')/Attachments('AAMkAGI2TG9yAAABEgAQALxJtn1LwydGuOzcHf1FBlo=')",
    "Id": "AAMkAGI2TG9yAAABEgAQALxJtn1LwydGuOzcHf1FBlo=",
    "LastModifiedDateTime": "2014-10-22T00:30:26Z",
    "Name": "Company Party.docx",
    "ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "Size": 11647,
    "IsInline": false,
    "ContentId": null,
    "ContentLocation": null,
    "ContentBytes": "UEsDBBQABgAIAAAAIQD...AAF4pAAAAAA=="
}

Sample request ($expand on attachments)

The following example gets and expands the 2 reference attachments inline with the event properties.

GET https://outlook.office.com/api/v2.0/me/events('AAMkAGE1Mbs88AADggYEcAAA=')?$expand=attachments

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events/$entity",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAA4KZrtA==\"",
    "id": "AAMkAGE1Mbs88AADggYEcAAA=",
    "createdDateTime": "2016-03-22T22:19:58.1359352Z",
    "lastModifiedDateTime": "2016-03-22T22:39:09.9335289Z",
    "changeKey": "mODEKWhc/Um6lA3uPm7PPAAA4KZrtA==",
    "categories": [
    ],
    "originalStartTimeZone": "Pacific Standard Time",
    "originalEndTimeZone": "Pacific Standard Time",
    "responseStatus": {
        "response": "organizer",
        "time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "040000008200E00074C5B7101A82E008000000005895FCF78884D10100000000000000001000000099DD7CA6BCF37C4F9F7DAACCADDD6B89",
    "reminderMinutesBeforeStart": 15,
    "isReminderOn": true,
    "hasAttachments": true,
    "subject": "Plan Easter egg hunt!",
    "body": {
        "contentType": "html",
        "content": "<html>\r\n<body>\r\nLet's get organized for this weekend's gathering.\r\n</body>\r\n</html>\r\n"
    },
    "bodyPreview": "Let's get organized for this weekend's gathering.",
    "importance": "normal",
    "sensitivity": "normal",
    "start": {
        "dateTime": "2016-03-26T17:00:00.0000000",
        "timeZone": "UTC"
    },
    "end": {
        "dateTime": "2016-03-26T18:00:00.0000000",
        "timeZone": "UTC"
    },
    "location": {
        "displayName": "",
        "locationType": "default",
        "address": {
            "type": "unknown"
        },
        "coordinates": {
        }
    },
    "locations": [

    ],
    "isAllDay": false,
    "isCancelled": false,
    "isOrganizer": true,
    "recurrence": null,
    "responseRequested": true,
    "seriesMasterId": null,
    "showAs": "busy",
    "type": "singleInstance",
    "attendees": [
        {
            "status": {
                "response": "none",
                "time": "0001-01-01T00:00:00Z"
            },
            "type": "required",
            "emailAddress": {
                "name": "Randi Welch",
                "address": "randiw@contoso.onmicrosoft.com"
            }
        }
    ],
    "organizer": {
        "emailAddress": {
            "name": "Dana Swope",
            "address": "danas@contoso.onmicrosoft.com"
        }
    },
    "webLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1Mbs88AADggYEcAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "onlineMeetingUrl": null,
    "attachments@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events('AAMkAGE1Mbs88AADggYEcAAA%3D')/attachments",
    "attachments": [
        {
            "@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
            "id": "AAMkAGE1Mbs88AADggYEcAAABEgAQAABWAoLgP3REt_LWRG8ORv4=",
            "lastModifiedDateTime": "2016-03-22T22:27:20Z",
            "name": "Hydrangea picture",
            "contentType": null,
            "size": 412,
            "isInline": false,
            "sourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
            "providerType": "oneDriveBusiness",
            "thumbnailUrl": null,
            "previewUrl": null,
            "permission": "edit",
            "isFolder": false
        },
        {
            "@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
            "id": "AAMkAGE1Mbs88AADggYEcAAABEgAQAE1rHHth7YNLlR9WsgnODy0=",
            "lastModifiedDateTime": "2016-03-22T22:39:09Z",
            "name": "Koala picture",
            "contentType": null,
            "size": 382,
            "isInline": false,
            "sourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/koala.jpg",
            "providerType": "oneDriveBusiness",
            "thumbnailUrl": null,
            "previewUrl": null,
            "permission": "edit",
            "isFolder": false
        }
    ]
}

Sample request ($expand on nested attachment items)

The following example gets a nested attachment item.

GET https://outlook-sdf.office.com/api/v2.0/me/events/AAMkAGE1Mbs88AADUv0uFAAA=/attachments/AAMkAGE1Mbs88AADUv0uFAAABEgAQAL53d0u3BKBJmCxKVxZKBZ8=$expand=Microsoft.OutlookServices.ItemAttachment/Item

Sample response

Status code: 200

{
    "Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAL53d0u3BKBJmCxKVxZKBZ8=",
    "LastModifiedDateTime": "2017-04-25T20:05:55Z",
    "Name": "RE: Changes to GetConditionMetadata handler",
    "ContentType": null,
    "Size": 78927,
    "IsInline": false,
    "Item": {
        "Id": "",
        "Name": "How to retrieve item attachment using Outlook REST API",
        "ContentType": message/rfc822,
        "Size": 71094,
        "IsInline": false,
        "LastModifiedDateTime": "2015-09-24T05:57:59Z",
    }
}

Create attachments

You can create a file attachment or create an item attachment for an event.

• Create a file attachment
• Create an item attachment
• Create a reference attachment

Create a file attachment

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Add a file attachment to an event.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments

Required parameter	Type	Description
URL parameters
event_id	string	The event ID.
Body parameters
@odata.type	string	#Microsoft.OutlookServices.FileAttachment
Name	string	The name of the attachment.
ContentBytes	binary	The file to attach.

Response type

The new file attachment.

Create an item attachment

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Add an item attachment to an event.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments

Required parameter	Type	Description
URL parameters
event_id	string	The event ID.
Body parameters
@odata.type	string	#Microsoft.OutlookServices.ItemAttachment
Name	string	The name of the attachment.
Item	A Message, Event, or Contact entity.	The item to attach.

Response type

The new item attachment.

Create a reference attachment

Minimum required scope

https://outlook.office.com/calendars.readwrite

Add a reference attachment to an event.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments

Required parameter	Type	Description
URL parameters
event_id	String	The event ID.
Body parameters
@odata.type	String	#Microsoft.OutlookServices.ReferenceAttachment
Name	String	The display name of the attachment. Required.
SourceUrl	String	URL to get the attachment content. If this is a URL to a folder, then for the folder to be displayed correctly in Outlook or Outlook on the web, set IsFolder to true. Required.

Specify the Name and SourceUrl parameters and any writable reference attachment properties in the request body.

Response type

The reference attachment.

Sample request

The following example adds a reference attachment to an existing event. The attachment is a link to a file on OneDrive for Business.

POST https://outlook.office.com/api/v2.0/me/events('AAMkAGE1Mbs88AADggYEcAAA=')/attachments
Content-Type: application/json

{
    "@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
    "Name": "Hydrangea picture",
    "SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
    "ProviderType": "oneDriveBusiness",
    "Permission": "Edit",
    "IsFolder": "False"
 }

Sample response

Status code: 201 Created

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events('AAMkAGE1Mbs88AADggYEcAAA%3D')/attachments/$entity",
    "@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
    "Id": "AAMkAGE1Mbs88AADggYEcAAABEgAQAABWAoLgP3REt_LWRG8ORv4=",
    "LastModifiedDateTime": "2016-03-22T22:27:20Z",
    "Name": "Hydrangea picture",
    "ContentType": null,
    "Size": 412,
    "IsInline": false,
    "SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
    "ProviderType": "oneDriveBusiness",
    "ThumbnailUrl": null,
    "PreviewUrl": null,
    "Permission": "edit",
    "IsFolder": false
}

Delete attachments

• Delete an event attachment

Delete an event attachment

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Delete the specified attachment of an event. The attachment can be a file attachment or item attachment.

DELETE https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments/{attachment_id}

Required parameter	Type	Description
URL parameters
event_id	string	The event ID.
attachment_id	string	The attachment ID.

Sample request

DELETE https:/outlook.office.com/api/v2.0/me/events/AAMkAGE0MG4v1OAAA=/attachments/AAMkAGITG9yAAA=

Sample response

Status code: 204

Get reminders

Get a list of event reminders between two dates and times from a calendar.

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

GET https://outlook.office.com/api/v2.0/me/ReminderView(StartDateTime='{DateTime}',EndDateTime='{DateTime}')

Required parameter	Type	Description
Header parameters
Prefer:	outlook.timezone	The default timezone for events in the response.
URL parameters
StartDateTime	string	The starting date and time for returned reminders.
EndDateTime	string	The ending date and time for returned reminders.

Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.

See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the time zone is set to UTC.

Snooze reminders

Snooze a reminder to postpone the reminder until a new time.

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

POST https://outlook.office.com/api/v2.0/me/Events('{id}')/SnoozeReminder

Required paremeters	Type	Description
URL parameters
id	string	The ID of the event.
Body parameters
NewReminderTime	DateTimeTimeZone	The new date and time to trigger the reminder.

Dismiss reminders

Dismiss a reminder that has been triggered.

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

POST https://outlook.office.com/api/v2.0/me/Events({id})/DismissReminder

Required paremeters	Type	Description
URL parameters
id	string	The ID of the event.

Get calendars

You can get a calendar collection or get a calendar.

• Get a calendar collection
• Get a calendar

Get a calendar collection

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get all the user's calendars (calendars) or get the calendars from a specific calendar group.

GET https://outlook.office.com/api/v2.0/me/calendars
GET https://outlook.office.com/api/v2.0/me/calendargroups/{calendar_group_id}/calendars

Note

See OData query parameters for filtering, sorting, and paging parameters.

Required parameter	Type	Description
URL parameters
calender_group_id	string	The calendar group ID.

Sample request

https://outlook.office.com/api/v2.0/me/calendars

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Calendars",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Calendars('AAMkAGI2TGuLAAA=')",
            "Id": "AAMkAGI2TGuLAAA=",
            "Name": "Calendar",
            "Color": "Auto",
            "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==",
            "CanShare":true,
            "CanViewPrivateItems":true,
            "CanEdit":true,
            "Owner":{
              "Name":"Fanny Downs",
              "Address":"fannyd@adatum.onmicrosoft.com"
            }
        }
    ]
}

Get a calendar

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get a calendar by ID. You can get the user's primary calendar by using the ../me/calendar endpoint.

GET https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}

Note

See OData query parameters for filtering, sorting, and paging parameters.

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID.

Sample request

GET https://outlook.office.com/api/v2.0/me/calendars/AAMkAGI2TGuLAAA=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Calendars/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Calendars('AAMkAGI2TGuLAAA=')",
    "Id": "AAMkAGI2TGuLAAA=",
    "Name": "Calendar",
    "Color": "Auto",
    "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==",
    "CanShare":true,
    "CanViewPrivateItems":true,
    "CanEdit":true,
    "Owner":{
      "Name":"Fanny Downs",
      "Address":"fannyd@adatum.onmicrosoft.com"
    }
}

Response type

The requested calendar.

Create calendars

• Create a calendar

Create a calendar

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Create a calendar in the default calendar group by using the ../me/calendars shortcut, or in a particular calendar group by posting to the group's calendars endpoint.

POST https://outlook.office.com/api/v2.0/me/calendars
POST https://outlook.office.com/api/v2.0/me/calendargroups/{calendar_group_id}/calendars

Required parameter	Type	Description
URL parameters
calender_group_id	string	The calendar group ID, if you're getting calendars from a specific group.
Body parameters
Name	string	The name of the new calendar.

Sample request

POST https://outlook.office.com/api/v2.0/me/calendars
Content-Type: application/json

{
  "Name": "Social"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Calendars/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Calendars('AAMkAGE4xLHAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ==\"",
  "Id": "AAMkAGE4xLHAAA=",
  "Name": "Social",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ==",
  "CanShare":true,
  "CanViewPrivateItems":true,
  "CanEdit":true,
  "Owner":{
    "Name":"Fanny Downs",
    "Address":"fannyd@adatum.onmicrosoft.com"
  }
}

Response type

The new calendar.

Update calendars

• Update a calendar

Update a calendar

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Change writable properties of a calendar.

PATCH https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID.

Sample request

PATCH https://outlook.office.com/api/v2.0/me/calendars/AAMkAGE4xLIAAA=
Content-Type: application/json

{
  "Name": "Social events"
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Calendars/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Calendars('AAMkAGE4xLIAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw==\"",
  "Id": "AAMkAGE4xLIAAA=",
  "Name": "Social events",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw==",
  "CanShare":true,
  "CanViewPrivateItems":true,
  "CanEdit":true,
  "Owner":{
    "Name":"Fanny Downs",
    "Address":"fannyd@adatum.onmicrosoft.com"
  }
}

Response type

The updated calendar.

Delete calendars

• Delete a calendar

Delete a calendar

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

DELETE https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID.

Sample request

DELETE https://outlook.office.com/api/v2.0/me/calendars/AAMkAGE4xLIAAA=

Sample response

Status code: 204

Get calendar groups

You can get a calendar group collection or get a calendar group.

• Get a calendar group collection
• Get a calendar group

Note

Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut.

Get a calendar group collection

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get the calendar groups in a mailbox.

GET https://outlook.office.com/api/v2.0/me/calendargroups

Note

See OData query parameters for filtering, sorting, and paging parameters.

Sample request

GET https://outlook.office.com/api/v2.0/me/calendargroups

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/CalendarGroups",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGI2TGuKAAA=')",
            "Id": "AAMkAGI2TGuKAAA=",
            "Name": "My Calendars",
            "ClassId": "0006f0b7-0000-0000-c000-000000000046",
            "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g=="
        },
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGI2TGuMAAA=')",
            "Id": "AAMkAGI2TGuMAAA=",
            "Name": "Other Calendars",
            "ClassId": "0006f0b8-0000-0000-c000-000000000046",
            "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0/A=="
        }
    ]
}

Response type

The requested calendar group collection.

Get a calendar group

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.read
• wl.calendars
• wl.contacts_calendars

Get a calendar group by ID.

GET https://outlook.office.com/api/v2.0/me/calendargroups/{calendar_group_id}

Note

See OData query parameters for filtering, sorting, and paging parameters.

Required parameter	Type	Description
URL parameters
calendar_group_id	string	The calendar group ID.

Sample request

GET https://outlook.office.com/api/v2.0/me/calendargroups/AAMkAGI2TGuKAAA=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/CalendarGroups/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGI2TGuKAAA=')",
    "Id": "AAMkAGI2TGuKAAA=",
    "Name": "My Calendars",
    "ClassId": "0006f0b7-0000-0000-c000-000000000046",
    "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g=="
}

Response type

The requested calendar group.

Create calendar groups

Create a calendar group. Name is the only writable property for a calendar group.

• Create a calendar group

Note

Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut. You cannot create another calendar group in Outlook.com.

Create a calendar group

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

POST https://outlook.office.com/api/v2.0/me/calendargroups

Required parameter	Type	Description
URL parameter
Body parameters
Name	string	The name of the calendar group.

Sample request

POST https://outlook.office.com/api/v2.0/me/calendargroups
Content-Type: application/json

{
  "Name": "Birthdays"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGE0M4xLGAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Rw==\"",
  "Id": "AAMkAGE0M4xLGAAA=",
  "Name": "Birthdays",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Rw==",
  "ClassId": "4d969bba-8942-42a0-ae33-c7d4410d1e11"
}

Response type

The new calendar group.

Update calendar groups

• Update a calendar group

Update a calendar group

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

Change the name of a calendar group. Name is the only writable calendar group property.

PATCH https://outlook.office.com/api/v2.0/me/calendargroups/{calendar_group_id}

Required parameter	Type	Description
URL parameters
calendar_group_id	string	The calendar group ID.
Body parameters
Name	string	The name of the updated calendar group.

Sample request

PATCH https://outlook.office.com/api/v2.0/me/calendargroups/AAMkAGE0M4xLGAAA=
Content-Type: application/json

{
  "Name": "Holidays"
}

Sample response

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGE0MGM4xLGAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SA==\"",
  "Id": "AAMkAGE0MGM4xLGAAA=",
  "Name": "Holidays",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SA==",
  "ClassId": "4d969bba-8942-42a0-ae33-c7d4410d1e11"
}

Response type

The updated calendar group.

Delete calendar groups

• Delete a calendar group

Note

Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut. Do not delete this calendar group.

Delete a calendar group

Minimum required scope

One of the following:

• https://outlook.office.com/calendars.readwrite
• wl.calendars_update
• wl.events_create

DELETE https://outlook.office.com/api/v2.0/me/calendargroups/{calendar_group_id}

Required parameter	Type	Description
URL parameters
calendar_group_id	string	The calendar group ID.

Sample request

DELETE https://outlook.office.com/api/v2.0/me/calendargroups/AAMkAGE0MGM4xLGAAA=

Sample response

Status code: 204

Next steps

Whether you're ready to start building an app or just want to learn more, we've got you covered.

• Get started with Mail, Calendar, and Contacts REST APIs.
• Want samples? We've got them.

Or, learn more about using the Office 365 platform:

• Outlook REST API on the Outlook Dev Center
• Overview of developing on the Office 365 platform
• Office 365 app authentication and resource authorization
• Manually register your app with Azure AD so it can access Office 365 APIs
• Mail API reference
• Contacts API reference
• Task REST API (preview)
• OneDrive API
• Discovery Service REST API operations reference
• Resource reference for the Mail, Calendar, Contacts, and Task REST APIs