Share via


[DEPRECATED] Outlook Calendar REST API reference (beta)

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

Note

The beta version of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. Consequently, the beta REST endpoint is also deprecated and will be fully decommissioned in November 2022. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

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

Note

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

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

All Calendar API operations

Event operations

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

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.

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.

See also

Using the Calendar REST API

Authentication

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

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

Scopes to access shared calendars

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

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

Version of API

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

Target user

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

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

Get events

Get an event collection or an event.

An event body can be in either text or HTML.

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

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

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

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

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

Prefer: outlook.timezone="Eastern Standard Time"

If you do not specify the Prefer: outlook.timezone header, the start and end times in the response are returned in UTC.

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

Get a calendar view

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

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

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

Note

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

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

GET https://outlook.office.com/api/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 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 parameter Type Description
_Header parameters
Prefer: outlook.timezone The default time zone for events in the response.
URL parameters
calendar_id string The calendar ID, if you're getting events from a specific calendar.

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

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

Note

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

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

Sample request

GET https://outlook.office.com/api/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 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 parameter Type Description
Header parameters
Prefer: outlook.timezone The default timezone for events in the response.
URL parameters
event_id string The event ID.
start_datetime datetimeoffset The UTC date and time when the event starts.
end_datetime datetimeoffset The UTC date and time when the event ends.

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

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

Response type

The requested event collection.

Note

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

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

GET https://outlook.office.com/api/beta/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 parameter Type Description
Header parameters
Prefer: outlook.timezone The default timezone for events in the response.
URL parameters
event_id string The event ID.

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

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

Sample request

GET https://outlook.office.com/api/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"
            }
        }
    }

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

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

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"
}

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.

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

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

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

Response type

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

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

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

Prefer: outlook.timezone="Pacific Standard Time"

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

Note

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

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

Find time and location to meet with 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": ""
}

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)

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, 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 parameter Type Description
Function parameter
room_list string The 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"
    }
  ]
}

Create events

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 sends 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 parameter Type Description
URL parameters
calendar_id string The 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

Update events

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 parameter Type Description
URL parameters
event_id string The 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.

Respond to events

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

Sample request

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

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

Sample request

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

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

Sample request

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

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 parameter Type Description
URL parameters
event_id string The event ID.
Body parameters
Comment string A comment to include. Can be an empty string.
ToRecipients Collection(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

Delete events

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 parameter Type Description
URL parameters
event_id string The event ID.

Sample request

DELETE https://outlook.office.com/api/beta/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 parameter Type Description
URL parameters
event_id string The event ID.
Body parameters
Comment string A 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

Get attachments

You can get an attachment collection or 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 parameter Type Description
URL parameters
event_id string The 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 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 parameter Type Description
URL parameters
event_id string The event ID.
attachment_id string The attachment ID.

Note

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

Response type

The requested file attachment, 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",
    }
}

Create attachments

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

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
Required parameter Type Description
URL parameters
event_id string The event ID.
Body parameters
@odata.type string #Microsoft.OutlookServices.FileAttachment
Name string The name of the attachment.
ContentBytes binary The file to attach.

Response type

The new file attachment.

Create an item attachment

Minimum required scope

One of the following:

Add an item attachment to an event.

POST https://outlook.office.com/api/beta/me/events/{event_id}/attachments
Required parameter Type Description
URL parameters
event_id string The event ID.
Body parameters
@odata.type string #Microsoft.OutlookServices.ItemAttachment
Name string The name of the attachment.
Item A Message, Event, or Contact entity. The item to attach.

Response type

The new item attachment.

Create a reference attachment

Minimum required scope

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

Add a reference attachment to an event.

POST https://outlook.office.com/api/beta/me/events/{event_id}/attachments
Required parameter Type Description
URL parameters
event_id String The event ID.
Body parameters
@odata.type String #Microsoft.OutlookServices.ReferenceAttachment
Name String The display name of the attachment. Required.
SourceUrl String URL to get the attachment content. If this is a URL to a folder, then for the folder to be displayed correctly in Outlook or Outlook on the web, set IsFolder to true. Required.

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

Response type

The reference attachment.

Sample request

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

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

Delete attachments

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 parameter Type Description
URL parameters
event_id string The event ID.
attachment_id string The attachment ID.

Sample request

DELETE https:/outlook.office.com/api/beta/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 parameter Type Description
Header parameters
Prefer: outlook.timezone The default timezone for events in the response.
URL parameters
StartDateTime string The starting date and time for returned reminders.
EndDateTime string The ending date and time for returned reminders.

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

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

Snooze reminders

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

Minimum required scope

One of the following:

POST https://outlook.office.com/api/beta/me/Events('{id}')/SnoozeReminder
Required paremeters Type Description
URL parameters
id string The ID of the event.
Body parameters
NewReminderTime DateTimeTimeZone The new date and time to trigger the reminder.

Dismiss reminders

Dismiss a reminder that has been triggered.

Minimum required scope

One of the following:

POST https://outlook.office.com/api/beta/me/Events({id})/DismissReminder
Required paremeters Type Description
URL parameters
id string The ID of the event.

Get calendars

You can get a calendar collection or get a calendar.

Get a calendar collection

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 parameter Type Description
URL parameters
calender_group_id string The 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 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 parameter Type Description
URL parameters
calendar_id string The 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"
    }
}

Response type

The requested calendar.

Create calendars

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 parameter Type Description
URL parameters
calender_group_id string The calendar group ID, if you're getting calendars from a specific group.
Body parameters
Name string The name of the new calendar.

Sample request

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

Response type

The new calendar.

Update calendars

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 parameter Type Description
URL parameters
calendar_id string The 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"
    }
}

Response type

The updated calendar.

Delete calendars

Delete a calendar

Minimum required scope

One of the following:

DELETE https://outlook.office.com/api/beta/me/calendars/{calendar_id}
Required parameter Type Description
URL parameters
calendar_id string The calendar ID.

Sample request

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

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

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=="
        }
    ]
}

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 parameter Type Description
URL parameters
calendar_group_id string The 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=="
}

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

Minimum required scope

One of the following:

POST https://outlook.office.com/api/beta/me/calendargroups
Required parameter Type Description
URL parameter
Body parameters
Name string The name of the calendar group.

Sample request

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

Response type

The new calendar group.

Update calendar groups

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 parameter Type Description
URL parameters
calendar_group_id string The calendar group ID.
Body parameters
Name string The name of the updated calendar group.

Sample request

PATCH https://outlook.office.com/api/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"
}

Response type

The updated calendar group.

Delete calendar groups

Note

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

Delete a calendar group

Minimum required scope

One of the following:

DELETE https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}
Required parameter Type Description
URL parameters
calendar_group_id string The calendar group ID.

Sample request

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