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

Article
10/21/2021

Note

Version 1.0 of the Outlook REST API is deprecated.

As announced in October 2017, version 1.0 of the Outlook REST API has been deprecated. The v1.0 REST endpoint will be fully decommissioned, and the v1.0 documentation will be removed shortly afterwards. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

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

Note

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

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

All Calendar API operations

Event operations

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

Get events
Sync events
Create events
Update events
Respond to events
Delete events
Get attachments
Create attachments
Delete attachments
Get reminders
Snooze reminders
Dismiss reminders

Calendar operations

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

Get calendars
Create calendars
Update calendars
Delete calendars

Calendar group operations

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

Note

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

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

Using the Calendar REST API

Authentication

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

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

Scopes to access shared calendars

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

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

Version of API

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

Target user

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

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

Get events

Get an event collection or an event.

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

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

Get a calendar view

Minimum required scope

One of the following:

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

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

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

Note

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

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

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

Response type

The expanded events within the specified time range.

Get series master and single events

Minimum required scope

One of the following:

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

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

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

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

Sample response

Status code: 200

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

Get event instances

Minimum required scope

One of the following:

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

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

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

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

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

Get an event

Minimum required scope

One of the following:

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

Get an event by ID.

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=

Sample response

Status code: 200

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

Response type

The requested event.

Note

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

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

Sample request

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

Sample response

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

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 @odata.deltaLink header with a deltaToken again, which indicates the sync is complete.

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

To sync in the default calendar

Initial request:

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

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

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

Sample initial request

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

Sample initial response data

Preference-Applied: odata.track-changes

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

Sample second request

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

Sample second response data

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

Find meeting times

This feature is currently available in the v2.0 and beta versions.

Get meeting rooms (preview)

This feature is currently available in only the beta version.

Create events

Create a calendar event

Create a calendar event

Minimum required scope

One of the following:

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

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

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": "janets@a830edad9050849NDA1.onmicrosoft.com",
        "Name": "Janet Schorr"
      },
      "Type": "Required"
    }
  ]
}

Sample response

Status code: 201

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

Response type

The new event.

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

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

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

Update events

Update a calendar event

Update a calendar event

Minimum required scope

One of the following:

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

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

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

Sample response

Status code: 200

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

Response type

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

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

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

Accept event

Minimum required scope

One of the following:

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

Accept the specified event.

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

Tentatively accept event

Minimum required scope

One of the following:

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

Tentatively accept the specified event.

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

Decline event

Minimum required scope

One of the following:

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

Decline invitation to the specified event.

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

Forward events (preview)

This feature is currently available in only the beta version.

Delete events

Delete a calendar event

Delete a calendar event

Minimum required scope

One of the following:

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

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

DELETE https://outlook.office.com/api/v1.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/v1.0/me/events/AAMkAGE0M4v1OAAA=

Sample response

Status code: 204

Cancel events (preview)

This feature is currently available in only the beta version.

Get attachments

You can get an attachment collection or get an attachment.

Get an attachment collection
Get an attachment

Get an attachment collection

Minimum required scope

One of the following:

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

Get the attachments from a particular event.

Note

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

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

Sample response

Status code: 200

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

Get an attachment

Minimum required scope

One of the following:

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

Get an attachment from a particular event.

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=

Sample response

Status code: 200

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

Create attachments

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

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

Create a file attachment

Minimum required scope

One of the following:

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

Add a file attachment to an event.

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

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

Response type

The new file attachment.

Create an item attachment

Minimum required scope

One of the following:

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

Add an item attachment to an event.

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

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

Response type

The new item attachment.

Create a reference attachment

Minimum required scope

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

Add a reference attachment to an event.

This feature is currently available in only the beta version.

Delete attachments

Delete an event attachment

Delete an event attachment

Minimum required scope

One of the following:

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

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

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

Sample request

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

Sample response

Status code: 204

Get reminders

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

Minimum required scope

One of the following:

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

This feature is currently available in the v2.0 and beta versions.

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

This feature is currently available in the v2.0 and beta versions.

Dismiss reminders

Dismiss a reminder that has been triggered.

Minimum required scope

One of the following:

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

This feature is currently available in the v2.0 and beta versions.

Get calendars

You can get a calendar collection or get a calendar.

Get a calendar collection
Get a calendar

Get a calendar collection

Minimum required scope

One of the following:

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

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

GET https://outlook.office.com/api/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('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9xAAA=')",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=",
            "Name": "Calendar",
            "Color": "Auto",
            "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w=="
        }
    ]
}

Response type

The requested calendar collection.

Get a calendar

Minimum required scope

One of the following:

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

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

GET https://outlook.office.com/api/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('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG9xAAA=')",
    "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEGAACd9nJ-tVysQos2hTfspaWRAAADTGuLAAA=",
    "Name": "Calendar",
    "Color": "Auto",
    "ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w=="
}

Response type

The requested calendar.

Create calendars

Create a calendar

Create a calendar

Minimum required scope

One of the following:

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

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

POST https://outlook.office.com/api/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('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLHAAA=",
  "Name": "Social",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SQ=="
}

Response type

The new calendar.

Update calendars

Update a calendar

Update a calendar

Minimum required scope

One of the following:

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

Change writable properties of a calendar.

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('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw==\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEGAAAmP1Ln1wcHRariNdTMGAO9AAAV4xLIAAA=",
  "Name": "Social events",
  "ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Sw=="

Response type

The updated calendar.

Delete calendars

Delete a calendar

Delete a calendar

Minimum required scope

One of the following:

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

DELETE https://outlook.office.com/api/v1.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/v1.0/me/calendars/{calendar_id}

Sample response

Status code: 204

Get calendar groups

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

Get a calendar group collection
Get a calendar group

Note

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

Get a calendar group collection

Minimum required scope

One of the following:

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

Get the calendar groups in a mailbox.

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

Note

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

Sample request

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

Sample response

Status code: 200

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

Response type

The requested calendar group collection.

Get a calendar group

Minimum required scope

One of the following:

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

Get a calendar group by ID.

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

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

Response type

The requested calendar group.

Create calendar groups

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

Create a calendar group

Note

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

Create a calendar group

Minimum required scope

One of the following:

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

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

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

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

Content-Type: application/json

{
  "Name": "Birthdays"
}

Sample response

Status code: 201

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

Response type

The new calendar group.

Update calendar groups

Update a calendar group

Update a calendar group

Minimum required scope

One of the following:

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

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

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

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

{
  "Name": "Holidays"
}

Sample response

Status code: 200

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

Response type

The updated calendar group.

Delete calendar groups

Delete a calendar group

Note

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

Delete a calendar group

Minimum required scope

One of the following:

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

DELETE https://outlook.office.com/api/v1.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/v1.0/me/calendargroups/AAMkAGE0MGM4xLGAAA=

Sample response

Status code: 204

Next steps

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

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

Or, learn more about using the Office 365 platform:

Share via

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

All Calendar API operations

Event operations

Calendar operations

Calendar group operations

See also

Using the Calendar REST API

Authentication

Scopes to access shared calendars

Version of API

Target user

Get events

Get a calendar view

Minimum required scope

Response type

Get series master and single events

Minimum required scope

Sample request

Sample response

Get event instances

Minimum required scope

Response type

Get an event

Minimum required scope

Sample request

Sample response

Response type

Sample request

Sample response

Sync events

Minimum required scope

Request headers

To sync in the default calendar

To sync in a specific calendar

Parameters

Response type

Example

Find meeting times

Get meeting rooms (preview)

Create events

Create a calendar event

Minimum required scope

Sample request

Sample response

Response type

Update events

Update a calendar event

Minimum required scope

Sample request

Sample response

Response type

Respond to events

Accept event

Minimum required scope

Sample request

Response

Tentatively accept event

Minimum required scope

Sample request

Response

Decline event

Minimum required scope

Sample request

Response

Forward events (preview)

Delete events

Delete a calendar event

Minimum required scope

Sample request

Sample response

Cancel events (preview)

Get attachments

Get an attachment collection

Minimum required scope

Response type

Sample request

Sample response

Get an attachment

Minimum required scope