Last Updated: 10/12/2016

Outlook Calendar REST API reference

outlookrestapibeta

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

outlookrestapibeta

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

Note

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

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.

outlookrestapibeta

outlookrestapibeta

outlookrestapiv2

outlookrestapiv2

outlookrestapiv1

outlookrestapiv1

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

Get calendars | Create calendars | Update calendars | Delete calendars

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

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

Get calendar groups | Create calendar groups | Update calendar groups | Delete calendar groups

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.

outlookrestapibeta

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.

outlookrestapibeta

outlookrestapiv2

Prefer: outlook.timezone="Eastern Standard Time"

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

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

outlookrestapiv2

REST API: Get a calendar view (REST) |
Get series master and single events (REST) | Get event instances (REST) | Get an event (REST)

Client libraries: Get events from the user's calendar (Client)

Get a calendar view (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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.

outlookrestapibeta

outlookrestapiv2

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

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

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

Response type

The expanded events within the specified time range.

outlookrestapiv2

outlookrestapiv1

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

Required parameter	Type	Description
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.

For example, get the calendar view for the month of October, returning only the Subject property for each event:

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

Response type

The expanded events within the specified time range.

outlookrestapiv1

Get series master and single events (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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.

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

Sample response

Status code: 200

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Sample response

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

outlookrestapiv2

outlookrestapiv1

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

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID, if you're getting events from a specific calendar.

Sample request

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

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48w==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x48w==",
      "Categories": [],
      "DateTimeCreated": "2014-10-19T23:13:47.3959685Z",
      "DateTimeLastModified": "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": "2014-10-13T21:00:00Z",
      "StartTimeZone": "Pacific Standard Time",
      "End": "2014-10-13T22:00:00Z",
      "EndTimeZone": "Pacific Standard Time",
      "Location": {
        "DisplayName": "Alex's Office"
      },
      "ShowAs": "Busy",
      "IsAllDay": false,
      "IsCancelled": false,
      "IsOrganizer": true,
      "ResponseRequested": true,
      "Type": "SeriesMaster",
      "SeriesMasterId": null,
      "Attendees": [
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "Name": "Janet Schorr"
          },
          "Status": {
            "Response": "None",
            "Time": "0001-01-01T00:00:00Z"
          },
          "Type": "Required"
        },
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "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"
          ]
        },
        "Range": {
          "Type": "NoEnd",
          "StartDate": "2014-10-13T00:00:00-07:00",
          "EndDate": "0001-01-01T00:00:00Z",
          "NumberOfOccurrences": 0
        }
      },
      "Organizer": {
        "EmailAddress": {
          "Address": "[email protected]",
          "Name": "Alex D"
        }
      }
    },
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG92AAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48A==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG92AAA=",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x48A==",
      "Categories": [],
      "DateTimeCreated": "2014-10-19T23:13:01.9733945Z",
      "DateTimeLastModified": "2014-10-19T23:13:02.426753Z",
      "Subject": "Daily Team Meeting",
      "BodyPreview": "Daily sync on project progress and team member status",
      "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\nDaily sync on project progress and team member status\r\n</body>\r\n</html>\r\n"
      },
      "Importance": "Normal",
      "HasAttachments": false,
      "Start": "2014-10-13T18:00:00Z",
      "StartTimeZone": "Pacific Standard Time",
      "End": "2014-10-13T18:30:00Z",
      "EndTimeZone": "Pacific Standard Time",
      "Location": {
        "DisplayName": "Team Room"
      },
      "ShowAs": "Busy",
      "IsAllDay": false,
      "IsCancelled": false,
      "IsOrganizer": true,
      "ResponseRequested": true,
      "Type": "SeriesMaster",
      "SeriesMasterId": null,
      "Attendees": [
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "Name": "Rob Young"
          },
          "Status": {
            "Response": "None",
            "Time": "0001-01-01T00:00:00Z"
          },
          "Type": "Required"
        },
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "Name": "Pavel Bansky"
          },
          "Status": {
            "Response": "None",
            "Time": "0001-01-01T00:00:00Z"
          },
          "Type": "Required"
        },
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "Name": "Janet Schorr"
          },
          "Status": {
            "Response": "None",
            "Time": "0001-01-01T00:00:00Z"
          },
          "Type": "Required"
        },
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "Name": "Garth Fort"
          },
          "Status": {
            "Response": "None",
            "Time": "0001-01-01T00:00:00Z"
          },
          "Type": "Required"
        },
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "Name": "Katie Jordan"
          },
          "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",
            "Tuesday",
            "Wednesday",
            "Thursday",
            "Friday"
          ]
        },
        "Range": {
          "Type": "NoEnd",
          "StartDate": "2014-10-13T00:00:00-07:00",
          "EndDate": "0001-01-01T00:00:00Z",
          "NumberOfOccurrences": 0
        }
      },
      "Organizer": {
        "EmailAddress": {
          "Address": "[email protected]",
          "Name": "Alex D"
        }
      }
    },
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG91AAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x47Q==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG91AAA=",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x47Q==",
      "Categories": [],
      "DateTimeCreated": "2014-10-19T23:12:40.7543183Z",
      "DateTimeLastModified": "2014-10-19T23:12:41.0043215Z",
      "Subject": "Rob:Alex 1:1",
      "BodyPreview": "Let's meet every month to engage in project review and career discussion",
      "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none\"><!-- p { margin-top: 0px; margin-bottom: 0px; }--></style>\r\n</head>\r\n<body dir=\"ltr\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>Let's meet every month to engage in project review and career discussion<br>\r\n</p>\r\n</body>\r\n</html>\r\n"
      },
      "Importance": "Normal",
      "HasAttachments": false,
      "Start": "2014-10-15T16:30:00Z",
      "StartTimeZone": "Pacific Standard Time",
      "End": "2014-10-15T17:30:00Z",
      "EndTimeZone": "Pacific Standard Time",
      "Location": {
        "DisplayName": "Alex's Office"
      },
      "ShowAs": "Busy",
      "IsAllDay": false,
      "IsCancelled": false,
      "IsOrganizer": true,
      "ResponseRequested": true,
      "Type": "SeriesMaster",
      "SeriesMasterId": null,
      "Attendees": [
        {
          "EmailAddress": {
            "Address": "[email protected]",
            "Name": "Rob Young"
          },
          "Status": {
            "Response": "None",
            "Time": "0001-01-01T00:00:00Z"
          },
          "Type": "Required"
        }
      ],
      "Recurrence": {
        "Pattern": {
          "Type": "RelativeMonthly",
          "Interval": 1,
          "Month": 0,
          "Index": "Third",
          "FirstDayOfWeek": "Sunday",
          "DayOfMonth": 0,
          "DaysOfWeek": [
            "Wednesday"
          ]
        },
        "Range": {
          "Type": "NoEnd",
          "StartDate": "2014-10-15T00:00:00-07:00",
          "EndDate": "0001-01-01T00:00:00Z",
          "NumberOfOccurrences": 0
        }
      },
      "Organizer": {
        "EmailAddress": {
          "Address": "[email protected]",
          "Name": "Alex D"
        }
      }
    },
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG90AAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x46g==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG90AAA=",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x46g==",
      "Categories": [],
      "DateTimeCreated": "2014-10-19T08:48:13.6271741Z",
      "DateTimeLastModified": "2014-10-19T08:48:13.6427985Z",
      "Subject": "Thanksgiving Holiday",
      "BodyPreview": "",
      "Body": {
        "ContentType": "HTML",
        "Content": ""
      },
      "Importance": "Normal",
      "HasAttachments": false,
      "Start": "2015-11-26T00:00:00Z",
      "StartTimeZone": "Pacific Standard Time",
      "End": "2015-11-27T00:00:00Z",
      "EndTimeZone": "Pacific Standard Time",
      "Location": {
        "DisplayName": ""
      },
      "ShowAs": "Free",
      "IsAllDay": true,
      "IsCancelled": false,
      "IsOrganizer": true,
      "ResponseRequested": true,
      "Type": "SingleInstance",
      "SeriesMasterId": null,
      "Attendees": [],
      "Recurrence": null,
      "Organizer": {
        "EmailAddress": {
          "Address": "[email protected]",
          "Name": "Alex D"
        }
      }
    },
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9zAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x46Q==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9zAAA=",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x46Q==",
      "Categories": [],
      "DateTimeCreated": "2014-10-19T08:46:18.8700566Z",
      "DateTimeLastModified": "2014-10-19T08:46:18.8856803Z",
      "Subject": "Thanksgiving Holiday",
      "BodyPreview": "",
      "Body": {
        "ContentType": "HTML",
        "Content": ""
      },
      "Importance": "Normal",
      "HasAttachments": false,
      "Start": "2014-11-27T00:00:00Z",
      "StartTimeZone": "Pacific Standard Time",
      "End": "2014-11-28T00:00:00Z",
      "EndTimeZone": "Pacific Standard Time",
      "Location": {
        "DisplayName": ""
      },
      "ShowAs": "Free",
      "IsAllDay": true,
      "IsCancelled": false,
      "IsOrganizer": true,
      "ResponseRequested": true,
      "Type": "SingleInstance",
      "SeriesMasterId": null,
      "Attendees": [],
      "Recurrence": null,
      "Organizer": {
        "EmailAddress": {
          "Address": "[email protected]",
          "Name": "Alex D"
        }
      }
    },
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x46A==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA=",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x46A==",
      "Categories": [],
      "DateTimeCreated": "2014-10-19T08:43:37.2138006Z",
      "DateTimeLastModified": "2014-10-19T08:43:37.2450436Z",
      "Subject": "New Year's Day Holiday",
      "BodyPreview": "",
      "Body": {
        "ContentType": "HTML",
        "Content": ""
      },
      "Importance": "Normal",
      "HasAttachments": false,
      "Start": "2015-01-01T00:00:00Z",
      "StartTimeZone": "Pacific Standard Time",
      "End": "2015-01-02T00:00:00Z",
      "EndTimeZone": "Pacific Standard Time",
      "Location": {
        "DisplayName": ""
      },
      "ShowAs": "Free",
      "IsAllDay": true,
      "IsCancelled": false,
      "IsOrganizer": true,
      "ResponseRequested": true,
      "Type": "SingleInstance",
      "SeriesMasterId": null,
      "Attendees": [],
      "Recurrence": null,
      "Organizer": {
        "EmailAddress": {
          "Address": "[email protected]",
          "Name": "Alex D"
        }
      }
    },
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9xAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x45w==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9xAAA=",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x45w==",
      "Categories": [],
      "DateTimeCreated": "2014-10-19T08:33:45.1538198Z",
      "DateTimeLastModified": "2014-10-19T08:33:45.200696Z",
      "Subject": "Christmas Holiday",
      "BodyPreview": "",
      "Body": {
        "ContentType": "HTML",
        "Content": ""
      },
      "Importance": "Normal",
      "HasAttachments": false,
      "Start": "2014-12-25T00:00:00Z",
      "StartTimeZone": "Pacific Standard Time",
      "End": "2014-12-26T00:00:00Z",
      "EndTimeZone": "Pacific Standard Time",
      "Location": {
        "DisplayName": ""
      },
      "ShowAs": "Free",
      "IsAllDay": true,
      "IsCancelled": false,
      "IsOrganizer": true,
      "ResponseRequested": true,
      "Type": "SingleInstance",
      "SeriesMasterId": null,
      "Attendees": [],
      "Recurrence": null,
      "Organizer": {
        "EmailAddress": {
          "Address": "[email protected]",
          "Name": "Alex D"
        }
      }
    }
  ]
}

outlookrestapiv1

Get event instances (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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.

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

outlookrestapibeta

outlookrestapiv2

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

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

Response type

The requested event collection.

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

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

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

outlookrestapiv2

outlookrestapiv1

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

Required parameter	Type	Description
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.

Response type

The requested event collection.

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

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

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

outlookrestapiv1

Get an event (REST)

Minimum required scope: one of the following:

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

Get an event by ID.

outlookrestapibeta

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",
            "Address": null,
            "Coordinates": null,
            "LocationEmailAddress": "",
            "LocationUri": ""
        },
        "ShowAs": "Busy",
        "IsAllDay": false,
        "IsCancelled": false,
        "IsOrganizer": true,
        "ResponseRequested": true,
        "Type": "SeriesMaster",
        "SeriesMasterId": null,
        "Attendees": [
            {
                "EmailAddress": {
                    "Address": "[email protected]",
                    "Name": "Janet Schorr"
                },
                "Status": {
                    "Response": "None",
                    "Time": "0001-01-01T00:00:00Z"
                },
                "Type": "Required"
            },
            {
                "EmailAddress": {
                    "Address": "[email protected]",
                    "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": "[email protected]",
                "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": "[email protected]",
                "Name": "Alex D"
            }
        }
    }

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Sample response

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

Response type

The requested event.

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

Sample request

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

Sample response

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

outlookrestapiv2

outlookrestapiv1

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

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

Sample request

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

Name	Type	Value	Notes
event_id	string		The event ID.

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=')",
  "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48w==\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=",
  "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x48w==",
  "Categories": [],
  "DateTimeCreated": "2014-10-19T23:13:47.3959685Z",
  "DateTimeLastModified": "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": "2014-10-13T21:00:00Z",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-10-13T22:00:00Z",
  "EndTimeZone": "Pacific Standard Time",
  "Location": {
    "DisplayName": "Alex's Office"
  },
  "ShowAs": "Busy",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": true,
  "ResponseRequested": true,
  "Type": "SeriesMaster",
  "SeriesMasterId": null,
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "[email protected]",
        "Name": "Janet Schorr"
      },
      "Status": {
        "Response": "None",
        "Time": "0001-01-01T00:00:00Z"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "[email protected]",
        "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"
      ]
    },
    "Range": {
      "Type": "NoEnd",
      "StartDate": "2014-10-13T00:00:00-07:00",
      "EndDate": "0001-01-01T00:00:00Z",
      "NumberOfOccurrences": 0
    }
  },
  "Organizer": {
    "EmailAddress": {
      "Address": "[email protected]",
      "Name": "Alex D"
    }
  }
}

Response type

The requested event.

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

Sample request

GET https://outlook.office.com/api/v1.0/me/events/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=?$select=Subject,Organizer,Start,End

Name	Type	Value	Notes
event_id	string		The event ID.

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=')",
  "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48w==\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG93AAA=",
  "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x48w==",
  "Categories": [],
  "DateTimeCreated": "2014-10-19T23:13:47.3959685Z",
  "DateTimeLastModified": "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": "2014-10-13T21:00:00Z",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-10-13T22:00:00Z",
  "EndTimeZone": "Pacific Standard Time",
  "Location": {
    "DisplayName": "Alex's Office"
  },
  "ShowAs": "Busy",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": true,
  "ResponseRequested": true,
  "Type": "SeriesMaster",
  "SeriesMasterId": null,
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "[email protected]",
        "Name": "Janet Schorr"
      },
      "Status": {
        "Response": "None",
        "Time": "0001-01-01T00:00:00Z"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "[email protected]",
        "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"
      ]
    },
    "Range": {
      "Type": "NoEnd",
      "StartDate": "2014-10-13T00:00:00-07:00",
      "EndDate": "0001-01-01T00:00:00Z",
      "NumberOfOccurrences": 0
    }
  },
  "Organizer": {
    "EmailAddress": {
      "Address": "[email protected]",
      "Name": "Alex D"
    }
  }
}

outlookrestapiv1

Get events from the user's calendar (Client)

Get the events from the user's default calendar. To get the events from a different calendar, call the calendar's Events property.

Example: outlookClient.Me.Calendars[calendarId].Events.ExecuteAsync()

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

To get a particular event, you can specify the event ID as the index of the Events collection or use the GetById method.

Note Event collections support query expressions such as Select, OrderBy, and Take.

This example calls the method that creates the Outlook Services client.

var outlookClient = await CreateOutlookClientAsync("Calendar");
var events = await outlookClient.Me.Events
  .Take(10)
  .ExecuteAsync();

foreach(var calendarEvent in events.CurrentPage)
{
  System.Diagnostics.Debug.WriteLine("Event '{0}'.", calendarEvent.Subject);
}

outlookClient.me.events.getEvents().fetch().then(function (result) {
    result.currentPage.forEach(function (event) {
console.log('Event "' + event.subject + '"')
    });
}, function(error) {
    console.log(error);
});

This call returns the event series, not the individual expanded instances for recurring events (such as a weekly team meeting).

Querying event instances is currently not supported in the client library. You can use the REST API to query the CalendarView property on the Calendar resource or the Instances property on the Event resource:

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Sync events

Minimum required scope: one of the following:

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

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

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

Request headers

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

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

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.)
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 [email protected]_ 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.

outlookrestapibeta

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('[email protected]')/Events('asdas==')",
                "@odata.etag": "W/\"L8Z+4Y4u7k+97uRKg==\"",
                "Id": "AQMkANJAAAAA==",
                "ChangeKey": "L8Z+AAAAARKg==",
                "Categories": [
                ],
                "DateTimeCreated": "2015-04-10T17:54:49.2725912Z",
                "DateTimeLastModified": "2015-04-10T17:54:49.3038538Z",
                "Subject": "Discuss the Calendar REST API",
                "BodyPreview": "I think it will meet our requirements!",
                "Body": {
                    "ContentType": "HTML",
                    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
                },
                "Importance": "Normal",
                "HasAttachments": false,
                "Start": {
                    "DateTime": "2015-04-05T18:00:00",
                    "TimeZone": "Pacific Standard Time"
                }
                "End": {
                    "DateTime": "2015-04-05T19:00:00",
                    "TimeZone": "Pacific Standard Time"
                }
                "ReminderMinutesBeforeStart": "15",
                "IsReminderOn": "true",
                "Location": {
                    "DisplayName": "",
                    "Address": null,
                    "Coordinates": null,
                    "LocationEmailAddress": "",
                    "LocationUri": ""
                },
                "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": "[email protected]",
                        "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('[email protected]')/Events('AAMkAD0jAAA=')",
            "@odata.etag": "W/\"P2fd7QAAAAAVFA==\"",
            "Id": "AAMkADNkNmVlOTITVAAAAAA0jAAA=",
            "ChangeKey": "P2fdmIU1QAAAAAVFA==",
            "Categories": [
            ],
            "DateTimeCreated": "2015-04-15T18:59:11.0226221Z",
            "DateTimeLastModified": "2015-04-15T18:59:11.0694979Z",
            "Subject": "1 hour",
            "BodyPreview": "\u200b",
            "Body": {
                "ContentType": "HTML",
                "Content": "<html><body>content</body></html>"
            },
            "Importance": "Normal",
            "HasAttachments": false,
            "Start": {
                "DateTime": "2015-04-16T18:00:00",
                "TimeZone": "Pacific Standard Time"
            }
            "End": {
                "DateTime": "2015-04-16T19:00:00",
                "TimeZone": Pacific Standard Time"
            }
            "ReminderMinutesBeforeStart": "15",
            "IsReminderOn": "true",
            "Location": {
                "DisplayName": "",
                "Address": {
                    "Street": "",
                    "City": "",
                    "State": "",
                    "CountryOrRegion": "",
                    "PostalCode": ""
                },
                "Coordinates": {
                    "Accuracy": "NaN",
                    "Altitude": "NaN",
                    "AltitudeAccuracy": "NaN",
                    "Latitude": "NaN",
                    "Longitude": "NaN"
                },
                "LocationEmailAddress": "",
                "LocationUri": ""
            },
            "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": "[email protected]",
                    "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"
}

outlookrestapibeta

outlookrestapiv2

To sync in the default calendar

Initial request:

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

Second request, or first request of a subsequent round:

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

Third or subsequent request in the same round

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

To sync in a specific calendar

Initial request:

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

Second request, or first request of a subsequent round:

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

Third or subsequent request in the same round:

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

Parameters

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

Note

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

Response type

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

Example

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

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

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

Sample initial request

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

Sample initial response data

Preference-Applied: odata.track-changes

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

Sample second request

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

Sample second response data

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

outlookrestapiv2

outlookrestapiv1

To sync in the default calendar

Initial request:

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

Second request, or first request of a subsequent round:

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

Third or subsequent request in the same round

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

To sync in a specific calendar

Initial request:

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

Second request, or first request of a subsequent round:

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

Third or subsequent request in the same round:

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

Parameters

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

Note

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

Response type

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

Example

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

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

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

Sample initial request

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

Sample initial response data

Preference-Applied: odata.track-changes

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

Sample second request

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

Sample second response data

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

outlookrestapiv1

Find meeting times

outlookrestapibeta

Minimum required scope: one of the following:

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

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

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

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

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

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

Based on the specified parameters, FindMeetingTimes checks the free/busy status in the primary calendars of the organizer and attendees. The action calculates the best possible meeting times, and returns any meeting suggestions.

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:

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.
Any meeting suggestion occurs during only the work hours of the organizer or an attendee. You can ignore specifying the ActivityDomain property of a TimeConstraint.

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

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

Find time and location to meet with specific attendees (REST)

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 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": "[email protected]" 
      } 
    } 
  ],  
  "TimeConstraint": { 
    "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": "[email protected]"
                        }
                    },
                    "Availability": "Free"
                }
            ],
            "Locations": [
               {
                    "DisplayName": "Tokyo conference room",
                    "LocationEmailAddress": "",
                    "LocationUri": "",
                    "Address": null,
                    "Coordinates": null
                }
            ]
        },
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-20T11:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T12:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
                {
                    "Attendee": {
                        "Type": "Required",
                        "EmailAddress": {
                            "Name": "Fanny",
                            "Address": "[email protected]"
                        }
                    },
                    "Availability": "Free"
                }
            ],
            "Locations": [
               {
                    "DisplayName": "Paris conference room",
                    "LocationEmailAddress": "",
                    "LocationUri": "",
                    "Address": null,
                    "Coordinates": null
                }
            ]
        }
    ],
    "EmptySuggestionsReason": ""
}

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

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": "[email protected]" 
      } 
    } 
  ],  
  "LocationConstraint": { 
    "IsRequired": "false",  
    "SuggestLocation": "false",  
    "Locations": [ 
      { 
        "ResolveAvailability": "false",
        "DisplayName": "Conf room Hood" 
      } 
    ] 
  },  
  "TimeConstraint": { 
    "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": "[email protected]"
                        }
                    },
                    "Availability": "Free"
                }
            ],
            "Locations": [
                {
                    "DisplayName": "Conf room Hood"
                }
            ],
            "SuggestionReason": "Suggested because it is one of the nearest times when all attendees are available."
        }
    ],
    "EmptySuggestionsReason": ""
}

Find time to meet but no attendee is available (REST)

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": "[email protected]" 
      } 
    } 
  ],  
  "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 (REST)

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": "[email protected]" 
      } 
    },
   { 
      "Type": "Optional",  
      "EmailAddress": { 
        "Name": "Dana",
        "Address": "[email protected]" 
      } 
    } 
  ],  
  "LocationConstraint": { 
    "IsRequired": "false",  
    "SuggestLocation": "false",  
    "Locations": [ 
      { 
        "ResolveAvailability": "false",
        "DisplayName": "Conf room Hood" 
      } 
    ] 
  },  
  "TimeConstraint": { 
    "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":"[email protected]"
                  }
               },
               "Availability":"Free"
            },
            {
               "Attendee":{
                  "Type":"Required",
                  "EmailAddress":{
                     "Name": "Dana",
                     "Address":"[email protected]"
                  }
               },
               "Availability":"Free"
            }
         ],
         "Locations":[
            {
               "DisplayName":"Conf room Hood"
            }
         ],
         "SuggestionReason":"Suggested because it is one of the nearest times when most attendees are available."
      },
      {
         "MeetingTimeSlot":{
            "Start":{
               "DateTime":"2016-05-20T11:00:00.0000000",
               "TimeZone":"Pacific Standard Time"
            },
            "End":{
               "DateTime":"2016-05-20T12:00:00.0000000",
               "TimeZone":"Pacific Standard Time"
            }
         },
         "Confidence":74.5,
         "OrganizerAvailability":"Free",
         "AttendeeAvailability":[
            {
               "Attendee":{
                  "Type":"Required",
                  "EmailAddress":{
                     "Name": "Fanny",
                     "Address":"[email protected]"
                  }
               },
               "Availability":"Free"
            },
            {
               "Attendee":{
                  "Type":"Required",
                  "EmailAddress":{
                     "Name": "Dana",
                     "Address":"[email protected]"
                  }
               },
               "Availability":"Unknown"
            }
         ],
         "Locations":[
            {
               "DisplayName":"Conf room Hood"
            }
         ],
         "SuggestionReason":"Suggested because it is one of the nearest times when most attendees are available."
      }
   ],
   "EmptySuggestionsReason":""
}

Find free time slots for just the signed-in user (REST)

Find free time slots in the signed-in user's primary calendar within a range of dates, 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 within the time period specified by TimeConstraint.

POST https://outlook.office.com/api/beta/me/findmeetingtimes

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

{ 
  "Attendees": [],
  "TimeConstraint": { 
    "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-20T08:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T09:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
            ],
            "Locations": [
            ]
        },
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-20T09:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T10:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
            ],
            "Locations": [
            ]
        },
        {
            "MeetingTimeSlot": {
                "Start": {
                    "DateTime": "2016-05-20T12:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                },
                "End": {
                    "DateTime": "2016-05-20T13:00:00.0000000",
                    "TimeZone": "Pacific Standard Time"
                }
            },
            "Confidence": 100.0,
            "OrganizerAvailability": "Free",
            "AttendeeAvailability": [
            ],
            "Locations": [
            ]
        }
    ],
    "EmptySuggestionsReason": ""
}

outlookrestapibeta

outlookrestapiv2

Minimum required scope: one of the following:

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

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

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

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

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

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

Response type

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

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"

Note

Currently, FindMeetingTimes assumes the following:

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.
Any meeting suggestion occurs during only the work hours of the organizer or an attendee. You can ignore specifying the ActivityDomain property of a TimeConstraint.

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

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

Find time and location to meet with specific attendees (REST)

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

Attendees
TimeConstraint
MeetingDuration

Sample request

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

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

{ 
  "Attendees": [ 
    { 
      "Type": "Required",  
      "EmailAddress": { 
        "Name": "Fanny",
        "Address": "[email protected]" 
      } 
    } 
  ],  
  "TimeConstraint": { 
    "Timeslots": [ 
       { 
        "Start": { 
          "DateTime": "2016-05-20T07:00:00",  
          "TimeZone": "Pacific Standard Time" 
        },  
        "End": { 
          "DateTime": "2016-05-20T17:00:00",  
          "TimeZone": "Pacific Standard Time" 
        } 
      } 
    ] 
  },  
  "MeetingDuration": "PT1H" 
}

Sample response

Status code: 200

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

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

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

Attendees
LocationConstraint
TimeConstraint
MeetingDuration
ReturnSuggestionReasons

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

Sample request

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

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

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

Sample response

Status code: 200

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

Find time to meet but no attendee is available (REST)

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

Attendees
LocationConstraint
TimeConstraint
MeetingDuration

See other possible reasons for not returning any meeting suggestions.

Sample request

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

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

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

Sample response

Status code: 200

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

Find time to meet but only some attendees are available (REST)

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

Attendees
LocationConstraint
TimeConstraint
MeetingDuration
ReturnSuggestionReasons
MinimumAttendeePercentage

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

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

Find more information about the confidence of a meeting.

Sample request

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

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

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

Sample response

Status code: 200

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

Find free time slots for just the signed-in user (REST)

Find free time slots in the signed-in user's primary calendar within a range of dates, 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 within the time period specified by TimeConstraint.

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

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

{ 
  "Attendees": [],
  "TimeConstraint": { 
    "Timeslots": [ 
      { 
        "Start": { 
          "DateTime": "2016-05-20T07:00:00",  
          "TimeZone": "Pacific Standard Time" 
        },  
        "End": { 
          "DateTime": "2016-05-20T17:00:00",  
          "TimeZone": "Pacific Standard Time" 
        } 
      } 
    ] 
  },  
  "MeetingDuration": "PT1H"
}

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Create events

REST API: Create a calendar event

Client libraries: Create a calendar event (Client)

Create a calendar event (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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

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

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

Sample response

Status code: 201

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

Response type

The new event.

By default, the response includes all the properties of the new event. Use $select to specify only those properties you need for best performance. The Id property is always returned. The following is an example to include only the Start and End properties of the new event in the response.

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

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

Sample response

Status code: 201

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

Response type

The new event.

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

outlookrestapiv2

outlookrestapiv1

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

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

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

Sample request

POST https://outlook.office.com/api/v1.0/me/events

Content-Type: application/json

{
  "Subject": "Discuss the Calendar REST API",
  "Body": {
    "ContentType": "HTML",
    "Content": "I think it will meet our requirements!"
  },
  "Start": "2014-02-02T18:00:00-08:00",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-02-02T19:00:00-08:00",
  "EndTimeZone": "Pacific Standard Time",
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "[email protected]",
        "Name": "Janet Schorr"
      },
      "Type": "Required"
    }
  ]
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeNheA==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1RAAA=",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeNheA==",
  "Categories": [],
  "DateTimeCreated": "2014-01-22T20:56:10.1058291Z",
  "DateTimeLastModified": "2014-01-22T20:56:10.3402186Z",
  "Subject": "Discuss the Calendar REST API",
  "BodyPreview": "I think it will meet our requirements!",
  "Body": {
    "ContentType": "HTML",
    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
  },
  "Importance": "Normal",
  "HasAttachments": false,
  "Start": "2014-02-02T18:00:00-08:00",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-02-02T19:00:00-08:00",
  "EndTimeZone": "Pacific Standard Time",
  "Location": {
    "DisplayName": ""
  },
  "ShowAs": "Busy",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": true,
  "ResponseRequested": true,
  "Type": "SingleInstance",
  "SeriesMasterId": null,
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "[email protected]",
        "Name": "Janet Schorr"
      },
      "Status": {
        "Response": "None",
        "Time": "0001-01-01T00:00:00Z"
      },
      "Type": "Required"
    }
  ],
  "Recurrence": null,
  "Organizer": {
    "EmailAddress": {
      "Address": "[email protected]",
      "Name": "alexd"
    }
  }
}

Response type

The new event.

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

outlookrestapiv1

Create a calendar event (Client)

Create an event. To add an event to a different calendar, use the Events property of the destination calendar.

Example: await client.Me.Calendars["AQMkADE3..."].Events.AddEventAsync(newEvent);

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

outlookrestapibeta

outlookrestapiv2

This example assumes you already got the Outlook Services client.

// Create a location for the event
Location location = new Location 
{ 
    DisplayName = "Water cooler" 
}; 

// Create a description for the event    
ItemBody body = new ItemBody 
{ 
    Content = "Status updates, blocking issues, and next steps", 
    ContentType = BodyType.Text 
}; 

// Create an attendee for the event    
Attendee[] attendees =  
{  
    new Attendee  
    {  
        Type = AttendeeType.Required,  
        EmailAddress = new EmailAddress  
        {  
            Address = "[email protected]"  
        },  
    },  
}; 

// Create the event object
Event newEvent = new Event 
{ 
    Subject = "Sync up", 
    Location = location, 
    Attendees = attendees, 
    Start = new DateTimeTimeZone()
    {
        TimeZone = TimeZoneInfo.Local.Id,
        DateTime = new DateTime(2015, 12, 1, 9, 30, 0).ToString("s")
    },
    End = new DateTimeTimeZone()
    {
        TimeZone = TimeZoneInfo.Local.Id,
        DateTime = new DateTime(2015, 12, 1, 10, 30, 0).ToString("s")
    },    
    Body = body 
};

// Add the event to the default calendar
await client.Me.Events.AddEventAsync(newEvent);

// Get the event ID.
string eventId = newEvent.Id;

        var event = new Microsoft.OutlookServices.Event();
        event.subject = 'Your Subject';
        event.start = new Date("October 30, 2014 11:13:00").toISOString();
        event.end = new Date("October 30, 2014 12:13:00").toISOString();

        // Body
        event.body = new Microsoft.OutlookServices.ItemBody();
        event.body.content = 'Body Content';
        event.body.contentType = Microsoft.OutlookServices.BodyType.Text;

        // Location
        event.location = new Microsoft.OutlookServices.Location();
        event.location.displayName = 'Location';

        // Attendee
        var attendee1 = new Microsoft.OutlookServices.Attendee();
        var emailAddress1 = new Microsoft.OutlookServices.EmailAddress();
        emailAddress1.name = "Katie Jordan";
        emailAddress1.address = "[email protected]";

        attendee1.emailAddress = emailAddress1;

        event.attendees.push(attendee1);

        outlookClient.me.calendar.events.addEvent(event)
        .then(function (response) {
            console.log(response._Id);
        });

outlookrestapiv2

outlookrestapiv1

This example assumes you already got the Outlook Services client.

// Create a location for the event
Location location = new Location 
{ 
    DisplayName = "Water cooler" 
}; 

// Create a description for the event    
ItemBody body = new ItemBody 
{ 
    Content = "Status updates, blocking issues, and next steps", 
    ContentType = BodyType.Text 
}; 

// Create an attendee for the event    
Attendee[] attendees =  
{  
    new Attendee  
    {  
        Type = AttendeeType.Required,  
        EmailAddress = new EmailAddress  
        {  
            Address = "[email protected]"  
        },  
    },  
}; 

// Create the event object
Event newEvent = new Event 
{ 
    Subject = "Sync up", 
    Location = location, 
    Attendees = attendees, 
    Start = new DateTimeOffset(new DateTime(2014, 12, 1, 9, 30, 0)), 
    End = new DateTimeOffset(new DateTime(2014, 12, 1, 10, 0, 0)), 
    Body = body 
}; 

// Add the event to the default calendar
await client.Me.Events.AddEventAsync(newEvent);

// Get the event ID.
string eventId = newEvent.Id;

        var event = new Microsoft.OutlookServices.Event();
        event.subject = 'Your Subject';
        event.start = new Date("October 30, 2014 11:13:00").toISOString();
        event.end = new Date("October 30, 2014 12:13:00").toISOString();

        // Body
        event.body = new Microsoft.OutlookServices.ItemBody();
        event.body.content = 'Body Content';
        event.body.contentType = Microsoft.OutlookServices.BodyType.Text;

        // Location
        event.location = new Microsoft.OutlookServices.Location();
        event.location.displayName = 'Location';

        // Attendee
        var attendee1 = new Microsoft.OutlookServices.Attendee();
        var emailAddress1 = new Microsoft.OutlookServices.EmailAddress();
        emailAddress1.name = "Katie Jordan";
        emailAddress1.address = "[email protected]";

        attendee1.emailAddress = emailAddress1;

        event.attendees.push(attendee1);

        outlookClient.me.calendar.events.addEvent(event)
        .then(function (response) {
            console.log(response._Id);
        });

outlookrestapiv1

Update events

REST API: Update a calendar event

Client libraries: Update a calendar event (Client)

Update a calendar event (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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": "Your office",
    "Address": null,
    "Coordinates": null,
    "LocationEmailAddress": "",
    "LocationUri": ""
  }
}

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": "Your office",
    "Address": null,
    "Coordinates": null,
    "LocationEmailAddress": "",
    "LocationUri": ""
  },
  "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": "[email protected]",
      "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.

outlookrestapibeta

outlookrestapiv2

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

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

Specify any writable event properties in the request body.

Sample request

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

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

Sample response

Status code: 200

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

Response type

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

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

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

outlookrestapiv2

outlookrestapiv1

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

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

Specify any writable event properties in the request body.

Sample request

PATCH https://outlook.office.com/api/v1.0/me/events/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA=

Content-Type: application/json

{
  "Location": {
    "DisplayName": "Your office"
  }
}

Name	Type	Value	Notes
event_id	string		The event ID.

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Events/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Events('AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA=",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==",
  "Categories": [],
  "DateTimeCreated": "2014-01-22T20:49:05.5657528Z",
  "DateTimeLastModified": "2014-01-22T21:14:17.4886416Z",
  "Subject": "Discuss the Calendar REST API",
  "BodyPreview": "I think it will meet our requirements!",
  "Body": {
    "ContentType": "HTML",
    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
  },
  "Importance": "Normal",
  "HasAttachments": false,
  "Start": "2014-02-02T18:00:00-08:00",
  "StartTimeZone": "Pacific Standard Time",
  "End": "2014-02-02T19:00:00-08:00",
  "EndTimeZone": "Pacific Standard Time",
  "Location": {
    "DisplayName": "Your office"
  },
  "ShowAs": "Busy",
  "IsAllDay": false,
  "IsCancelled": false,
  "IsOrganizer": true,
  "ResponseRequested": true,
  "Type": "SingleInstance",
  "SeriesMasterId": null,
  "Attendees": [],
  "Recurrence": null,
  "Organizer": {
    "EmailAddress": {
      "Address": "[email protected]",
      "Name": "alexd"
    }
  }
}

Response type

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

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

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

outlookrestapiv1

Update a calendar event (Client)

Change an event.

You can define multiple updates client-side and send the requests all at once (batch them) by using the following pattern:

Call UpdateAsync(true) for each entity you want to update. Specifying true registers the updates locally on the client but doesn't post them to the server.
Call client.Context.SaveChangesAsync() to post all updates that are registered locally.

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

outlookrestapiv2

This example assumes you already got the Outlook Services client and got the event ID.

// Get an existing event by ID
IEvent eventToUpdate = await client.Me.Events[eventId].ExecuteAsync();

// Add attendees
eventToUpdate.Attendees.Add(new Attendee
{
    Type = AttendeeType.Required,
    EmailAddress = new EmailAddress
    {
        Address = "[email protected]",
    },
});

// Make other changes
eventToUpdate.Start = new DateTimeOffset(new DateTime(2014, 12, 1, 14, 30, 0));
eventToUpdate.End = new DateTimeOffset(new DateTime(2014, 12, 1, 15, 0, 0));
eventToUpdate.Subject = "New event name";

// Commit all changes to the event
await eventToUpdate.UpdateAsync();

// Get an updated property.
string newEventName = eventToUpdate.Subject;

outlookrestapiv2

outlookrestapiv1

This example assumes you already got the Outlook Services client and got the event ID.

// Get an existing event by ID
IEvent eventToUpdate = await client.Me.Events[eventId].ExecuteAsync();

// Add attendees
eventToUpdate.Attendees.Add(new Attendee
{
    Type = AttendeeType.Required,
    EmailAddress = new EmailAddress
    {
        Address = "[email protected]",
    },
});

// Make other changes
eventToUpdate.Start = new DateTimeOffset(new DateTime(2014, 12, 1, 14, 30, 0));
eventToUpdate.End = new DateTimeOffset(new DateTime(2014, 12, 1, 15, 0, 0));
eventToUpdate.Subject = "New event name";

// Commit all changes to the event
await eventToUpdate.UpdateAsync();

// Get an updated property.
string newEventName = eventToUpdate.Subject;

outlookrestapiv1

Respond to events

REST API: Accept event (REST) | Tentatively accept event (REST) | Decline event (REST)

Accept event (REST)

Minimum required scope: one of the following:

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

Accept the specified event.

outlookrestapibeta

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.

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Content-Type: application/json

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

Response

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

outlookrestapiv2

outlookrestapiv1

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

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

Sample request

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

Content-Type: application/json

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

Response

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

outlookrestapiv1

Tentatively accept event (REST)

Minimum required scope: one of the following:

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

Tentatively accept the specified event.

outlookrestapibeta

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.

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Content-Type: application/json

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

Response

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

outlookrestapiv2

outlookrestapiv1

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

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

Sample request

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

Content-Type: application/json

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

Response

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

outlookrestapiv1

Decline event (REST)

Minimum required scope: one of the following:

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

Decline invitation to the specified event.

outlookrestapibeta

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.

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Content-Type: application/json

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

Response

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

outlookrestapiv2

outlookrestapiv1

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

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

Sample request

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

Content-Type: application/json

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

Response

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

outlookrestapiv1

Forward events (preview)

outlookrestapibeta

Minimum required scope: one of the following:

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

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":"[email protected]",
          "Name":"Dana Swope"
        }
      }
     ],
  "Comment": "Dana, hope you can make this meeting." 
}

Sample response

Status code: 202 Accepted

outlookrestapibeta

outlookrestapiv2

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Delete events

REST API: Delete a calendar event (REST)

Client libraries: Delete a calendar event (Client)

Delete a calendar event (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Sample response

Status code: 204

outlookrestapiv2

outlookrestapiv1

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

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

{
    "method": "DELETE",
    "resourceFormat": "https://outlook.office.com/api/v1.0/me/events/{event_id}",
    "requestUrl": "https://outlook.office.com/api/v1.0/me/events/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA=",
    "requestHeaders": {
        "Accept": "application/json"
    },
    "parameterDetails": [ 
                {
            "name": "event_id",
            "type": "string",
            "description": "The event ID.",
            "defaultValue": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA="
        }
    ],
    
    "statusCode": 204
    
}

outlookrestapiv1

Delete a calendar event (Client)

Move an event to the Deleted Items folder.

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

This example assumes you already got the Outlook Services client and got the event ID.

// Get an existing event by ID
IEvent eventToDelete = await client.Me.Events[eventId].ExecuteAsync();

//Delete the event
await eventToDelete.DeleteAsync();

Cancel events (preview)

outlookrestapibeta

Minimum required scope: one of the following:

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

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 Accepted

outlookrestapibeta

outlookrestapiv2

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Get attachments

You can get an attachment collection or get an attachment.

REST API: Get an attachment collection (REST) | Get an attachment (REST)

Get an attachment collection (REST)

Minimum required scope: one of the following:

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

Get the attachments from a particular event.

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

Response type

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

Sample request

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

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

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

Response type

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

Sample request

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

Name	Type	Value	Notes
event_id	string		The event ID.

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/CalendarGroups('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=')",
  "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=",
  "Name": "My Calendars",
  "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==",
  "ClassId": "0006f0b7-0000-0000-c000-000000000046"
}

outlookrestapiv1

Get an attachment (REST)

Minimum required scope: one of the following:

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

Get an attachment from a particular event.

outlookrestapibeta

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": "",
        "address": {
            "type": "unknown"
        },
        "coordinates": {
        }
    },
    "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": "[email protected]"
            }
        }
    ],
    "organizer": {
        "emailAddress": {
            "name": "Dana Swope",
            "address": "[email protected]"
        }
    },
    "webLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1Mbs88AADggYEcAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "onlineMeetingUrl": null,
    "[email protected]": "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
        }
    ]
}

outlookrestapibeta

outlookrestapiv2

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

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

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

Response type

The requested file attachment or item attachment.

Sample request

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

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

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

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

Response type

The requested file attachment or item attachment.

Sample request

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

Name	Type	Value	Notes
event_id	string		The event ID.
attachment_id	string		The attachment ID.

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/CalendarGroups('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=')",
  "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=",
  "Name": "My Calendars",
  "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==",
  "ClassId": "0006f0b7-0000-0000-c000-000000000046"
}

outlookrestapiv1

Create attachments

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

REST API: Create a file attachment (REST) | Create an item attachment (REST) | Create a reference attachment (REST)

Create a file attachment (REST)

Minimum required scope: one of the following:

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

Add a file attachment to an event.

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

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 (REST)

Minimum required scope: one of the following:

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

Add an item attachment to an event.

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

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 (REST)

outlookrestapibeta

Required scope: https://outlook.office.com/mail.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
}

Sample request

The following example adds a reference attachment in the same call as creating an event. The attachment is a link to a file on OneDrive for Business.

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

{
  "Subject": "Plan Easter egg hunt!",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get organized for this weekend's gathering."
  },
  "Start": {
      "DateTime": "2016-03-25T10:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2016-03-25T11:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "[email protected]",
        "Name": "Randi Welch"
      },
      "Type": "Required"
    }
  ],
  "Attachments": [
      {
        "@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/$entity",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAA4KZrrg==\"",
    "Id": "AAMkAGE1Mbs88AADggYEbAAA=",
    "CreatedDateTime": "2016-03-22T22:09:26.2918604Z",
    "LastModifiedDateTime": "2016-03-22T22:09:27.0754806Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAA4KZrrg==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "040000008200E00074C5B7101A82E0080000000043FB607F8784D101000000000000000010000000B3A31CD7479252448ECE77242DE92587",
    "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-25T10:00:00.0000000",
        "TimeZone": "Pacific Standard Time"
    },
    "End": {
        "DateTime": "2016-03-25T11:00:00.0000000",
        "TimeZone": "Pacific Standard Time"
    },
    "Location": {
        "DisplayName": "",
        "Address": {
            "Type": "unknown"
        },
        "Coordinates": {
        }
    },
    "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": "[email protected]"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Dana Swope",
            "Address": "[email protected]"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1Mbs88AADggYEbAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "OnlineMeetingUrl": null,
    "[email protected]": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events('AAMkAGE1Mbs88AADZ0CU9AAA%3D')/attachments",
    "Attachments": [
    {
      "@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
      "Id": "AAMkAGE1Mbs88AADZ0CU9AAABEgAQAGe4H1iqXwtLsrCCLLkDxqo=",
      "LastModifiedDateTime": null,
      "Name": Hydrangea picture,
      "ContentType": null,
      "Size": 0,
      "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
    }
    ]
}

outlookrestapibeta

outlookrestapiv2

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Delete attachments

Delete attachments of an event.

REST API: Delete an event attachment (REST)

Delete an event attachment (REST)

Minimum required scope: one of the following:

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

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

Sample request

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

Sample response

Status code: 204

outlookrestapiv2

outlookrestapiv1

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

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

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

{
    "method": "DELETE",
    "resourceFormat": "https://outlook.office.com/api/v1.0/me/events/{event_id}/attachments/{attachment_id}",
    "requestUrl": "https:/outlook.office.com/api/v1.0/me/events/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA=/attachments/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA=",
    "requestHeaders": {
        "Accept": "application/json"
    },
    "parameterDetails": [
        {
            "name": "event_id",
            "type": "string",
            "description": "The event ID.",
            "defaultValue": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAENAAAmP1Ln1wcHRariNdTMGAO9AAAV4v1OAAA="
        },
        {
            "name": "event_id",
            "type": "string",
            "description": "The attachment ID.",
            "defaultValue": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAENAACd9nJ-tVysQos2hTfspaWRAAADTG9yAAA="
        }
    ],
    "statusCode": 204

}

outlookrestapiv1

Get reminders

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

Minimum required scope: one of the following:

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

outlookrestapibeta

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.

outlookrestapibeta

outlookrestapiv2

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

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Snooze reminders

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

Minimum required scope: one of the following:

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

outlookrestapibeta

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.

outlookrestapibeta

outlookrestapiv2

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.

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Dismiss reminders

Dissmiss a reminder that has been triggered.

Minimum required scope: one of the following:

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

outlookrestapibeta

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

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

outlookrestapibeta

outlookrestapiv2

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

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

outlookrestapiv2

outlookrestapiv1

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

outlookrestapiv1

Get calendars

You can get a calendar collection or get a calendar.

REST API: Get a calendar collection (REST) | Get a calendar (REST)

Client libraries: Get a calendar collection or a calendar (Client)

Get a calendar collection (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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":"[email protected]"
            }
        }
    ]
}

outlookrestapibeta

outlookrestapiv2

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

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

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

Sample request

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

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

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

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

Sample request

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

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Calendars('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=",
      "Name": "Calendar",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w=="
    }
  ]
}

Response type

The requested calendar collection.

outlookrestapiv1

Get a calendar (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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":"[email protected]"
    }
}

outlookrestapibeta

outlookrestapiv2

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

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

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

Sample request

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

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

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

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

Sample request

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

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Calendars('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=')",
  "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=",
  "Name": "Calendar",
  "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w=="
}

outlookrestapiv1

Response type

The requested calendar.

Get a calendar collection or a calendar (Client)

Get the user's calendars. To get the user's default calendar, use the client.Me.Calendar shortcut property. To get a different calendar, specify the calendar ID as the index of the Calendars collection or use the GetById method.

Example: client.Me.Calendars[calendarId].ExecuteAsync()

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

Note Calendar collections support query expressions such as Select, OrderBy, and Take.

This example calls the method that gets the Outlook Services client.

var outlookClient = await CreateOutlookClientAsync("Calendar");
var calendars = await outlookClient.Me.Calendars
  .Take(10)
  .ExecuteAsync();

foreach(var calendar in calendars.CurrentPage)
{
  System.Diagnostics.Debug.WriteLine("Calendar '{0}'.", calendar.Name);
}

outlookClient.me.calendars.getCalendars().fetchAll(100).then(function(result) {
    result.forEach(function (calendar) {
        console.log('Calendar "' + calendar.name + '", URL ' + calendar.path)
    });
}, function(error) {
    console.log(error);
});

Create calendars

REST API: Create a calendar (REST)

Client libraries: Create a calendar (Client)

Create a calendar (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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":"[email protected]"
    }
}

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

{
  "Name": "Social"
}

Sample response

Status code: 201

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

outlookrestapiv2

outlookrestapiv1

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

Required 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/v1.0/me/calendars

Content-Type: application/json

{
  "Name": "Social"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Calendars('AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLHAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLHAAA=",
  "Name": "Social",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ=="
}

outlookrestapiv1

Response type

The new calendar.

Create a calendar (Client)

Create a calendar. See Create events for an example of how to create an event.

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

This example assumes you already got the Outlook Services client.

Calendar newCal = new Calendar
{
    Name = "Personal"
};

// Add the calendar to the Calendars collection
await client.Me.Calendars.AddCalendarAsync(newCal);

// Get the ID of the calendar
string calendarId = newCal.Id;

Update calendars

REST API: Update a calendar (REST)

Client libraries: Update a calendar (Client)

Update a calendar (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID.
Body parameters
Name	string	The new name of the calendar.

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":"[email protected]"
    }
}

outlookrestapibeta

outlookrestapiv2

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

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID.
Body parameters
Name	string	The new name of the calendar.

Sample request

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

{
  "Name": "Social events"
}

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

Required parameter	Type	Description
URL parameters
calendar_id	string	The calendar ID.
Body parameters
Name	string	The new name of the calendar.

Sample request

PATCH https://outlook.office.com/api/v1.0/me/calendars/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA=

Content-Type: application/json

{
  "Name": "Social events"
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Calendars/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/Calendars('AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA=",
  "Name": "Social events",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw=="
}

outlookrestapiv1

Response type

The updated calendar.

Update a calendar (Client)

Change the name of a calendar. Name is the only writeable property for a calendar.

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

This example assumes you already got the Outlook Services client and got the calendar ID.

// Get an existing calendar by ID
ICalendar calendarToUpdate = await client.Me.Calendars[calendarId].ExecuteAsync();
calendarToUpdate.Name = "Family";

// Commit the change
await calendarToUpdate.UpdateAsync();

// Get the updated property
string newCalendarName = calendarToUpdate.Name;

You can define multiple updates client-side and send the requests all at once (batch them) by using the following pattern:

Call UpdateAsync(true) for each entity you want to update. Specifying true registers the updates locally on the client but doesn't post them to the server.
Call client.Context.SaveChangesAsync() to post all updates that are registered locally.

Delete calendars

Delete a calendar.

REST API: Delete a calendar (REST)

Client libraries: Delete a calendar (Client)

Delete a calendar (REST)

Minimum required scope: one of the following:

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Sample response

Status code: 204

outlookrestapiv2

outlookrestapiv1

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

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

{
    "method": "DELETE",
    "resourceFormat": "https://outlook.office.com/api/v1.0/me/calendars/{calender_id}",
    "requestUrl": "https://outlook.office.com/api/v1.0/me/calendars/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA=",
    "requestHeaders": {
        "Accept": "application/json"
    },
    "parameterDetails": [
        {
            "name": "calender_id",
            "type": "string",
            "description": "The calendar ID.",
            "defaultValue": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA="
        }
    ],
    "statusCode": 204

}

outlookrestapiv1

Delete a calendar (Client)

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

This example assumes you already got the Outlook Services client and got the calendar ID.

// Get an existing calendar by ID
ICalendar calendarToDelete = await client.Me.Calendars[calendarId].ExecuteAsync();

// Delete the calendar
await calendarToDelete.DeleteAsync(false);

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.

REST API: Get a calendar group collection (REST) | Get a calendar group (REST)

Client libraries: Get calendar groups (Client)

Get a calendar group collection (REST)

Minimum required scope: one of the following:

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

Get the calendar groups in a mailbox.

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

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

Sample request

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

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/CalendarGroups('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=",
      "Name": "My Calendars",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==",
      "ClassId": "0006f0b7-0000-0000-c000-000000000046"
    },
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/CalendarGroups('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuMAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x0/A==\"",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuMAAA=",
      "Name": "Other Calendars",
      "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0/A==",
      "ClassId": "0006f0b8-0000-0000-c000-000000000046"
    }
  ]
}

outlookrestapiv1

Response type

The requested calendar group collection.

Get a calendar group (REST)

Minimum required scope: one of the following:

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

Get a calendar group by ID.

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

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

Sample request

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

Sample response

Status code: 200

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

outlookrestapiv2

outlookrestapiv1

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

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

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

Sample request

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

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/CalendarGroups('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=')",
  "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuKAAA=",
  "Name": "My Calendars",
  "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g==",
  "ClassId": "0006f0b7-0000-0000-c000-000000000046"
}

outlookrestapiv1

Response type

The requested calendar group.

Get calendar groups (Client)

Get a user's calendar groups. To get a different calendar group, specify the calendar group ID as the index of the CalendarGroups collection or use the GetById method.

Example: client.Me.CalendarGroups[calendarGroupId].ExecuteAsync()

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

Note Calendar group collections support query expressions such as Select, OrderBy, and Take.

This example assumes you already got the Outlook Services client.

IPagedCollection<ICalendarGroup> calendarGroupsResults = await client.Me.CalendarGroups.ExecuteAsync();

// Get the ID of the first calendar group
string groupId = calendarGroupsResults.CurrentPage[0].Id;

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.

REST API: Create a calendar group (REST)

Client libraries: Create a calendar group (Client)

Create a calendar group (REST)

Minimum required scope: one of the following:

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

{
  "Name": "Birthdays"
}

Sample response

Status code: 201

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

outlookrestapiv2

outlookrestapiv1

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

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

Sample request

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

Content-Type: application/json

{
  "Name": "Birthdays"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('[email protected]')/CalendarGroups('AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Rw==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=",
  "Name": "Birthdays",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Rw==",
  "ClassId": "4d969bba-8942-42a0-ae33-c7d4410d1e11"
}

outlookrestapiv1

Response type

The new calendar group.

Create a calendar group (Client)

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

This example assumes you already got the Outlook Services client.

CalendarGroup newCalendarGroup = new CalendarGroup
{
    Name = "Business"
};

// Add it to the CalendarGroups collection
await client.Me.CalendarGroups.AddCalendarGroupAsync(newCalendarGroup);

// Get the ID of the calendar group
string calendarGroupId = newCalendarGroup.Id;

Update calendar groups

REST API: Update a calendar group (REST)

Client libraries: Update a calendar group (Client)

Update a calendar group (REST)

Minimum required scope: one of the following:

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

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

{
  "Name": "Holidays"
}

Sample response

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

outlookrestapiv2

outlookrestapiv1

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

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

Sample request

PATCH https://outlook.office.com/api/v1.0/me/calendargroups/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=

{
  "Name": "Holidays"
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/CalendarGroups/$entity",
  "@odata.id": "https://https://outlook.office.com/api/v1.0/Users('[email protected]')/CalendarGroups('AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SA==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=",
  "Name": "Holidays",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SA==",
  "ClassId": "4d969bba-8942-42a0-ae33-c7d4410d1e11"
}

outlookrestapiv1

Response type

The updated calendar group.

Update a calendar group (Client)

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

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

This example assumes you already got the Outlook Services client and got the calendar group ID.

// Get an existing calendar group by ID
ICalendarGroup groupToUpdate = await client.Me.CalendarGroups[groupId].ExecuteAsync();
groupToUpdate.Name = "Contoso";

// Commit the change
await groupToUpdate.UpdateAsync();

// Get the updated property
string newCalendarGroupName = groupToUpdate.Name;

You can define multiple updates client-side and send the requests all at once (batch them) by using the following pattern:

Call UpdateAsync(true) for each entity you want to update. Specifying true registers the updates locally on the client but doesn't post them to the server.
Call client.Context.SaveChangesAsync() to post all updates that are registered locally.

Delete calendar groups

Delete a calendar group.

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

REST API: Delete a calendar group (REST)

Client libraries: Delete a calendar group (Client)

Delete a calendar group (REST)

Minimum required scope: one of the following:

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

outlookrestapibeta

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

outlookrestapibeta

outlookrestapiv2

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

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

Sample request

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

Sample response

Status code: 204

outlookrestapiv2

outlookrestapiv1

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

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

{
    "method": "DELETE",
    "resourceFormat": "https://outlook.office.com/api/v1.0/me/calendargroups/{calendar_group_id}",
    "requestUrl": "https://outlook.office.com/api/v1.0/me/calendargroups/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA=",
    "requestHeaders": {
        "Accept": "application/json"
    },
    "parameterDetails": [
        {
            "name": "calendar_group_id",
            "type": "string",
            "description": "The calendar group ID.",
            "defaultValue": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLGAAA="
        }
    ],
    "statusCode": 204

}

outlookrestapiv1

Delete a calendar group (Client)

Attention If you're accessing mailbox data on Outlook.com, do not use the client libraries and call the REST API directly.

This example assumes you already got the Outlook Services client and got the calendar group ID.

// Get an existing calendar group by ID
ICalendarGroup groupToDelete = await client.Me.CalendarGroups[groupId].ExecuteAsync();

// Delete the group
await groupToDelete.DeleteAsync();

Next steps

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

Get started with Mail, Calendar, and Contacts REST APIs.
Explore the Office REST APIs using the interactive API Sandbox.
Want samples? We've got them.

Or, learn more about using the Office 365 platform:

Shared to

Outlook Calendar REST API reference

All Calendar API operations

Using the Calendar REST API

Authentication

Version of API

Target user

Get events

Get a calendar view (REST)

Get series master and single events (REST)

Sample request

Sample response

Get event instances (REST)

Get an event (REST)

Sample request

Parameters

Sample response

Sample request

Parameters

Sample response

Get events from the user's calendar (Client)

Sync events

Find meeting times

Find time and location to meet with specific attendees (REST)

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

Find time to meet but no attendee is available (REST)

Find time to meet but only some attendees are available (REST)

Find free time slots for just the signed-in user (REST)

Find time and location to meet with specific attendees (REST)

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

Find time to meet but no attendee is available (REST)

Find time to meet but only some attendees are available (REST)

Find free time slots for just the signed-in user (REST)

Create events

Create a calendar event (REST)

Sample request

Sample response

Create a calendar event (Client)

Update events

Update a calendar event (REST)

Sample request

Parameters

Sample response

Update a calendar event (Client)

Respond to events

Accept event (REST)

Tentatively accept event (REST)

Decline event (REST)

Forward events (preview)

Delete events

Delete a calendar event (REST)

Delete a calendar event (Client)

Cancel events (preview)

Get attachments

Get an attachment collection (REST)

Sample request

Parameters

Sample response

Get an attachment (REST)

Sample request

Parameters

Sample response

Create attachments

Create a file attachment (REST)

Create an item attachment (REST)

Create a reference attachment (REST)

Delete attachments

Delete an event attachment (REST)

Get reminders

Snooze reminders

Dismiss reminders

Get calendars

Get a calendar collection (REST)

Sample request

Sample response

Get a calendar (REST)

Sample request

Parameters

Sample response

Get a calendar collection or a calendar (Client)