Table of contents
TOC
Collapse the table of content
Expand the table of content
Last Updated: 1/3/2018

Outlook Calendar REST API reference

This documentation covers the API for meeting rooms, multiple event locations, calendar sharing, and forwarding and cancelling events which are in preview. Preview features are subject to change prior to finalization, and may break code that uses them. Because of this, in general you should use only a production version of an API in your production code. If available, v2.0 is currently the preferred version.

Version 1.0 of the Outlook REST API is being deprecated. Beginning November 1, 2018, apps will no longer be able to use Basic Authentication with the v1.0 REST endpoint (https://outlook.office.com/api/v1.0). By November 1, 2019, the v1.0 REST endpoint will be fully decommissioned, and the v1.0 documentation will be removed shortly afterwards. Start migrating your app to use Outlook REST API in v1.0 of Microsoft Graph. See more details in our announcement.

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

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 the above listed Microsoft account domains.

Not interested in the beta version of the API? Use the control at the top right corner and select the version you want.

Not interested in v2.0 of the API? Use the control at the top right and select the version you want.

Not interested in v1.0 of the API? Use the control at the top right 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 | Get meeting rooms | Create events | Update events | Respond to events | Forward events (preview) | Delete events | Cancel events (preview) |

Get attachments | Create attachments | Delete attachments | Get reminders | Snooze reminders] | Dismiss reminders

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

Get events | Sync events | 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:

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.

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

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.

An event body can be in either text or HTML. Currently, the GET operation returns event bodies in only HTML format.


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:

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/beta/me/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}
GET https://outlook.office.com/api/beta/me/calendars/{calendar_id}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default time zone for events in the response.
URL parameters
calendar_idstringThe calendar ID, if you're getting a calendar view from a specific calendar.
start_datetimedatetimeoffsetThe date and time when the event starts.
end_datetimedatetimeoffsetThe 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/beta/me/calendarview?startDateTime=2014-10-01T01:00:00Z&endDateTime=2014-10-31T23:00:00Z&$select=Subject

Response type

The expanded events within the specified time range.

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 parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default time zone for events in the response.
URL parameters
calendar_idstringThe calendar ID, if you're getting a calendar view from a specific calendar.
start_datetimedatetimeoffsetThe date and time when the event starts.
end_datetimedatetimeoffsetThe 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 https://outlook.office.com/api/v1.0/me/calendarview?start={start_datetime}&end={end_datetime}
GET https://outlook.office.com/api/v1.0/me/calendars/{calendar_id}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID, if you're getting a calendar view from a specific calendar.
start_datetimedatetimeoffsetThe date and time when the event starts.
end_datetimedatetimeoffsetThe date and time when the event ends.

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:

GET https://outlook.office.com/api/v1.0/me/calendarview?startDateTime=2014-10-01T01:00:00Z&endDateTime=2014-10-31T23:00:00Z&$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:

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/beta/me/events
GET https://outlook.office.com/api/beta/me/calendars/{calendar_id}/events
Required parameterTypeDescription
_Header parameters
Prefer:outlook.timezoneThe default time zone for events in the response.
URL parameters
calendar_idstringThe 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, 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 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/beta/me/events?$select=Subject,Organizer,Start,End,Location,Locations 

Sample response

Status code: 200

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer,Start,End,Location,Locations)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/Events('AAMkADNWAACYBXsvAAA=')",
            "@odata.etag":"W/\"SuFHwDRP1EeXJUopWbSLlgAAmBvk2g==\"",
            "Id":"AAMkADNWAACYBXsvAAA=",
            "Subject":"Plan summer company picnic",
            "Start":{
                "DateTime":"2017-06-09T18:00:00.0000000",
                "TimeZone":"UTC"
            },
            "End":{
                "DateTime":"2017-06-09T19:00:00.0000000",
                "TimeZone":"UTC"
            },
            "Location":{
                "DisplayName":"Conf Room 3; Fourth Coffee; Home Office",
                "LocationType":"Default"
            },
            "Locations":[
                {
                    "DisplayName":"Conf Room 3",
                    "LocationType":"Default"
                },
                {
                    "DisplayName":"Fourth Coffee",
                    "LocationType":"Default",
                    "Address":{
                        "Type":"Unknown",
                        "Street":"4567 Main St",
                        "City":"Redmond",
                        "State":"WA",
                        "CountryOrRegion":"US",
                        "PostalCode":"32008"
                    },
                    "Coordinates":{
                        "Latitude":47.672,
                        "Longitude":-102.103
                    }
                },
                {
                    "DisplayName":"Home Office",
                    "LocationType":"Default"
                }
            ],
            "Organizer":{
                "EmailAddress":{
                    "Name":"Alex Wilbur",
                    "Address":"AlexW@contoso.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/Events('AAMkADNPkvzAAA=')",
            "@odata.etag":"W/\"SuFHwDRP1EeXJUopWbSLlgAAdE6yjA==\"",
            "Id":"AAMkADNPkvzAAA=",
            "Subject":"Customer visit",
            "Start":{
                "DateTime":"2017-04-20T21:00:00.0000000",
                "TimeZone":"UTC"
            },
            "End":{
                "DateTime":"2017-04-20T23:00:00.0000000",
                "TimeZone":"UTC"
            },
            "Location":{
                "DisplayName":"",
                "LocationType":"Default",
                "Address":{
                    "Type":"Unknown"
                },
                "Coordinates":{

                }
            },
            "Locations":[

            ],
            "Organizer":{
                "EmailAddress":{
                    "Name":"Alex Wilbur",
                    "Address":"AlexW@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}
GET https://outlook.office.com/api/v2.0/me/events
GET https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}/events
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default time zone for events in the response.
URL parameters
calendar_idstringThe 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 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 https://outlook.office.com/api/v1.0/me/events
GET https://outlook.office.com/api/v1.0/me/calendars/{calendar_id}/events
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID, if you're getting events from a specific calendar.

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 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/v1.0/me/events?$select=Subject,Organizer,Start,End

Sample response

Status code: 200

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

Get event instances

Minimum required scope: one of the following:

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/beta/me/events/{event_id}/instances?startDateTime={start_datetime}&endDateTime={end_datetime}
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default timezone for events in the response.
URL parameters
event_idstringThe event ID.
start_datetimedatetimeoffsetThe UTC date and time when the event starts.
end_datetimedatetimeoffsetThe 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/beta/me/events/AAMkAGE0MGM1Y2M5LWEAAA=/instances?startDateTime=2014-10-01T01:00:00Z&endDateTime=2014-10-31T23:00:00Z&$select=Subject,Start,End
GET https://outlook.office.com/api/v2.0/me/events/{event_id}/instances?startDateTime={start_datetime}&endDateTime={end_datetime}
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default time zone for events in the response.
URL parameters
event_idstringThe event ID.
start_datetimedatetimeoffsetThe UTC date and time when the event starts.
end_datetimedatetimeoffsetThe 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 https://outlook.office.com/api/v1.0/me/events/{event_id}/instances?startDateTime={start_datetime}&endDateTime={end_datetime}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
start_datetimedatetimeoffsetThe UTC date and time when the event starts.
end_datetimedatetimeoffsetThe UTC date and time when the event ends.

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/v1.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:

Get an event by ID.

GET https://outlook.office.com/api/beta/me/events/{event_id}
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default timezone for events in the response.
URL parameters
event_idstringThe 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/beta/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",
        },
        "Locations":[
            {
                "DisplayName": "Alex's Office",
            }
        ]
        "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/beta/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"
            }
        }
    }
GET https://outlook.office.com/api/v2.0/me/events/{event_id}
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default time zone for events in the response.
URL parameters
event_idstringThe 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"
            }
        }
    }
GET https://outlook.office.com/api/v1.0/me/events/{event_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Sample request

GET https://outlook.office.com/api/v1.0/me/events/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9xAAA=')",
    "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x49w==\"",
    "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=",
    "DateTimeCreated": "2014-10-19T23:13:47.3959685Z",
    "DateTimeLastModified": "2014-10-23T20:23:47.0735997Z",
    "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x49w==",
    "Categories": [],
    "StartTimeZone": "Pacific Standard Time",
    "EndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "040000008200E00074C5B7101A82E0080000000005F3F755F2EBCF010000000000000000100000007547017C91509D42A5B60C97141AA3DD",
    "Reminder": 15,
    "HasAttachments": false,
    "Subject": "Weekly Meeting on 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"
    },
    "BodyPreview": "Setting up some time to review the budget and planning on the Contoso Project",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": "2014-10-13T21:00:00Z",
    "End": "2014-10-13T22:00:00Z",
    "Location": {
        "DisplayName": "Alex's Office"
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": {
        "Pattern": {
            "Type": "Weekly",
            "Interval": 1,
            "Month": 0,
            "DayOfMonth": 0,
            "DaysOfWeek": [
                "Monday"
            ],
            "FirstDayOfWeek": "Sunday",
            "Index": "First"
        },
        "Range": {
            "Type": "NoEnd",
            "StartDate": "2014-10-13T00:00:00-07:00",
            "EndDate": "0001-01-01T00:00:00Z",
            "NumberOfOccurrences": 0
        }
    },
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SeriesMaster",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Janet Schorr",
                "Address": "janets@a830edad9050849NDA1.onmicrosoft.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Pavel Bansky",
                "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Alex D",
            "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com"
        }
    }

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/v1.0/me/events/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=?$select=Subject,Organizer,Start,End

Sample response

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

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

Sync events

Minimum required scope: one of the following:

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/beta/{user_context}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}

Second request, or first request of a subsequent round:

GET https://outlook.office.com/api/beta/{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/beta/{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/beta/{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/beta/{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/beta/{user_context}/calendars('{calendar_id}')/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}&$skiptoken={skip_token}

Parameters

ParameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default timezone for events in the response.
URL parameters
user_contextstringThe 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_idstringThe calendar ID, if you're getting a calendar view from a specific calendar.
start_datetimedatetimeoffsetThe date and time when the event starts.
end_datetimedatetimeoffsetThe date and time when the event ends.
delta_tokenstringThe deltaToken string returned as part of the value for @odata.deltaLink in the previous sync response.
skip_tokenstringThe skipToken string returned as part of the value for @odata.nextLink in the previous sync response.

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

  • 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/beta/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
    Prefer: outlook.timezone="Pacific Standard Time"

Sample initial response data

Preference-Applied: odata.track-changes

    {
        "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarView",
        "value": [
            {
                "@odata.id": "https://outlook.office.com/api/beta/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":"",
                    "LocationType":"Default",
                    "Address":{
                        "Type":"Unknown"
                    },
                    "Coordinates":{

                    }
                },
                "Locations":[

                ],
                "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/beta/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/beta/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
    Prefer: outlook.timezone="Pacific Standard Time"

Sample second response data

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarView/$delta",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/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":"",
                "LocationType":"Default",
                "Address":{
                    "Type":"Unknown"
                },
                "Coordinates":{

                }
            },
            "Locations":[

            ],
            "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/beta/me/calendarview/?startdatetime=2015-01-01T00%3a00%3a00Z&enddatetime=2015-08-10T00%3a00%3a00Z&%24skipToken=530c9d02ae1a4d96804538bd4d381546"
}

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

ParameterTypeDescription
URL parameters
user_contextstringThe 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_idstringThe calendar ID, if you're getting a calendar view from a specific calendar.
start_datetimedatetimeoffsetThe date and time when the event starts.
end_datetimedatetimeoffsetThe date and time when the event ends.
delta_tokenstringThe deltaToken string returned as part of the value for @odata.deltaLink in the previous sync response.
skip_tokenstringThe 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"
}

To sync in the default calendar

Initial request:

GET https://outlook.office.com/api/v1.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/v1.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/v1.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/v1.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/v1.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/v1.0/{user_context}/calendars('{calendar_id}')/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}&$skiptoken={skip_token}

Parameters

ParameterTypeDescription
URL parameters
user_contextstringThe 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_idstringThe calendar ID, if you're getting a calendar view from a specific calendar.
start_datetimedatetimeoffsetThe date and time when the event starts.
end_datetimedatetimeoffsetThe date and time when the event ends.
delta_tokenstringThe deltaToken string returned as part of the value for @odata.deltaLink in the previous sync response.
skip_tokenstringThe 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/v1.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/v1.0/$metadata#Me/CalendarView",
        "value": [
            {
                "@odata.id": "https://outlook.office.com/api/v1.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": "2015-04-05T18:00:00Z",
                "StartTimeZone": "Pacific Standard Time",
                "End": "2015-04-05T19:00:00Z",
                "EndTimeZone": "Pacific Standard Time",
                "Reminder": 15,
                "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,
                "Organizer": {
                    "EmailAddress": {
                        "Address": "user0@contoso.com",
                        "Name": "user0"
                    }
                },
                "iCalUId": "040000008200E9888E07599CCFA23",
                "WebLink": "https://outlook.office.com/owa/?ItemID=AAAINJAAAAA%3D%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory"
            }
        ],
        "@odata.deltaLink": "https://outlook.office.com/api/v1.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/v1.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/v1.0/$metadata#Me/CalendarView/$delta",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v1.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": "2015-04-16T18:00:00Z",
            "StartTimeZone": "Pacific Standard Time",
            "End": "2015-04-16T19:00:00Z",
            "EndTimeZone": "Pacific Standard Time",
            "Reminder": 15,
            "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,
            "Organizer": {
                "EmailAddress": {
                    "Address": "user0@contoso.com",
                    "Name": "user0"
                }
            },
            "iCalUId": "040000008200E09BB89A316862",
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADNkNmVlOAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory"
        }
    ],
    "@odata.nextLink": "https://outlook.office.com/api/v1.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:

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.

ParameterTypeDescriptionRequired?
AttendeesCollection(AttendeeBase)Attendees or resources for the meeting. An empty collection causes FindMeetingTimes to look for free time slots for only the organizer.Optional
IsOrganizerOptionalEdm.BooleanSpecify true if the organizer doesn't necessarily have to attend. The default is false.Optional
LocationConstraintLocationConstraintThe 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
MaxCandidatesEdm.Int32The maximum number of meeting suggestions to return in the response.Optional
MeetingDurationEdm.DurationThe 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
MinimumAttendeePercentageEdm.DoubleThe minimum required confidence for a time slot to be returned in the response. It is a % value ranging from 0 to 100.Optional
ReturnSuggestionReasonsEdm.BooleanSpecify true to return a reason for each meeting suggestion in the SuggestionReason property. The default is false to not return that property.Optional
TimeConstraintTimeConstraintAny 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 TimeConstraintSuggestions for meeting times
WorkSuggestions 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 set for the mailbox. This is the default value if no ActivityDomain is specified.
PersonalSuggestions are within the user's work hours, and Saturday and Sunday. The default is Monday to Sunday, 8am to 5pm, in the time zone setting for the mailbox.
UnrestrictedSuggestions can be from all hours of a day, all days of a week.
UnknownDo 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 as described below:

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 of the requested meeting time range, and the requested length of time.

POST https://outlook.office.com/api/beta/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/beta/$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",
                    "LocationType": "Default"
                }
            ]
        },
        {
            "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",
                    "LocationType": "Default"
                }
            ]
        }
    ],
    "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/beta/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/beta/$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"
                    "LocationType": "Default"
                }
            ],
            "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/beta/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/beta/$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 2 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/beta/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/beta/$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"
               "LocationType": "Default"
            }
         ],
         "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"
               "LocationType": "Default"
            }
         ],
         "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 1-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/beta/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/beta/$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": ""
}

Minimum required scope: one of the following:

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.

ParameterTypeDescriptionRequired?
AttendeesCollection(AttendeeBase)Attendees or resources for the meeting. An empty collection causes FindMeetingTimes to look for free time slots for only the organizer.Optional
IsOrganizerOptionalEdm.BooleanSpecify true if the organizer doesn't necessarily have to attend. The default is false.Optional
LocationConstraintLocationConstraintThe 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
MaxCandidatesEdm.Int32The maximum number of meeting suggestions to return in the response.Optional
MeetingDurationEdm.DurationThe 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
MinimumAttendeePercentageEdm.DoubleThe minimum required confidence for a time slot to be returned in the response. It is a % value ranging from 0 to 100.Optional
ReturnSuggestionReasonsEdm.BooleanSpecify true to return a reason for each meeting suggestion in the SuggestionReason property. The default is false to not return that property.Optional
TimeConstraintTimeConstraintAny 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 TimeConstraintSuggestions for meeting times
WorkSuggestions 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.
PersonalSuggestions 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.
UnrestrictedSuggestions can be from all hours of a day, all days of a week.
UnknownDo 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 as described below:

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 2 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 1-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": ""
}

This feature is currently available in v2.0 and beta. To find out more, use the control in the top right corner of the article and select one of these versions.


Get meeting rooms (preview)

In Outlook, a tenant can organize meeting rooms into room lists. Each meeting room and room list is represented by an EmailAddress instance.

Get room lists (preview) | Get rooms (preview)

Get room lists (preview)

Minimum required scope: one of the following:

  • User.Read.All
  • User.ReadBasic.All_

Get the room lists defined in a tenant.

GET https://outlook.office.com/api/beta/me/findroomlists

Response type

Collection of EmailAddress instances. If no lists are defined in the tenant, then an empty array is returned.

Sample request

GET https://outlook.office.com/api/beta/me/findroomlists

Sample response

Status code: 200 

{
  "@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.EmailAddress)",
  "value":[
    {
      "Name":"Building 1 Rooms",
      "Address":"Building1Rooms@contoso.onmicrosoft.com"
    },
    {
      "Name":"Building 2 Rooms",
      "Address":"Building2Rooms@contoso.onmicrosoft.com"
    }
  ]
}

Get rooms (preview)

Minimum required scope: one of the following:

  • User.Read.All
  • User.ReadBasic.All

You can get all the meeting rooms defined in the user's tenant, or get the meeting rooms in a specific room list.

Note These operations return up to the first 100 rooms in a tenant.

To get all the rooms in the user's tenant:

GET https://outlook.office.com/api/beta/me/findrooms

To get the rooms in a specified room list:

GET https://outlook.office.com/api/beta/me/findrooms(roomlist='{room_list}') 
Optional parameterTypeDescription
Function parameter
room_liststringThe SMTP address associated with the room list. Each room list is represented by an EmailAddress instance that includes an SMTP address.

Response type

Collection of EmailAddress instances.

Sample request

The following example gets the rooms defined in the signed-in user's tenant.

GET https://outlook.office.com/api/beta/me/findrooms 

Sample response

Status code: 200 

{
  "@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.EmailAddress)",
  "value":[
    {
      "Name":"Conf Room Adams",
      "Address":"Adams@contoso.onmicrosoft.com"
    },
    {
      "Name":"Conf Room Baker",
      "Address":"Baker@contoso.onmicrosoft.com"
    },
    {
      "Name":"Conf Room Crystal",
      "Address":"Crystal@contoso.onmicrosoft.com"
    },
    {
      "Name":"Conf Room Hood",
      "Address":"Hood@contoso.onmicrosoft.com"
    },
    {
      "Name":"Conf Room Rainier",
      "Address":"Rainier@contoso.onmicrosoft.com"
    },
    {
      "Name":"Conf Room Stevens",
      "Address":"Stevens@contoso.onmicrosoft.com"
    },
    {
      "Name":"SurfaceHub",
      "Address":"SurfaceHub@contoso.onmicrosoft.com"
    }
  ]
}

Sample request

The following example gets the rooms in the specified room list identified by the email address Building2Rooms@contoso.onmicrosoft.com.

GET https://outlook.office.com/api/beta/me/findrooms(roomlist='Building2Rooms@contoso.onmicrosoft.com') 

Sample response

Status code: 200 

{
  "@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.EmailAddress)",
  "value":[
    {
      "Name":"Conf Room Baker",
      "Address":"Baker@contoso.onmicrosoft.com"
    },
    {
      "Name":"Conf Room Hood",
      "Address":"Hood@contoso.onmicrosoft.com"
    },
    {
      "Name":"Conf Room Rainier",
      "Address":"Rainier@contoso.onmicrosoft.com"
    }
  ]
}

This feature is currently available in beta. To find out more, use the control in the top right corner of the article and select beta.

This feature is currently available in beta. To find out more, use the control in the top right corner of the article and select beta.


Create events

Create a calendar event

Create a calendar event

Minimum required scope: one of the following:

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 send invitations to all attendees.

POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/calendars/{calendar_id}/events
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

The following example creates an event for the organizer and attendees to participate from 3 different locations.

POST https://outlook.office.com/api/beta/me/events
Content-Type: application/json
{
  "Subject": "Plan summer company picnic",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's kick-start this event planning!"
  },
  "Start": {
      "DateTime": "2017-06-09T11:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2017-06-09T12:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "AdeleV@contoso.onmicrosoft.com",
        "Name": "Adele Vance"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "AlexW@contoso.onmicrosoft.com",
        "Name": "Alex Wilber"
      },
      "Type": "Required"
    }
  ],
  "Location": {
    "DisplayName": "Conf Room 3; Fourth Coffee; Home Office",
    "LocationType": "Default"
  },
  "Locations": [
    {
      "DisplayName": "Conf Room 3",
    },
    {
      "DisplayName": "Fourth Coffee",
      "Address": {
        "Street": "4567 Main St",
        "City": "Redmond",
        "State": "WA",
        "CountryOrRegion": "US",
        "PostalCode": "32008"
      },
      "Coordinates": {
        "Latitude": 47.672,
        "Longitude": -102.103
      },
      "LocationType": "LocalBusiness"
    },
    {
      "DisplayName": "Home Office",
    }
  ]

}

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('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/Events('AAMkADNCYBXsvAAA=')",
    "@odata.etag":"W/\"SuFHwDRP1EeXJUopWbSLlgAAmBvk2g==\"",
    "Id":"AAMkADNCYBXsvAAA=",
    "CreatedDateTime":"2017-06-06T19:59:23.003773-07:00",
    "LastModifiedDateTime":"2017-06-06T19:59:24.8432785-07:00",
    "ChangeKey":"SuFHwDRP1EeXJUopWbSLlgAAmBvk2g==",
    "Categories":[

    ],
    "OriginalStartTimeZone":"Pacific Standard Time",
    "OriginalEndTimeZone":"Pacific Standard Time",
    "iCalUId":"040000008200E00074C5B7101A82E008000000000FD9CB103ADFD20100000000000000001000000026DB266A0E3C4A4FB15DC14FFFB1469D",
    "ReminderMinutesBeforeStart":15,
    "IsReminderOn":true,
    "HasAttachments":false,
    "Subject":"Plan summer company picnic",
    "BodyPreview":"Let's kick-start this event planning!",
    "Importance":"Normal",
    "Sensitivity":"Normal",
    "IsAllDay":false,
    "IsCancelled":false,
    "IsOrganizer":true,
    "ResponseRequested":true,
    "SeriesMasterId":null,
    "ShowAs":"Busy",
    "Type":"SingleInstance",
    "WebLink":"https://outlook.office365.com/owa/?itemid=AAMkADNCYBXsvAAA%3D&exvsurl=1&path=/calendar/item",
    "OnlineMeetingUrl":null,
    "ResponseStatus":{
        "Response":"Organizer",
        "Time":"0001-01-01T00:00:00Z"
    },
    "Body":{
        "ContentType":"HTML",
        "Content":"<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's kick-start this event planning!\r\n</body>\r\n</html>\r\n"
    },
    "Start":{
        "DateTime":"2017-06-09T11:00:00.0000000",
        "TimeZone":"Pacific Standard Time"
    },
    "End":{
        "DateTime":"2017-06-09T12:00:00.0000000",
        "TimeZone":"Pacific Standard Time"
    },
    "Location":{
        "DisplayName":"Conf Room 3; Fourth Coffee; Home Office",
        "LocationType":"Default"
    },
    "Locations":[
        {
            "DisplayName":"Conf Room 3",
            "LocationType":"Default"
        },
        {
            "DisplayName":"Fourth Coffee",
            "LocationType":"Default",
            "Address":{
                "Type":"Unknown",
                "Street":"4567 Main St",
                "City":"Redmond",
                "State":"WA",
                "CountryOrRegion":"US",
                "PostalCode":"32008"
            },
            "Coordinates":{
                "Latitude":47.672,
                "Longitude":-102.103
            }
        },
        {
            "DisplayName":"Home Office",
            "LocationType":"Default"
        }
    ],
    "Recurrence":null,
    "Attendees":[
        {
            "Type":"Required",
            "Status":{
                "Response":"None",
                "Time":"0001-01-01T00:00:00Z"
            },
            "EmailAddress":{
                "Name":"Adele Vance",
                "Address":"AdeleV@contoso.onmicrosoft.com"
            }
        },
        {
            "Type":"Required",
            "Status":{
                "Response":"None",
                "Time":"0001-01-01T00:00:00Z"
            },
            "EmailAddress":{
                "Name":"Alex Wilber",
                "Address":"AlexW@contoso.onmicrosoft.com"
            }
        }
    ],
    "Organizer":{
        "EmailAddress":{
            "Name":"Fanny Downs",
            "Address":"fannyd@contoso.onmicrosoft.com"
        }
    },
    "OnlineMeeting":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/beta/me/events?$Select=Start,End
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}/events
Required parameterTypeDescription
URL parameters
calendar_idstringThe 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

By default, the Start and End time values are in UTC. You can specify time zones for Start and End, express the time in the corresponding time zone, and include a time offset from UTC. The example below shows how to assign time values in Pacific Standard Time. Note that if you specify one time zone, you must specify a value for the other one as well.

POST https://outlook.office.com/api/v1.0/me/events
POST https://outlook.office.com/api/v1.0/me/calendars/{calendar_id}/events
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

POST https://outlook.office.com/api/v1.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": "2014-02-02T18:00:00-08:00",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-02-02T19:00:00-08:00",
  "EndTimeZone": "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/v1.0/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeNheA==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1RAAA=",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeNheA==",
  "Categories": [],
  "DateTimeCreated": "2014-01-22T20:56:10.1058291Z",
  "DateTimeLastModified": "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": "2014-02-02T18:00:00-08:00",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-02-02T19:00:00-08:00",
  "EndTimeZone": "Pacific Standard Time",
  "Location": {
    "DisplayName": ""
  },
  "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,
  "Organizer": {
    "EmailAddress": {
      "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "alexd"
    }
  }
}

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/v1.0/me/events?$Select=Start,End

Update events

Update a calendar event

Update a calendar event

Minimum required scope: one of the following:

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/beta/me/events/{event_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Specify any writable event properties in the request body.

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

Sample request

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

{
  "Location": {
    "DisplayName": "Conference Rome",
    "LocationType": "ConferenceRoom"
  }
}

Sample response

Status code: 200

{
  "@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('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": "Conference Rome",
    "LocationType": "ConferenceRoom"
  },
  "Locations":[
    {
      "DisplayName":"Conference Rome",
      "LocationType":"ConferenceRoom"
    }
  ],
  "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/{event_id}
Required parameterTypeDescription
URL parameters
event_idstringThe 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
PATCH https://outlook.office.com/api/v1.0/me/events/{event_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Specify any writable event properties in the request body.

Sample request

PATCH https://outlook.office.com/api/v1.0/me/events/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA=
Content-Type: application/json
{
  "Location": {
    "DisplayName": "Your office"
  }
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA=",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==",
  "Categories": [],
  "DateTimeCreated": "2014-01-22T20:49:05.5657528Z",
  "DateTimeLastModified": "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": "2014-02-02T18:00:00-08:00",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-02-02T19:00:00-08:00",
  "EndTimeZone": "Pacific Standard Time",
  "Location": {
    "DisplayName": "Your office"
  },
  "ShowAs": "Busy",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": true,
  "ResponseRequested": true,
  "Type": "SingleInstance",
  "SeriesMasterId": null,
  "Attendees": [],
  "Recurrence": null,
  "Organizer": {
    "EmailAddress": {
      "Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "alexd"
    }
  }
}

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/v1.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:

Accept the specified event.

POST https://outlook.office.com/api/beta/me/events/{event_id}/accept
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/beta/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.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/accept
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue 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.

POST https://outlook.office.com/api/v1.0/me/events/{event_id}/accept
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/v1.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:

Tentatively accept the specified event.

POST https://outlook.office.com/api/beta/me/events/{event_id}/tentativelyaccept
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/beta/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.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/tentativelyaccept
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue 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.

POST https://outlook.office.com/api/v1.0/me/events/{event_id}/tentativelyaccept
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/v1.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:

Decline invitation to the specified event.

POST https://outlook.office.com/api/beta/me/events/{event_id}/decline
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/beta/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.

POST https://outlook.office.com/api/v2.0/me/events/{event_id}/decline
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue 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.

POST https://outlook.office.com/api/v1.0/me/events/{event_id}/decline
ParameterTypeDescription
URL parameters
event_idstringThe event ID. Required.
Body parameters
CommentstringText included in the response. Optional.
SendResponsebooleantrue if a response is to be sent to the organizer; otherwise, false. Optional. Default is true.

Sample request

POST https://outlook.office.com/api/v1.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)

Minimum required scope: one of the following:

This action allows the organizer or attendee of a meeting event to forward the meeting request to a new recipient.

If the meeting event is forwarded from an Office 365 mailbox to another recipient, this action also sends a message to notify the organizer of the forwarding, and adds the recipient to the organizer's copy of the meeting event. This convenience is not available when forwarding from an Outlook.com account.

POST https://outlook.office.com/api/beta/me/events('{event_id}')/forward
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
Body parameters
CommentstringA comment to include. Can be an empty string.
ToRecipientsCollection(Recipient)The list of recipients to forward the event to.

Sample request

POST https://outlook.office.com/api/beta/me/events('AQMkADJmMTU4AAAA=')/forward

Content-Type: application/json
{
  "ToRecipients":[
      {
        "EmailAddress": {
          "Address":"danas@contoso.onmicrosoft.com",
          "Name":"Dana Swope"
        }
      }
     ],
  "Comment": "Dana, hope you can make this meeting." 
}

Sample response

Status code: 202 Accepted

This feature is currently available in only the beta version. To find out more, use the control in the top right corner of the article and select beta.

This feature is currently available in only the beta version. To find out more, use the control in the top right corner of the article and select beta.


Delete events

Delete a calendar event

Delete a calendar event

Minimum required scope: one of the following:

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.

This action differs from Cancel in that Delete is available to the organizer and attendees of the meeting. If the signed-user is the meeting organizer, the user simply cancels the meeting without providing a custom cancellation message to the attendees.

DELETE https://outlook.office.com/api/beta/me/events/{event_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Sample request

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

Sample response

Status code: 204
DELETE https://outlook.office.com/api/v2.0/me/events/{event_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Sample request

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

Sample response

Status code: 204
DELETE https://outlook.office.com/api/v1.0/me/events/{event_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Sample request

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

Sample response

Status code: 204 

Cancel events (preview)

Minimum required scope: one of the following:

This action allows the organizer of a meeting to send a cancellation message and cancel the event.

The action moves the event to the Deleted Items folder. The organizer can also cancel an occurrence of a recurring meeting by providing the occurrence event ID. An attendee calling this action gets an error (HTTP 400 Bad Request), with the following error message:

"Your request can't be completed. You need to be an organizer to cancel a meeting."

This action differs from Delete in that Cancel is available to only the organizer, and lets the organizer send a custom message to the attendees about the cancellation.

POST https://outlook.office.com/api/beta/me/events/{event_id}/Cancel
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
Body parameters
CommentstringA comment about the cancellation sent to all the attendees.

Sample request

POST https://outlook.office.com/api/beta/me/events/AAMkAGE0M4v1OAAA=/Cancel

Content-Type: application/json
{
  "Comment": "Cancelling this meeting as there is a time conflict for most folks."
}

Sample response

Status code: 202

This feature is currently available in only the beta version. To find out more, use the control in the top right corner of the article and select beta.

This feature is currently available in only the beta version. To find out more, use the control in the top right corner of the article and select beta.



Get attachments

You can get an attachement collection or get an attachment.

Get an attachment collection | Get an attachment

Get an attachment collection

Minimum required scope: one of the following:

Get the attachments from a particular event.

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

GET https://outlook.office.com/api/beta/me/events/{event_id}/attachments
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Response type

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

Sample request

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

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGI2NG9yAAA%3D')/Attachments",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.FileAttachment",
            "@odata.id": "https://outlook.office.com/api/beta/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 https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments
Required parameterTypeDescription
URL parameters
event_idstringThe 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 https://outlook.office.com/api/v1.0/me/events/{event_id}/attachments
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.

Response type

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

Sample request

GET https://outlook.office.com/api/v1.0/me/events/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA=/attachments

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA%3D')/Attachments",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.FileAttachment",
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2NGTG9yAAA=')/Attachments('AAMkAGI2NGLwydGuOzcHf1FBlo=')",
            "Id": "AAMkAGI2NGLwydGuOzcHf1FBlo=",
            "DateTimeLastModified": "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=="
            "IsContactPhoto": false
        }
    ]
}

Get an attachment

Minimum required scope: one of the following:

Get an attachment from a particular event.

GET https://outlook.office.com/api/beta/me/events/{event_id}/attachments/{attachment_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
attachment_idstringThe attachment ID.

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

Response type

The requested file attachment, item attachment, or reference attachment.

Sample request

The following example gets the file attached to a specific event.

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

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGI2WRAAADTG9yAAA%3D')/Attachments/$entity",
    "@odata.type": "#Microsoft.OutlookServices.FileAttachment",
    "@odata.id": "https://outlook.office.com/api/beta/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 (reference attachment)

The following example gets the reference attachment of an event.

GET https://outlook.office.com/api/beta/me/events('AAMkAGE1Mbs88AADggYEcAAA=')/attachments('AAMkAGE1Mbs88AADggYEcAAABEgAQAABWAoLgP3REt_LWRG8ORv4=')

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$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
}

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/beta/me/events('AAMkAGE1Mbs88AADggYEcAAA=')?$expand=attachments

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$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/beta/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",
    }
}
GET https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments/{attachment_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
attachment_idstringThe 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",
    }
}
GET https://outlook.office.com/api/v1.0/me/events/{event_id}/attachments/{attachment_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
attachment_idstringThe 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/v1.0/me/events/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA=/attachments/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAABEgAQALxJtn1LwydGuOzcHf1FBlo=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA%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="
    "DateTimeLastModified": "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==",
    "IsContactPhoto": false
}

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:

Add a file attachment to an event.

POST https://outlook.office.com/api/beta/me/events/{event_id}/attachments
POST https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments
POST https://outlook.office.com/api/v1.0/me/events/{event_id}/attachments
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
Body parameters
@odata.typestring#Microsoft.OutlookServices.FileAttachment
NamestringThe name of the attachment.
ContentBytesbinaryThe file to attach.

Response type

The new file attachment.


Create an item attachment

Minimum required scope: one of the following:

Add an item attachment to an event.

POST https://outlook.office.com/api/beta/me/events/{event_id}/attachments
POST https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments
POST https://outlook.office.com/api/v1.0/me/events/{event_id}/attachments
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
Body parameters
@odata.typestring#Microsoft.OutlookServices.ItemAttachment
NamestringThe name of the attachment.
ItemA 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/beta/me/events/{event_id}/attachments
Required parameterTypeDescription
URL parameters
event_idStringThe event ID.
Body parameters
@odata.typeString#Microsoft.OutlookServices.ReferenceAttachment
NameStringThe display name of the attachment. Required.
SourceUrlStringURL 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/beta/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/beta/$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
}
POST https://outlook.office.com/api/v2.0/me/events/{event_id}/attachments
Required parameterTypeDescription
URL parameters
event_idStringThe event ID.
Body parameters
@odata.typeString#Microsoft.OutlookServices.ReferenceAttachment
NameStringThe display name of the attachment. Required.
SourceUrlStringURL 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
}

This feature is currently available in only the beta version. To find out more, use the control in the top right corner of the article and select beta.


Delete attachments

Delete attachments of an event.

Delete an event attachment

Delete an event attachment

Minimum required scope: one of the following:

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

DELETE https://outlook.office.com/api/beta/me/events/{event_id}/attachments/{attachment_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
attachment_idstringThe attachment ID.

Sample request

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

Sample response

Status code: 204

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 parameterTypeDescription
URL parameters
event_idstringThe event ID.
attachment_idstringThe attachment ID.

Sample request

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

Sample response

Status code: 204

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

DELETE https://outlook.office.com/api/v1.0/me/events/{event_id}/attachments/{attachment_id}
Required parameterTypeDescription
URL parameters
event_idstringThe event ID.
attachment_idstringThe attachment ID.

Sample request

DELETE https:/outlook.office.com/api/v1.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:

GET https://outlook.office.com/api/beta/me/ReminderView(StartDateTime='{DateTime}',EndDateTime='{DateTime}')
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default timezone for events in the response.
URL parameters
StartDateTimestringThe starting date and time for returned reminders.
EndDateTimestringThe 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.

GET https://outlook.office.com/api/v2.0/me/ReminderView(StartDateTime='{DateTime}',EndDateTime='{DateTime}')
Required parameterTypeDescription
Header parameters
Prefer:outlook.timezoneThe default timezone for events in the response.
URL parameters
StartDateTimestringThe starting date and time for returned reminders.
EndDateTimestringThe 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.

This feature is available in only the beta and v2.0 versions. To find out more, use the control in the top right corner of the article and select v2.0 or beta.

Snooze reminders

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

Minimum required scope: one of the following:

POST https://outlook.office.com/api/beta/me/Events('{id}')/SnoozeReminder
Required paremetersTypeDescription
URL parameters
idstringThe ID of the event.
Body parameters
NewReminderTimeDateTimeTimeZoneThe new date and time to trigger the reminder.
POST https://outlook.office.com/api/beta/me/Events('{id}')/SnoozeReminder
Required paremetersTypeDescription
URL parameters
idstringThe ID of the event.
Body parameters
NewReminderTimeDateTimeTimeZoneThe new date and time to trigger the reminder.

This feature is available in only the beta and v2.0 versions. To find out more, use the control in the top right corner of the article and select v2.0 or beta.

Dismiss reminders

Dissmiss a reminder that has been triggered.

Minimum required scope: one of the following:

POST https://outlook.office.com/api/beta/me/Events({id})/DismissReminder
Required paremetersTypeDescription
URL parameters
idstringThe ID of the event.
POST https://outlook.office.com/api/beta/me/Events({id})/DismissReminder
Required paremetersTypeDescription
URL parameters
idstringThe ID of the event.

This feature is available in only the beta and v2.0 versions. To find out more, use the control in the top right corner of the article and select v2.0 or beta.

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:

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

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

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

Required parameterTypeDescription
URL parameters
calender_group_idstringThe calendar group ID.

Sample request

GET https://outlook.office.com/api/beta/me/calendars

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Calendars",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Calendars('AAMkAGI2TGuLAAA=')",
            "Id": "AAMkAGI2TGuLAAA=",
            "Name": "Calendar",
            "Color": "Auto",
            "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==",
            "IsDefaultCalendar": true,
            "CanShare":true,
            "CanViewPrivateItems":true,
            "IsShared":false,
            "IsSharedWithMe":false,
            "CanEdit":true,
            "Owner":{
                "Name":"Fanny Downs",
                "Address":"fannyd@adatum.onmicrosoft.com"
            }
        }
    ]
}
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 parameterTypeDescription
URL parameters
calender_group_idstringThe 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 https://outlook.office.com/api/v1.0/me/calendars
GET https://outlook.office.com/api/v1.0/me/calendargroups/{calendar_group_id}/calendars

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

Required parameterTypeDescription
URL parameters
calender_group_idstringThe calendar group ID.

Sample request

GET https://outlook.office.com/api/v1.0/me/calendars

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9xAAA=')",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=",
            "Name": "Calendar",
            "Color": "Auto",
            "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w=="
        }
    ]
}

Response type

The requested calendar collection.


Get a calendar

Minimum required scope: one of the following:

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/beta/me/calendars/{calendar_id}

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

Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

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

Sample response

Status code: 200

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

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

Required parameterTypeDescription
URL parameters
calendar_idstringThe 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"
    }
}
GET https://outlook.office.com/api/v1.0/me/calendars/{calendar_id}

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

Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

GET https://outlook.office.com/api/v1.0/me/calendars/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars/$entity",
    "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9xAAA=')",
    "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=",
    "Name": "Calendar",
    "Color": "Auto",
    "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w=="
}

Response type

The requested calendar.


Create calendars

Create a calendar

Create a calendar

Minimum required scope: one of the following:

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/beta/me/calendars
POST https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}/calendars
Required parameterTypeDescription
URL parameters
calender_group_idstringThe calendar group ID, if you're getting calendars from a specific group.
Body parameters
NamestringThe name of the new calendar.

Sample request

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

{
  "Name": "Volunteer"
}

Sample response

Status code: 201

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Calendars/$entity",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Calendars('AAMkADJmMVAAA=')",
    "Id":"AAMkADJmMVAAA=",
    "Name":"Volunteer",
    "Color":"Auto",
    "IsDefaultCalendar":false,
    "ChangeKey":"DxYSthXJXEWwAQSYQnXvIgAAIxGttg==",
    "CanShare":true,
    "CanViewPrivateItems":true,
    "IsShared":false,
    "IsSharedWithMe":false,
    "CanEdit":true,
    "Owner":{
        "Name":"Fanny Downs",
        "Address":"fannyd@adatum.onmicrosoft.com"
    }
}
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 parameterTypeDescription
URL parameters
calender_group_idstringThe calendar group ID, if you're getting calendars from a specific group.
Body parameters
NamestringThe 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"
  }
}
POST https://outlook.office.com/api/v1.0/me/calendars
POST https://outlook.office.com/api/v1.0/me/calendargroups/{calendar_group_id}/calendars
Required parameterTypeDescription
URL parameters
calender_group_idstringThe calendar group ID, if you're getting calendars from a specific group.
Body parameters
NamestringThe name of the new calendar.

Sample request

POST https://outlook.office.com/api/v1.0/me/calendars
Content-Type: application/json
{
  "Name": "Social"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLHAAA=",
  "Name": "Social",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ=="
}

Response type

The new calendar.


Update calendars

Update a calendar

Update a calendar

Minimum required scope: one of the following:

Change writable properties of a calendar.

PATCH https://outlook.office.com/api/beta/me/calendars/{calendar_id}
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

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

{
  "Name": "Social events"
}

Sample response

Status code: 200

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Calendars/$entity",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Calendars('AAMkADJmMVAAA=')",
    "Id":"AAMkADJmMVAAA=",
    "Name":"Social events",
    "Color":"Auto",
    "IsDefaultCalendar":false,
    "ChangeKey":"DxYSthXJXEWwAQSYQnXvIgAAIxGttg==",
    "CanShare":true,
    "CanViewPrivateItems":true,
    "IsShared":false,
    "IsSharedWithMe":false,
    "CanEdit":true,
    "Owner":{
        "Name":"Fanny Downs",
        "Address":"fannyd@adatum.onmicrosoft.com"
    }
}
PATCH https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}
Required parameterTypeDescription
URL parameters
calendar_idstringThe 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"
  }
}
PATCH https://outlook.office.com/api/v1.0/me/calendars/{calendar_id}
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.
Body parameters
NamestringThe new name of the calendar.

Sample request

PATCH https://outlook.office.com/api/v1.0/me/calendars/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA=
Content-Type: application/json
{
  "Name": "Social events"
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA=",
  "Name": "Social events",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw=="

Response type

The updated calendar.


Delete calendars

Delete a calendar.

Delete a calendar

Delete a calendar

Minimum required scope: one of the following:

DELETE https://outlook.office.com/api/beta/me/calendars/{calendar_id}
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

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

Sample response

Status code: 204
DELETE https://outlook.office.com/api/v2.0/me/calendars/{calendar_id}
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

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

Sample response

Status code: 204
DELETE https://outlook.office.com/api/v1.0/me/calendars/{calendar_id}
Required parameterTypeDescription
URL parameters
calendar_idstringThe calendar ID.

Sample request

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

Sample response

Status code: 204

Get calendar groups

You can get a calendar group collection or 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 | Get a calendar group


Get a calendar group collection

Minimum required scope: one of the following:

Get the calendar groups in a mailbox.

GET https://outlook.office.com/api/beta/me/calendargroups

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

Sample request

GET https://outlook.office.com/api/beta/me/calendargroups

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/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/beta/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=="
        }
    ]
}
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=="
        }
    ]
}
GET https://outlook.office.com/api/v1.0/me/calendargroups

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

Sample request

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

Sample response

Status code: 200

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

Response type

The requested calendar group collection.


Get a calendar group

Minimum required scope: one of the following:

Get a calendar group by ID.

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

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

Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.

Sample request

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

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/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=="
}
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 parameterTypeDescription
URL parameters
calendar_group_idstringThe 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=="
}
GET https://outlook.office.com/api/v1.0/me/calendargroups/{calendar_group_id}

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

Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.

Sample request

GET https://outlook.office.com/api/v1.0/me/calendargroups/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=

Sample response

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
    "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9xAAA=')",
    "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=",
    "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.

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

Create a calendar group

Minimum required scope: one of the following:

POST https://outlook.office.com/api/beta/me/calendargroups
Required parameterTypeDescription
URL parameter
Body parameters
NamestringThe name of the calendar group.

Sample request

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

{
  "Name": "Birthdays"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/beta/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"
}
POST https://outlook.office.com/api/v2.0/me/calendargroups
Required parameterTypeDescription
URL parameter
Body parameters
NamestringThe 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"
}
POST https://outlook.office.com/api/v1.0/me/calendargroups
Required parameterTypeDescription
URL parameter
Body parameters
NamestringThe name of the calendar group.
POST https://outlook.office.com/api/v1.0/me/calendargroups
Content-Type: application/json
{
  "Name": "Birthdays"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Rw==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=",
  "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:

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

PATCH https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}
Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.
Body parameters
NamestringThe name of the updated calendar group.

Sample request

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

{
  "Name": "Holidays"
}

Sample response

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://https://outlook.office.com/api/beta/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"
}
PATCH https://outlook.office.com/api/v2.0/me/calendargroups/{calendar_group_id}
Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.
Body parameters
NamestringThe 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"
}
PATCH https://outlook.office.com/api/v1.0/me/calendargroups/{calendar_group_id}
Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.
Body parameters
NamestringThe name of the updated calendar group.
PATCH https://outlook.office.com/api/v1.0/me/calendargroups/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=
{
  "Name": "Holidays"
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SA==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=",
  "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

Delete a calendar group

Minimum required scope: one of the following:

DELETE https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}
Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.

Sample request

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

Sample response

Status code: 204
DELETE https://outlook.office.com/api/v2.0/me/calendargroups/{calendar_group_id}
Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.

Sample request

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

Sample response

Status code: 204
DELETE https://outlook.office.com/api/v1.0/me/calendargroups/{calendar_group_id}
Required parameterTypeDescription
URL parameters
calendar_group_idstringThe calendar group ID.

Sample request

DELETE https://outlook.office.com/api/v1.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.

Or, learn more about using the Office 365 platform:

© 2018 Microsoft