[DEPRECATED] Outlook Calendar REST API reference (beta)
Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
Note
The beta version of the Outlook REST API is deprecated.
As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. Consequently, the beta REST endpoint is also deprecated and will be fully decommissioned in November 2022. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.
The Calendar API provides access to events, calendar, and calendar group data secured by Azure Active Directory on Office 365, and to similar data in Microsoft accounts specifically in these domains: Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.
Note
- The exception is the API to find meeting times, which applies to only Office 365 mailboxes (on Azure AD) and not to Microsoft accounts.
- For simplicity of reference, the rest of this article uses Outlook.com to include these Microsoft account domains.
Not interested in the beta version of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.
All Calendar API operations
Event operations
An event represents an appointment or meeting on the user's calendar. An event can be a series master (for recurring events), an occurrence, a single instance, or an exception.
- Get events
- Sync events
- Find meeting times
- Get meeting rooms (preview)
- Create events
- Update events
- Respond to events
- Forward events (preview)
- Delete events
- Cancel events (preview)
- Get attachments
- Create attachments
- Delete attachments
- Get reminders
- Snooze reminders
- Dismiss reminders
Calendar operations
A calendar serves as a container for events. A user can have multiple calendars. In Office 365, each calendar can be assigned to a calendar group.
Calendar group operations
Calendar groups are a way to organize multiple calendars. Users can add multiple calendars into a single calendar group in Outlook or Outlook Web App. This makes it easier for users to quickly view all calendars within the group.
Note
Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut. You cannot delete that calendar group, or create another calendar group.
See also
Using the Calendar REST API
Authentication
Like other Outlook REST API, for every request to the Calendar API, you should include a valid access token. Getting an access token requires you to have registered and identified your app, and obtained the appropriate authorization.
You can find out more about some streamlined registration and authorization options for you. Keep this in mind as you proceed with the specific operations in the Calendar API.
Scopes to access shared calendars
Office 365 and Outlook.com calendars support sharing. A user who created a calendar can share the calendar with other users. The following scopes are required to access a calendar that has been shared with that user:
- For read access:
https://outlook.office.com/calendars.read.shared - For read/write access:
https://outlook.office.com/calendars.readwrite.shared
Version of API
The Calendar REST API is supported in all versions of the Outlook REST API. The functionality may differ depending on the specific version.
Target user
The Calendar API requests are always performed on behalf of the current user.
See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.
Get events
Get an event collection or an event.
An event body can be in either text or HTML.
You can use the Prefer: outlook.body-content-type header to specify the desired format returned in the Body property in a GET request:
- Specify
Prefer: outlook.body-content-type="text"to get an event body returned in text format. - Specify
Prefer: outlook.body-content-type="html", or just skip the header, to return the event body in HTML format.
If you specify either header, the response will include the corresponding Preference-Applied header as confirmation:
- For text format requests:
Preference-Applied: outlook.body-content-type="text" - For HTML format requests:
Preference-Applied: outlook.body-content-type="html"
All operations that get calendar events can use the Prefer: outlook.timezone HTTP header to specify the time zone for start and end times in the response. For example, the following Prefer: outlook.timezone header sets the start and end times in the response to Eastern Standard Time.
Prefer: outlook.timezone="Eastern Standard Time"
If you do not specify the Prefer: outlook.timezone header, the start and end times in the response are returned in UTC.
You can use the OriginalStartTimeZone and OriginalEndTimeZone properties on the Event resource to find out the time zone used when the event was created.
Get a calendar view
Minimum required scope
One of the following:
- 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/beta/me/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}
GET https://outlook.office.com/api/beta/me/calendars/{calendar_id}/calendarview?startDateTime={start_datetime}&endDateTime={end_datetime}
| Required parameter | Type | Description |
|---|---|---|
| Header parameters | ||
| Prefer: | outlook.timezone | The default time zone for events in the response. |
| URL parameters | ||
| calendar_id | string | The calendar ID, if you're getting a calendar view from a specific calendar. |
| start_datetime | datetimeoffset | The date and time when the event starts. |
| end_datetime | datetimeoffset | The date and time when the event ends. |
Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.
See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.
Note
By default, each event in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
For example, get the calendar view for the month of October, returning only the Subject property for each event. Assuming that the Prefer: outlook.timezone header is not included in the request, the time zone will be UTC.
GET https://outlook.office.com/api/beta/me/calendarview?startDateTime=2014-10-01T01:00:00Z&endDateTime=2014-10-31T23:00:00Z&$select=Subject
Response type
The expanded events within the specified time range.
Get series master and single events
Minimum required scope
One of the following:
- 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/beta/me/events
GET https://outlook.office.com/api/beta/me/calendars/{calendar_id}/events
| Required parameter | Type | Description |
|---|---|---|
| _Header parameters | ||
| Prefer: | outlook.timezone | The default time zone for events in the response. |
| URL parameters | ||
| calendar_id | string | The calendar ID, if you're getting events from a specific calendar. |
Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.
See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, start and end times are returned in UTC.
Note
Each event in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See the next example. See OData query parameters for filtering, sorting, and paging parameters.
The following example shows how to use $select to specify returning only the Subject, Organizer, Start and End properties of each event in the response. Refer to the first sample response in Get an event (REST) for a full list of properties that would be returned for an event if you don't use $select.
Sample request
GET https://outlook.office.com/api/beta/me/events?$select=Subject,Organizer,Start,End,Location,Locations
Sample response
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer,Start,End,Location,Locations)",
"value":[
{
"@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/Events('AAMkADNWAACYBXsvAAA=')",
"@odata.etag":"W/\"SuFHwDRP1EeXJUopWbSLlgAAmBvk2g==\"",
"Id":"AAMkADNWAACYBXsvAAA=",
"Subject":"Plan summer company picnic",
"Start":{
"DateTime":"2017-06-09T18:00:00.0000000",
"TimeZone":"UTC"
},
"End":{
"DateTime":"2017-06-09T19:00:00.0000000",
"TimeZone":"UTC"
},
"Location":{
"DisplayName":"Conf Room 3; Fourth Coffee; Home Office",
"LocationType":"Default"
},
"Locations":[
{
"DisplayName":"Conf Room 3",
"LocationType":"Default"
},
{
"DisplayName":"Fourth Coffee",
"LocationType":"Default",
"Address":{
"Type":"Unknown",
"Street":"4567 Main St",
"City":"Redmond",
"State":"WA",
"CountryOrRegion":"US",
"PostalCode":"32008"
},
"Coordinates":{
"Latitude":47.672,
"Longitude":-102.103
}
},
{
"DisplayName":"Home Office",
"LocationType":"Default"
}
],
"Organizer":{
"EmailAddress":{
"Name":"Alex Wilbur",
"Address":"AlexW@contoso.onmicrosoft.com"
}
}
},
{
"@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/Events('AAMkADNPkvzAAA=')",
"@odata.etag":"W/\"SuFHwDRP1EeXJUopWbSLlgAAdE6yjA==\"",
"Id":"AAMkADNPkvzAAA=",
"Subject":"Customer visit",
"Start":{
"DateTime":"2017-04-20T21:00:00.0000000",
"TimeZone":"UTC"
},
"End":{
"DateTime":"2017-04-20T23:00:00.0000000",
"TimeZone":"UTC"
},
"Location":{
"DisplayName":"",
"LocationType":"Default",
"Address":{
"Type":"Unknown"
},
"Coordinates":{
}
},
"Locations":[
],
"Organizer":{
"EmailAddress":{
"Name":"Alex Wilbur",
"Address":"AlexW@contoso.onmicrosoft.com"
}
}
}
]
}
Get event instances
Minimum required scope
One of the following:
- 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/beta/me/events/{event_id}/instances?startDateTime={start_datetime}&endDateTime={end_datetime}
| Required parameter | Type | Description |
|---|---|---|
| Header parameters | ||
| Prefer: | outlook.timezone | The default timezone for events in the response. |
| URL parameters | ||
| event_id | string | The event ID. |
| start_datetime | datetimeoffset | The UTC date and time when the event starts. |
| end_datetime | datetimeoffset | The UTC date and time when the event ends. |
Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.
See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.
Response type
The requested event collection.
Note
By default, each event in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
For example, get the instances of a particular event for the month of October, include only the Subject, Start and End properties of each instance:
GET https://outlook.office.com/api/beta/me/events/AAMkAGE0MGM1Y2M5LWEAAA=/instances?startDateTime=2014-10-01T01:00:00Z&endDateTime=2014-10-31T23:00:00Z&$select=Subject,Start,End
Get an event
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.read
- wl.calendars
- wl.contacts_calendars
Get an event by ID.
GET https://outlook.office.com/api/beta/me/events/{event_id}
| Required parameter | Type | Description |
|---|---|---|
| Header parameters | ||
| Prefer: | outlook.timezone | The default timezone for events in the response. |
| URL parameters | ||
| event_id | string | The event ID. |
Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.
See this list for the supported time zone names.If the Prefer: outlook.timezone header is not specified, the start and end times are returned in UTC.
Sample request
GET https://outlook.office.com/api/beta/me/events/AAMkAGI2TG93AAA=
Sample response
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG93AAA=')",
"@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48w==\"",
"Id": "AAMkAGI2TG93AAA=",
"ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x48w==",
"Categories": [],
"CreatedDateTime": "2014-10-19T23:13:47.3959685Z",
"LastModifiedDateTime": "2014-10-19T23:13:47.6772234Z",
"Subject": "Weekly Meeting on Contoso Project",
"BodyPreview": "Setting up some time to review the budget and planning on the Contoso Project",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nSetting up some time to review the budget and planning on the Contoso Project\r\n</body>\r\n</html>\r\n"
},
"Importance": "Normal",
"HasAttachments": false,
"Start": {
"DateTime": "2014-10-13T21:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2014-10-13T22:00:00",
"TimeZone": ""Pacific Standard Time"
},
"Location": {
"DisplayName": "Alex's Office",
},
"Locations":[
{
"DisplayName": "Alex's Office",
}
]
"ShowAs": "Busy",
"IsAllDay": false,
"IsCancelled": false,
"IsOrganizer": true,
"ResponseRequested": true,
"Type": "SeriesMaster",
"SeriesMasterId": null,
"Attendees": [
{
"EmailAddress": {
"Address": "janets@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Janet Schorr"
},
"Status": {
"Response": "None",
"Time": "0001-01-01T00:00:00Z"
},
"Type": "Required"
},
{
"EmailAddress": {
"Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Pavel Bansky"
},
"Status": {
"Response": "None",
"Time": "0001-01-01T00:00:00Z"
},
"Type": "Required"
}
],
"Recurrence": {
"Pattern": {
"Type": "Weekly",
"Interval": 1,
"Month": 0,
"Index": "First",
"FirstDayOfWeek": "Sunday",
"DayOfMonth": 0,
"DaysOfWeek": [
"Monday"
]
},
"RecurrenceTimeZone": "Pacific Standard Time",
"Range": {
"Type": "NoEnd",
"StartDate": "2014-10-13",
"EndDate": "2014-11-13",
"NumberOfOccurrences": 0
}
},
"OriginalEndTimeZone": "Pacific Standard Time",
"OriginalStartTimeZone": "Pacific Standard Time",
"Organizer": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"OnlineMeetingUrl": null
}
Response type
The requested event.
Note
By default, the response includes all the properties of the event. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
The following example shows how to use $select to specify returning only the Subject, Organizer, Start and End properties of the event.
Sample request
GET https://outlook.office.com/api/beta/me/events/AAMkAGI2TG93AAA=?$select=Subject,Organizer,Start,End
Sample response
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2TG93AAA=')",
"@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAAA0x48w==\"",
"Id": "AAMkAGI2TG93AAA=",
"Subject": "Weekly Meeting on Contoso Project",
"Start": {
"DateTime": "2014-10-13T21:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2014-10-13T22:00:00",
"TimeZone": ""Pacific Standard Time"
},
"Organizer": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
}
}
Sync events
Minimum required scope
One of the following:
- 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
skipTokenthat 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 askipTokenin 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/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$searchquery 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
deltaLinkanddeltaToken. - The second request uses that
deltatoken. The second response returns one event, anextLinkandskipToken.
To complete the sync, use the skipToken returned from the previous sync request until the sync response returns a
deltaLink and deltaToken, in which case this round of sync is complete. Save the deltaToken for the next round of sync.
For more information, see Synchronize events in an Outlook calendar view.
Sample initial request
GET https://outlook.office.com/api/beta/me/calendarview?startdatetime=2015-01-01T00:00:00Z&enddatetime=2015-04-10T00:00:00Z HTTP/1.1
Authorization: Bearer <token>
Prefer: odata.track-changes
Prefer: odata.maxpagesize=1
Prefer: outlook.timezone="Pacific Standard Time"
Sample initial response data
Preference-Applied: odata.track-changes
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarView",
"value": [
{
"@odata.id": "https://outlook.office.com/api/beta/Users('user0@contoso.com')/Events('asdas==')",
"@odata.etag": "W/\"L8Z+4Y4u7k+97uRKg==\"",
"Id": "AQMkANJAAAAA==",
"ChangeKey": "L8Z+AAAAARKg==",
"Categories": [
],
"DateTimeCreated": "2015-04-10T17:54:49.2725912Z",
"DateTimeLastModified": "2015-04-10T17:54:49.3038538Z",
"Subject": "Discuss the Calendar REST API",
"BodyPreview": "I think it will meet our requirements!",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
},
"Importance": "Normal",
"HasAttachments": false,
"Start": {
"DateTime": "2015-04-05T18:00:00",
"TimeZone": "Pacific Standard Time"
}
"End": {
"DateTime": "2015-04-05T19:00:00",
"TimeZone": "Pacific Standard Time"
}
"ReminderMinutesBeforeStart": "15",
"IsReminderOn": "true",
"Location":{
"DisplayName":"",
"LocationType":"Default",
"Address":{
"Type":"Unknown"
},
"Coordinates":{
}
},
"Locations":[
],
"ResponseStatus": {
"Response": "Organizer",
"Time": "0001-01-01T00:00:00Z"
},
"ShowAs": "Busy",
"IsAllDay": false,
"IsCancelled": false,
"IsOrganizer": true,
"ResponseRequested": true,
"Type": "SingleInstance",
"SeriesMasterId": null,
"Attendees": [
],
"Recurrence": null,
"OriginalEndTimeZone": "Pacific Standard Time",
"OriginalStartTimeZone": "Pacific Standard Time",
"Organizer": {
"EmailAddress": {
"Address": "user0@contoso.com",
"Name": "user0"
}
},
"iCalUId": "040000008200E9888E07599CCFA23",
"WebLink": "https://outlook.office.com/owa/?ItemID=AAAINJAAAAA%3D%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
"OnlineMeetingUrl": null
}
],
"@odata.deltaLink": "https://outlook.office.com/api/beta/me/calendarview/?startdatetime=2015-01-01T00%3a00%3a00Z&enddatetime=2015-04-10T00%3a00%3a00Z&%24deltatoken=v2%2cH4roCAAA%3d%2c1.0%2cFalse%2cA00%2c"
}
Sample second request
GET https://outlook.office.com/api/beta/me/calendarview?startdatetime=2015-01-01T00:00:00Z&enddatetime=2015-04-10T00:00:00Z&$deltatoken=v2%2cH4roCAAA%3d%2c1.0%2cFalse%2cA00%2c
Authorization: Bearer <token>
Prefer: odata.track-changes
Prefer: odata.maxpagesize=1
Prefer: outlook.timezone="Pacific Standard Time"
Sample second response data
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarView/$delta",
"value": [
{
"@odata.id": "https://outlook.office.com/api/beta/Users('user0@contoso.com')/Events('AAMkAD0jAAA=')",
"@odata.etag": "W/\"P2fd7QAAAAAVFA==\"",
"Id": "AAMkADNkNmVlOTITVAAAAAA0jAAA=",
"ChangeKey": "P2fdmIU1QAAAAAVFA==",
"Categories": [
],
"DateTimeCreated": "2015-04-15T18:59:11.0226221Z",
"DateTimeLastModified": "2015-04-15T18:59:11.0694979Z",
"Subject": "1 hour",
"BodyPreview": "\u200b",
"Body": {
"ContentType": "HTML",
"Content": "<html><body>content</body></html>"
},
"Importance": "Normal",
"HasAttachments": false,
"Start": {
"DateTime": "2015-04-16T18:00:00",
"TimeZone": "Pacific Standard Time"
}
"End": {
"DateTime": "2015-04-16T19:00:00",
"TimeZone": Pacific Standard Time"
}
"ReminderMinutesBeforeStart": "15",
"IsReminderOn": "true",
"Location":{
"DisplayName":"",
"LocationType":"Default",
"Address":{
"Type":"Unknown"
},
"Coordinates":{
}
},
"Locations":[
],
"ResponseStatus": {
"Response": "Organizer",
"Time": "0001-01-01T00:00:00Z"
},
"ShowAs": "Busy",
"IsAllDay": false,
"IsCancelled": false,
"IsOrganizer": true,
"ResponseRequested": true,
"Type": "SingleInstance",
"SeriesMasterId": null,
"Attendees": [
],
"Recurrence": null,
"OriginalEndTimeZone": "Pacific Standard Time",
"OriginalStartTimeZone": "Pacific Standard Time",
"Organizer": {
"EmailAddress": {
"Address": "user0@contoso.com",
"Name": "user0"
}
},
"iCalUId": "040000008200E09BB89A316862",
"WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADNkNmVlOAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
"OnlineMeetingUrl": null
}
],
"@odata.nextLink": "https://outlook.office.com/api/beta/me/calendarview/?startdatetime=2015-01-01T00%3a00%3a00Z&enddatetime=2015-08-10T00%3a00%3a00Z&%24skipToken=530c9d02ae1a4d96804538bd4d381546"
}
Find meeting times
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.read
- wl.calendars
- wl.contacts_calendars
Find meeting time suggestions based on organizer and attendee availability, and time or location constraints specified as parameters.
This operation applies to only Office 365 mailboxes (on Azure AD) and not to Microsoft accounts.
POST https://outlook.office.com/api/{version}/me/findmeetingtimes
All the supported parameters are listed below. Depending on your scenario, specify the necessary parameters in the request body of the FindMeetingTimes action.
| Parameter | Type | Description | Required? |
|---|---|---|---|
| Attendees | Collection(AttendeeBase) | Attendees or resources for the meeting. An empty collection causes FindMeetingTimes to look for free time slots for only the organizer. | Optional |
| IsOrganizerOptional | Edm.Boolean | Specify true if the organizer doesn't necessarily have to attend. The default is false. |
Optional |
| LocationConstraint | LocationConstraint | The organizer's requirements about the meeting location, such as whether a suggestion for a meeting location is required, or there are specific locations only where the meeting can take place. | Optional |
| MaxCandidates | Edm.Int32 | The maximum number of meeting suggestions to return in the response. | Optional |
| MeetingDuration | Edm.Duration | The length of the meeting expressed in ISO 8601 format for durations, for example, PT1H represents 1 hour. If no meeting duration is specified, FindMeetingTimes uses the default of 30 minutes. |
Optional |
| MinimumAttendeePercentage | Edm.Double | The minimum required confidence for a time slot to be returned in the response. It is a % value ranging from 0 to 100. | Optional |
| ReturnSuggestionReasons | Edm.Boolean | Specify true to return a reason for each meeting suggestion in the SuggestionReason property. The default is false to not return that property. |
Optional |
| TimeConstraint | TimeConstraint | Any time restrictions for a meeting, which can include the nature of the meeting (ActivityDomain) and possible meeting time periods (TimeSlots). FindMeetingTimes assumes ActivityDomain as Work if you don't specify this parameter. |
Optional |
FindMeetingTimes checks the free/busy status in the primary calendars of the organizer and attendees. Based on the specified parameters, the action suggests the best possible meeting times. The following table describes the restrictions you can specify in the TimeConstraint parameter.
| ActivityDomain value in TimeConstraint | Suggestions for meeting times |
|---|---|
| Work | Suggestions are within the user's work hours which are defined in the user’s calendar configuration and can be customized by the user or administrator. The default work hours are Monday to Friday, 8am to 5pm in the time zone set for the mailbox. This is the default value if no ActivityDomain is specified. |
| Personal | Suggestions are within the user's work hours, and Saturday and Sunday. The default is Monday to Sunday, 8am to 5pm, in the time zone setting for the mailbox. |
| Unrestricted | Suggestions can be from all hours of a day, all days of a week. |
| Unknown | Do not use this value as it will be deprecated in the future. Currently behaves the same as Work. Change any existing code to use Work, Personal or Unrestricted as appropriate. |
Response type
A MeetingTimeSuggestionsResult which includes a collection of meeting suggestions, each of type MeetingTimeSuggestion, and an EmptySuggestionsReason property.
Each suggestion is defined as a MeetingTimeSuggestion, with attendees having by default a confidence level of 50% to attend, or a specific % that you have specified in the MinimumAttendeePercentage parameter.
By default, each meeting time suggestion is returned in UTC. Apply the Prefer: outlook.timezone request header to have meeting time suggestions retuned in a different time zone, for example:
Prefer: outlook.timezone="Pacific Standard Time"
If FindMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the EmptySuggestionsReason property. Based on this value, you can better adjust the parameters and call FindMeetingTimes again.
Note
Currently, FindMeetingTimes assumes the following that any Attendee who is a person (as opposed to a resource) is a required attendee. So, specify Required for a person and Resource for a resource in the corresponding Type property, as part of the Attendees collection parameter.
Each example below calls FindMeetingTimes, and varies by attendee availability, time, and location constraints:
- Find time and location to meet with attendees
- Find time to meet at a known location, and get a reason for each suggestion
- Find time to meet but no attendee is available
- Find time to meet but only some attendees available
- Find free time slots for just the signed-in user
Find time and location to meet with specific attendees
Find times and locations to meet by specifying the following parameters in the request body:
- Attendees
- TimeConstraint
- MeetingDuration
Sample request
The following example suggests meeting times and locations taking into consideration the organizer's and attendee's availability during work hours of the requested meeting time range, and the requested length of time.
POST https://outlook.office.com/api/beta/me/findmeetingtimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json
{
"Attendees": [
{
"Type": "Required",
"EmailAddress": {
"Name": "Fanny",
"Address": "fannyd@prosewareltd.onmicrosoft.com"
}
}
],
"TimeConstraint": {
"ActivityDomain":"Work",
"Timeslots": [
{
"Start": {
"DateTime": "2016-05-20T07:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T17:00:00",
"TimeZone": "Pacific Standard Time"
}
}
]
},
"MeetingDuration": "PT1H"
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
"MeetingTimeSuggestions": [
{
"MeetingTimeSlot": {
"Start": {
"DateTime": "2016-05-20T10:00:00.0000000",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T11:00:00.0000000",
"TimeZone": "Pacific Standard Time"
}
},
"Confidence": 100.0,
"OrganizerAvailability": "Free",
"AttendeeAvailability": [
{
"Attendee": {
"Type": "Required",
"EmailAddress": {
"Name": "Fanny",
"Address": "fannyd@prosewareltd.onmicrosoft.com"
}
},
"Availability": "Free"
}
],
"Locations": [
{
"DisplayName": "Tokyo conference room",
"LocationType": "Default"
}
]
},
{
"MeetingTimeSlot": {
"Start": {
"DateTime": "2016-05-20T11:00:00.0000000",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T12:00:00.0000000",
"TimeZone": "Pacific Standard Time"
}
},
"Confidence": 100.0,
"OrganizerAvailability": "Free",
"AttendeeAvailability": [
{
"Attendee": {
"Type": "Required",
"EmailAddress": {
"Name": "Fanny",
"Address": "fannyd@prosewareltd.onmicrosoft.com"
}
},
"Availability": "Free"
}
],
"Locations": [
{
"DisplayName": "Paris conference room",
"LocationType": "Default"
}
]
}
],
"EmptySuggestionsReason": ""
}
Find time to meet at a known location, and get a reason for each suggestion
Find time to meet at a pre-determined location, and request a reason for each suggestion, by specifying the following parameters in the request body:
- Attendees
- LocationConstraint
- TimeConstraint
- MeetingDuration
- ReturnSuggestionReasons
By setting the ReturnSuggestionReasons parameter, you also get an explanation for each suggestion in the SuggestionReason property, if FindMeetingTimes returns any suggestion.
Sample request
POST https://outlook.office.com/api/beta/me/findmeetingtimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json
{
"Attendees": [
{
"Type": "Required",
"EmailAddress": {
"Name": "Fanny",
"Address": "fannyd@prosewareltd.onmicrosoft.com"
}
}
],
"LocationConstraint": {
"IsRequired": "false",
"SuggestLocation": "false",
"Locations": [
{
"ResolveAvailability": "false",
"DisplayName": "Conf room Hood"
}
]
},
"TimeConstraint": {
"ActivityDomain":"Work",
"Timeslots": [
{
"Start": {
"DateTime": "2016-05-20T07:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T17:00:00",
"TimeZone": "Pacific Standard Time"
}
}
]
},
"MeetingDuration": "PT2H",
"ReturnSuggestionReasons": "true"
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
"MeetingTimeSuggestions": [
{
"MeetingTimeSlot": {
"Start": {
"DateTime": "2016-05-20T10:00:00.0000000",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T12:00:00.0000000",
"TimeZone": "Pacific Standard Time"
}
},
"Confidence": 100.0,
"OrganizerAvailability": "Free",
"AttendeeAvailability": [
{
"Attendee": {
"Type": "Required",
"EmailAddress": {
"Name": "Fanny",
"Address": "fannyd@prosewareltd.onmicrosoft.com"
}
},
"Availability": "Free"
}
],
"Locations": [
{
"DisplayName": "Conf room Hood"
"LocationType": "Default"
}
],
"SuggestionReason": "Suggested because it is one of the nearest times when all attendees are available."
}
],
"EmptySuggestionsReason": ""
}
Find time to meet but no attendee is available
Find time to meet at a pre-determined location, by specifying the following parameters in the request body:
- Attendees
- LocationConstraint
- TimeConstraint
- MeetingDuration
In this example, based on specified parameters and attendee availability, FindMeetingTimes cannot return any suggestions, and instead returns a reason AttendeesUnavailable in the EmptySuggestionsReason property.
See other possible reasons for not returning any meeting suggestions.
Sample request
POST https://outlook.office.com/api/beta/me/findmeetingtimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json
{
"Attendees": [
{
"Type": "Required",
"EmailAddress": {
"Name": "Fanny",
"Address": "fannyd@prosewareltd.onmicrosoft.com"
}
}
],
"LocationConstraint": {
"IsRequired": "false",
"SuggestLocation": "false",
"Locations": [
{
"ResolveAvailability": "false",
"DisplayName": "Conf room Hood"
}
]
},
"TimeConstraint": {
"Timeslots": [
{
"Start": {
"DateTime": "2016-05-20T7:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T14:00:00",
"TimeZone": "Pacific Standard Time"
}
}
]
},
"MeetingDuration": "PT2H"
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
"MeetingTimeSuggestions": [
],
"EmptySuggestionsReason": "AttendeesUnavailable"
}
Find time to meet but only some attendees are available
Find time to meet at a pre-determined location, by specifying the following parameters in the request body:
- Attendees
- LocationConstraint
- TimeConstraint
- MeetingDuration
- ReturnSuggestionReasons
- MinimumAttendeePercentage
In this example, only one of the 2 attendees is available. Each meeting suggestion that FindMeetingTimes returns includes:
- The availability of each attendee.
- A computed meeting Confidence which is the average % chance of the attendees attending. This value must meet the 60% requirement specified in MinimumAttendeePercentage.
- A SuggestionHint, since the ReturnSuggestionReasons parameter is set.
Find more information about the confidence of a meeting.
Sample request
POST https://outlook.office.com/api/beta/me/findmeetingtimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json
{
"Attendees": [
{
"Type": "Required",
"EmailAddress": {
"Name": "Fanny",
"Address": "fannyd@prosewareltd.onmicrosoft.com"
}
},
{
"Type": "Optional",
"EmailAddress": {
"Name": "Dana",
"Address": "danas@prosewareltd.onmicrosoft.com"
}
}
],
"LocationConstraint": {
"IsRequired": "false",
"SuggestLocation": "false",
"Locations": [
{
"ResolveAvailability": "false",
"DisplayName": "Conf room Hood"
}
]
},
"TimeConstraint": {
"ActivityDomain":"Work",
"Timeslots": [
{
"Start": {
"DateTime": "2016-05-20T09:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T17:00:00",
"TimeZone": "Pacific Standard Time"
}
}
]
},
"MeetingDuration": "PT1H",
"ReturnSuggestionReasons": "true",
"MinimumAttendeePercentage": "60"
}
Sample response
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
"MeetingTimeSuggestions":[
{
"MeetingTimeSlot":{
"Start":{
"DateTime":"2016-05-20T10:00:00.0000000",
"TimeZone":"Pacific Standard Time"
},
"End":{
"DateTime":"2016-05-20T11:00:00.0000000",
"TimeZone":"Pacific Standard Time"
}
},
"Confidence":100.0,
"OrganizerAvailability":"Free",
"AttendeeAvailability":[
{
"Attendee":{
"Type":"Required",
"EmailAddress":{
"Name": "Fanny",
"Address":"fannyd@prosewareltd.onmicrosoft.com"
}
},
"Availability":"Free"
},
{
"Attendee":{
"Type":"Required",
"EmailAddress":{
"Name": "Dana",
"Address":"danas@prosewareltd.onmicrosoft.com"
}
},
"Availability":"Free"
}
],
"Locations":[
{
"DisplayName":"Conf room Hood"
"LocationType": "Default"
}
],
"SuggestionReason":"Suggested because it is one of the nearest times when most attendees are available."
},
{
"MeetingTimeSlot":{
"Start":{
"DateTime":"2016-05-20T11:00:00.0000000",
"TimeZone":"Pacific Standard Time"
},
"End":{
"DateTime":"2016-05-20T12:00:00.0000000",
"TimeZone":"Pacific Standard Time"
}
},
"Confidence":74.5,
"OrganizerAvailability":"Free",
"AttendeeAvailability":[
{
"Attendee":{
"Type":"Required",
"EmailAddress":{
"Name": "Fanny",
"Address":"fannyd@prosewareltd.onmicrosoft.com"
}
},
"Availability":"Free"
},
{
"Attendee":{
"Type":"Required",
"EmailAddress":{
"Name": "Dana",
"Address":"danas@prosewareltd.onmicrosoft.com"
}
},
"Availability":"Unknown"
}
],
"Locations":[
{
"DisplayName":"Conf room Hood"
"LocationType": "Default"
}
],
"SuggestionReason":"Suggested because it is one of the nearest times when most attendees are available."
}
],
"EmptySuggestionsReason":""
}
Find free time slots for just the signed-in user
Find free time slots in the signed-in user's primary calendar any time of the week within a date range, by specifying the following parameters in the request body:
- TimeConstraint
- MeetingDuration
Sample request
This example looks for 1-hour free time slots, as specified by MeetingDuration, in the signed-in user's primary calendar any time of the week within a date range specified by TimeConstraint.
POST https://outlook.office.com/api/beta/me/findmeetingtimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json
{
"Attendees": [],
"TimeConstraint": {
"ActivityDomain":"Unrestricted",
"Timeslots": [
{
"Start": {
"DateTime": "2016-05-20T06:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-22T23:00:00",
"TimeZone": "Pacific Standard Time"
}
}
]
},
"MeetingDuration": "PT1H"
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Microsoft.OutlookServices.MeetingTimeSuggestionsResult",
"MeetingTimeSuggestions": [
{
"MeetingTimeSlot": {
"Start": {
"DateTime": "2016-05-20T06:00:00.0000000",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-20T07:00:00.0000000",
"TimeZone": "Pacific Standard Time"
}
},
"Confidence": 100.0,
"OrganizerAvailability": "Free",
"AttendeeAvailability": [
],
"Locations": [
]
},
{
"MeetingTimeSlot": {
"Start": {
"DateTime": "2016-05-21T09:00:00.0000000",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-21T10:00:00.0000000",
"TimeZone": "Pacific Standard Time"
}
},
"Confidence": 100.0,
"OrganizerAvailability": "Free",
"AttendeeAvailability": [
],
"Locations": [
]
},
{
"MeetingTimeSlot": {
"Start": {
"DateTime": "2016-05-22T19:00:00.0000000",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2016-05-22T20:00:00.0000000",
"TimeZone": "Pacific Standard Time"
}
},
"Confidence": 100.0,
"OrganizerAvailability": "Free",
"AttendeeAvailability": [
],
"Locations": [
]
}
],
"EmptySuggestionsReason": ""
}
Get meeting rooms (preview)
In Outlook, a tenant can organize meeting rooms into room lists. Each meeting room and room list is represented by an EmailAddress instance.
- Get room lists (preview)
- Get rooms (preview)
Get room lists (preview)
Minimum required scope
One of the following:
- User.Read.All
- User.ReadBasic.All_
Get the room lists defined in a tenant.
GET https://outlook.office.com/api/beta/me/findroomlists
Response type
Collection of EmailAddress instances. If no lists are defined in the tenant, an empty array is returned.
Sample request
GET https://outlook.office.com/api/beta/me/findroomlists
Sample response
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.EmailAddress)",
"value":[
{
"Name":"Building 1 Rooms",
"Address":"Building1Rooms@contoso.onmicrosoft.com"
},
{
"Name":"Building 2 Rooms",
"Address":"Building2Rooms@contoso.onmicrosoft.com"
}
]
}
Get rooms (preview)
Minimum required scope
One of the following:
- User.Read.All
- User.ReadBasic.All
You can get all the meeting rooms defined in the user's tenant, or get the meeting rooms in a specific room list.
Note
These operations return up to the first 100 rooms in a tenant.
To get all the rooms in the user's tenant:
GET https://outlook.office.com/api/beta/me/findrooms
To get the rooms in a specified room list:
GET https://outlook.office.com/api/beta/me/findrooms(roomlist='{room_list}')
| Optional parameter | Type | Description |
|---|---|---|
| Function parameter | ||
| room_list | string | The SMTP address associated with the room list. Each room list is represented by an EmailAddress instance that includes an SMTP address. |
Response type
Collection of EmailAddress instances.
Sample request
The following example gets the rooms defined in the signed-in user's tenant.
GET https://outlook.office.com/api/beta/me/findrooms
Sample response
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.EmailAddress)",
"value":[
{
"Name":"Conf Room Adams",
"Address":"Adams@contoso.onmicrosoft.com"
},
{
"Name":"Conf Room Baker",
"Address":"Baker@contoso.onmicrosoft.com"
},
{
"Name":"Conf Room Crystal",
"Address":"Crystal@contoso.onmicrosoft.com"
},
{
"Name":"Conf Room Hood",
"Address":"Hood@contoso.onmicrosoft.com"
},
{
"Name":"Conf Room Rainier",
"Address":"Rainier@contoso.onmicrosoft.com"
},
{
"Name":"Conf Room Stevens",
"Address":"Stevens@contoso.onmicrosoft.com"
},
{
"Name":"SurfaceHub",
"Address":"SurfaceHub@contoso.onmicrosoft.com"
}
]
}
Sample request
The following example gets the rooms in the specified room list identified by the email address Building2Rooms@contoso.onmicrosoft.com.
GET https://outlook.office.com/api/beta/me/findrooms(roomlist='Building2Rooms@contoso.onmicrosoft.com')
Sample response
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Collection(Microsoft.OutlookServices.EmailAddress)",
"value":[
{
"Name":"Conf Room Baker",
"Address":"Baker@contoso.onmicrosoft.com"
},
{
"Name":"Conf Room Hood",
"Address":"Hood@contoso.onmicrosoft.com"
},
{
"Name":"Conf Room Rainier",
"Address":"Rainier@contoso.onmicrosoft.com"
}
]
}
Create events
Create a calendar event
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
Create an event in the user's primary calendar or a specific calendar by posting to the calendar's events endpoint.
When the event is created, the server sends invitations to all attendees.
POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/calendars/{calendar_id}/events
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calendar_id | string | The calendar ID. |
Sample request
The following example creates an event for the organizer and attendees to participate from 3 different locations.
POST https://outlook.office.com/api/beta/me/events
Content-Type: application/json
{
"Subject": "Plan summer company picnic",
"Body": {
"ContentType": "HTML",
"Content": "Let's kick-start this event planning!"
},
"Start": {
"DateTime": "2017-06-09T11:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2017-06-09T12:00:00",
"TimeZone": "Pacific Standard Time"
},
"Attendees": [
{
"EmailAddress": {
"Address": "AdeleV@contoso.onmicrosoft.com",
"Name": "Adele Vance"
},
"Type": "Required"
},
{
"EmailAddress": {
"Address": "AlexW@contoso.onmicrosoft.com",
"Name": "Alex Wilber"
},
"Type": "Required"
}
],
"Location": {
"DisplayName": "Conf Room 3; Fourth Coffee; Home Office",
"LocationType": "Default"
},
"Locations": [
{
"DisplayName": "Conf Room 3",
},
{
"DisplayName": "Fourth Coffee",
"Address": {
"Street": "4567 Main St",
"City": "Redmond",
"State": "WA",
"CountryOrRegion": "US",
"PostalCode": "32008"
},
"Coordinates": {
"Latitude": 47.672,
"Longitude": -102.103
},
"LocationType": "LocalBusiness"
},
{
"DisplayName": "Home Office",
}
]
}
Sample response
Status code: 201
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
"@odata.id":"https://outlook.office.com/api/beta/Users('94447c6e-ea4c-494c-a9ed-d905e366c5cb@007e925e-fb5a-4f60-9cb6-58a21e692480')/Events('AAMkADNCYBXsvAAA=')",
"@odata.etag":"W/\"SuFHwDRP1EeXJUopWbSLlgAAmBvk2g==\"",
"Id":"AAMkADNCYBXsvAAA=",
"CreatedDateTime":"2017-06-06T19:59:23.003773-07:00",
"LastModifiedDateTime":"2017-06-06T19:59:24.8432785-07:00",
"ChangeKey":"SuFHwDRP1EeXJUopWbSLlgAAmBvk2g==",
"Categories":[
],
"OriginalStartTimeZone":"Pacific Standard Time",
"OriginalEndTimeZone":"Pacific Standard Time",
"iCalUId":"040000008200E00074C5B7101A82E008000000000FD9CB103ADFD20100000000000000001000000026DB266A0E3C4A4FB15DC14FFFB1469D",
"ReminderMinutesBeforeStart":15,
"IsReminderOn":true,
"HasAttachments":false,
"Subject":"Plan summer company picnic",
"BodyPreview":"Let's kick-start this event planning!",
"Importance":"Normal",
"Sensitivity":"Normal",
"IsAllDay":false,
"IsCancelled":false,
"IsOrganizer":true,
"ResponseRequested":true,
"SeriesMasterId":null,
"ShowAs":"Busy",
"Type":"SingleInstance",
"WebLink":"https://outlook.office365.com/owa/?itemid=AAMkADNCYBXsvAAA%3D&exvsurl=1&path=/calendar/item",
"OnlineMeetingUrl":null,
"ResponseStatus":{
"Response":"Organizer",
"Time":"0001-01-01T00:00:00Z"
},
"Body":{
"ContentType":"HTML",
"Content":"<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's kick-start this event planning!\r\n</body>\r\n</html>\r\n"
},
"Start":{
"DateTime":"2017-06-09T11:00:00.0000000",
"TimeZone":"Pacific Standard Time"
},
"End":{
"DateTime":"2017-06-09T12:00:00.0000000",
"TimeZone":"Pacific Standard Time"
},
"Location":{
"DisplayName":"Conf Room 3; Fourth Coffee; Home Office",
"LocationType":"Default"
},
"Locations":[
{
"DisplayName":"Conf Room 3",
"LocationType":"Default"
},
{
"DisplayName":"Fourth Coffee",
"LocationType":"Default",
"Address":{
"Type":"Unknown",
"Street":"4567 Main St",
"City":"Redmond",
"State":"WA",
"CountryOrRegion":"US",
"PostalCode":"32008"
},
"Coordinates":{
"Latitude":47.672,
"Longitude":-102.103
}
},
{
"DisplayName":"Home Office",
"LocationType":"Default"
}
],
"Recurrence":null,
"Attendees":[
{
"Type":"Required",
"Status":{
"Response":"None",
"Time":"0001-01-01T00:00:00Z"
},
"EmailAddress":{
"Name":"Adele Vance",
"Address":"AdeleV@contoso.onmicrosoft.com"
}
},
{
"Type":"Required",
"Status":{
"Response":"None",
"Time":"0001-01-01T00:00:00Z"
},
"EmailAddress":{
"Name":"Alex Wilber",
"Address":"AlexW@contoso.onmicrosoft.com"
}
}
],
"Organizer":{
"EmailAddress":{
"Name":"Fanny Downs",
"Address":"fannyd@contoso.onmicrosoft.com"
}
},
"OnlineMeeting":null
}
Response type
The new event.
By default, the response includes all the properties of the new event. Use $select to specify only those properties you need for best performance. The Id property is always returned.
The following is an example to include only the Start and End properties of the new event in the response.
POST https://outlook.office.com/api/beta/me/events?$Select=Start,End
Update events
Update a calendar event
Minimum required scope
One of the following:
- 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/beta/me/events/{event_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. |
Specify any writable event properties in the request body.
PATCH https://outlook.office.com/api/beta/me/events/AAMkAGE1MFKPQWAAA=?$select=Location
Sample request
PATCH https://outlook.office.com/api/beta/me/events/AAMkAGE0M4v1OAAA=
Content-Type: application/json
{
"Location": {
"DisplayName": "Conference Rome",
"LocationType": "ConferenceRoom"
}
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE0M4v1OAAA=')",
"@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==\"",
"Id": "AAMkAGE0M4v1OAAA=",
"ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeNheQ==",
"Categories": [],
"CreatedDateTime": "2014-01-22T20:49:05.5657528Z",
"LastModifiedDateTime": "2014-01-22T21:14:17.4886416Z",
"Subject": "Discuss the Calendar REST API",
"BodyPreview": "I think it will meet our requirements!",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nI think it will meet our requirements!\r\n</body>\r\n</html>\r\n"
},
"Importance": "Normal",
"HasAttachments": false,
"Start": {
"DateTime": "2014-02-02T18:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2014-02-02T19:00:00",
"TimeZone": "Pacific Standard Time"
},
"Location": {
"DisplayName": "Conference Rome",
"LocationType": "ConferenceRoom"
},
"Locations":[
{
"DisplayName":"Conference Rome",
"LocationType":"ConferenceRoom"
}
],
"ShowAs": "Busy",
"IsAllDay": false,
"IsCancelled": false,
"IsOrganizer": true,
"ResponseRequested": true,
"Type": "SingleInstance",
"SeriesMasterId": null,
"Attendees": [],
"Recurrence": null,
"OriginalEndTimeZone": "Pacific Standard Time",
"OriginalStartTimeZone": "Pacific Standard Time",
"Organizer": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "alexd"
}
},
"OnlineMeetingUrl": null
}
Response type
The updated event. If the user is the organizer, the server sends meeting updates to all attendees.
By default, the response includes all the properties of the updated event. Use $select to specify only those properties you need for best performance. The Id property is always returned.
Respond to events
Accept event
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
Accept the specified event.
POST https://outlook.office.com/api/beta/me/events/{event_id}/accept
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. Required. |
| Body parameters | ||
| Comment | string | Text included in the response. Optional. |
| SendResponse | boolean | true if a response is to be sent to the organizer; otherwise, false. Optional. Default is true. |
Sample request
POST https://outlook.office.com/api/beta/me/events('AAMkAGE1M2IyNGNmLTI5MT_bs88AAAXDJwEAAA=')/accept
Content-Type: application/json
{
"Comment": "Great idea!",
"SendResponse": "true"
}
Response
A successful response is indicated by an HTTP 202 Accepted response code.
Tentatively accept event
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
Tentatively accept the specified event.
POST https://outlook.office.com/api/beta/me/events/{event_id}/tentativelyaccept
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. Required. |
| Body parameters | ||
| Comment | string | Text included in the response. Optional. |
| SendResponse | boolean | true if a response is to be sent to the organizer; otherwise, false. Optional. Default is true. |
Sample request
POST https://outlook.office.com/api/beta/me/events('AAMkAGE1M2IyNGNmLTI5MT_bs88AAAXDJwEAAA=')/tentativelyaccept
Content-Type: application/json
{
"Comment": "I'll confirm later!",
"SendResponse": "true"
}
Response
A successful response is indicated by an HTTP 202 Accepted response code.
Decline event
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
Decline invitation to the specified event.
POST https://outlook.office.com/api/beta/me/events/{event_id}/decline
| Parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. Required. |
| Body parameters | ||
| Comment | string | Text included in the response. Optional. |
| SendResponse | boolean | true if a response is to be sent to the organizer; otherwise, false. Optional. Default is true. |
Sample request
POST https://outlook.office.com/api/beta/me/events('AAMkAGE1M2IyNGNmLTI5MT_bs88AAAXDJwEAAA=')/decline
Content-Type: application/json
{
"Comment": "Sorry, maybe next time!",
"SendResponse": "true"
}
Response
A successful response is indicated by an HTTP 202 Accepted response code.
Forward events (preview)
Minimum required scope
One of the following:
- 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":"danas@contoso.onmicrosoft.com",
"Name":"Dana Swope"
}
}
],
"Comment": "Dana, hope you can make this meeting."
}
Sample response
Status code: 202 Accepted
Delete events
Delete a calendar event
Minimum required scope
One of the following:
- 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.
This action differs from Cancel in that Delete is available to the organizer and attendees of the meeting. If the signed-user is the meeting organizer, the user simply cancels the meeting without providing a custom cancellation message to the attendees.
DELETE https://outlook.office.com/api/beta/me/events/{event_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. |
Sample request
DELETE https://outlook.office.com/api/beta/me/events/AAMkAGE0M4v1OAAA=
Sample response
Status code: 204
Cancel events (preview)
Minimum required scope
One of the following:
- 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
Get attachments
You can get an attachment collection or 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/beta/me/events/{event_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. |
Response type
An attachment collection which can be of the type FileAttachment, ItemAttachment, or ReferenceAttachment.
Sample request
GET https://outlook.office.com/api/beta/me/events/AAMkAGI2NGTG9yAAA=/attachments
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGI2NG9yAAA%3D')/Attachments",
"value": [
{
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2NGTG9yAAA=')/Attachments('AAMkAGI2NGLwydGuOzcHf1FBlo=')",
"Id": "AAMkAGI2NGLwydGuOzcHf1FBlo=",
"LastModifiedDateTime": "2014-10-22T00:30:26Z",
"Name": "Company Party.docx",
"ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"Size": 11647,
"IsInline": false,
"ContentId": null,
"ContentLocation": null,
"ContentBytes": "UEsDBBQABgAIAAAAIQDfpNJs...AAF4pAAAAAA=="
}
]
}
Get an attachment
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.read
- wl.calendars
- wl.contacts_calendars
Get an attachment from a particular event.
GET https://outlook.office.com/api/beta/me/events/{event_id}/attachments/{attachment_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. |
| attachment_id | string | The attachment ID. |
Note
See OData query parameters for filtering, sorting, and paging parameters.
Response type
The requested file attachment, item attachment, or reference attachment.
Sample request
The following example gets the file attached to a specific event.
GET https://outlook.office.com/api/beta/me/events/AAMkAGI2WRAAADTG9yAAA=/attachments/AAMkAGI2TG9yAAABEgAQALxJtn1LwydGuOzcHf1FBlo=
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGI2WRAAADTG9yAAA%3D')/Attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI2WRAAADTG9yAAA=')/Attachments('AAMkAGI2TG9yAAABEgAQALxJtn1LwydGuOzcHf1FBlo=')",
"Id": "AAMkAGI2TG9yAAABEgAQALxJtn1LwydGuOzcHf1FBlo=",
"LastModifiedDateTime": "2014-10-22T00:30:26Z",
"Name": "Company Party.docx",
"ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"Size": 11647,
"IsInline": false,
"ContentId": null,
"ContentLocation": null,
"ContentBytes": "UEsDBBQABgAIAAAAIQD...AAF4pAAAAAA=="
}
Sample request (reference attachment)
The following example gets the reference attachment of an event.
GET https://outlook.office.com/api/beta/me/events('AAMkAGE1Mbs88AADggYEcAAA=')/attachments('AAMkAGE1Mbs88AADggYEcAAABEgAQAABWAoLgP3REt_LWRG8ORv4=')
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events('AAMkAGE1Mbs88AADggYEcAAA%3D')/attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"id": "AAMkAGE1Mbs88AADggYEcAAABEgAQAABWAoLgP3REt_LWRG8ORv4=",
"lastModifiedDateTime": "2016-03-22T22:27:20Z",
"name": "Hydrangea picture",
"contentType": null,
"size": 412,
"isInline": false,
"sourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
"providerType": "oneDriveBusiness",
"thumbnailUrl": null,
"previewUrl": null,
"permission": "edit",
"isFolder": false
}
Sample request ($expand on attachments)
The following example gets and expands the 2 reference attachments inline with the event properties.
GET https://outlook.office.com/api/beta/me/events('AAMkAGE1Mbs88AADggYEcAAA=')?$expand=attachments
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events/$entity",
"@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAA4KZrtA==\"",
"id": "AAMkAGE1Mbs88AADggYEcAAA=",
"createdDateTime": "2016-03-22T22:19:58.1359352Z",
"lastModifiedDateTime": "2016-03-22T22:39:09.9335289Z",
"changeKey": "mODEKWhc/Um6lA3uPm7PPAAA4KZrtA==",
"categories": [
],
"originalStartTimeZone": "Pacific Standard Time",
"originalEndTimeZone": "Pacific Standard Time",
"responseStatus": {
"response": "organizer",
"time": "0001-01-01T00:00:00Z"
},
"iCalUId": "040000008200E00074C5B7101A82E008000000005895FCF78884D10100000000000000001000000099DD7CA6BCF37C4F9F7DAACCADDD6B89",
"reminderMinutesBeforeStart": 15,
"isReminderOn": true,
"hasAttachments": true,
"subject": "Plan Easter egg hunt!",
"body": {
"contentType": "html",
"content": "<html>\r\n<body>\r\nLet's get organized for this weekend's gathering.\r\n</body>\r\n</html>\r\n"
},
"bodyPreview": "Let's get organized for this weekend's gathering.",
"importance": "normal",
"sensitivity": "normal",
"start": {
"dateTime": "2016-03-26T17:00:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2016-03-26T18:00:00.0000000",
"timeZone": "UTC"
},
"location": {
"displayName": "",
"locationType": "default",
"address": {
"type": "unknown"
},
"coordinates": {
}
},
"locations": [
],
"isAllDay": false,
"isCancelled": false,
"isOrganizer": true,
"recurrence": null,
"responseRequested": true,
"seriesMasterId": null,
"showAs": "busy",
"type": "singleInstance",
"attendees": [
{
"status": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"type": "required",
"emailAddress": {
"name": "Randi Welch",
"address": "randiw@contoso.onmicrosoft.com"
}
}
],
"organizer": {
"emailAddress": {
"name": "Dana Swope",
"address": "danas@contoso.onmicrosoft.com"
}
},
"webLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1Mbs88AADggYEcAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
"onlineMeetingUrl": null,
"attachments@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events('AAMkAGE1Mbs88AADggYEcAAA%3D')/attachments",
"attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"id": "AAMkAGE1Mbs88AADggYEcAAABEgAQAABWAoLgP3REt_LWRG8ORv4=",
"lastModifiedDateTime": "2016-03-22T22:27:20Z",
"name": "Hydrangea picture",
"contentType": null,
"size": 412,
"isInline": false,
"sourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
"providerType": "oneDriveBusiness",
"thumbnailUrl": null,
"previewUrl": null,
"permission": "edit",
"isFolder": false
},
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"id": "AAMkAGE1Mbs88AADggYEcAAABEgAQAE1rHHth7YNLlR9WsgnODy0=",
"lastModifiedDateTime": "2016-03-22T22:39:09Z",
"name": "Koala picture",
"contentType": null,
"size": 382,
"isInline": false,
"sourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/koala.jpg",
"providerType": "oneDriveBusiness",
"thumbnailUrl": null,
"previewUrl": null,
"permission": "edit",
"isFolder": false
}
]
}
Sample request ($expand on nested attachment items)
The following example gets a nested attachment item.
GET https://outlook-sdf.office.com/api/beta/me/events/AAMkAGE1Mbs88AADUv0uFAAA=/attachments/AAMkAGE1Mbs88AADUv0uFAAABEgAQAL53d0u3BKBJmCxKVxZKBZ8=$expand=Microsoft.OutlookServices.ItemAttachment/Item
Sample response
Status code: 200
{
"Id": "AAMkAGE1Mbs88AADUv0uFAAABEgAQAL53d0u3BKBJmCxKVxZKBZ8=",
"LastModifiedDateTime": "2017-04-25T20:05:55Z",
"Name": "RE: Changes to GetConditionMetadata handler",
"ContentType": null,
"Size": 78927,
"IsInline": false,
"Item": {
"Id": "",
"Name": "How to retrieve item attachment using Outlook REST API",
"ContentType": message/rfc822,
"Size": 71094,
"IsInline": false,
"LastModifiedDateTime": "2015-09-24T05:57:59Z",
}
}
Create attachments
You can create a file attachment or create an item attachment for an event.
Create a file attachment
Minimum required scope
One of the following:
- 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/beta/me/events/{event_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. |
| Body parameters | ||
| @odata.type | string | #Microsoft.OutlookServices.FileAttachment |
| Name | string | The name of the attachment. |
| ContentBytes | binary | The file to attach. |
Response type
The new file attachment.
Create an item attachment
Minimum required scope
One of the following:
- 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/beta/me/events/{event_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. |
| Body parameters | ||
| @odata.type | string | #Microsoft.OutlookServices.ItemAttachment |
| Name | string | The name of the attachment. |
| Item | A Message, Event, or Contact entity. | The item to attach. |
Response type
The new item attachment.
Create a reference attachment
Minimum required scope
https://outlook.office.com/calendars.readwrite
Add a reference attachment to an event.
POST https://outlook.office.com/api/beta/me/events/{event_id}/attachments
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | String | The event ID. |
| Body parameters | ||
| @odata.type | String | #Microsoft.OutlookServices.ReferenceAttachment |
| Name | String | The display name of the attachment. Required. |
| SourceUrl | String | URL to get the attachment content. If this is a URL to a folder, then for the folder to be displayed correctly in Outlook or Outlook on the web, set IsFolder to true. Required. |
Specify the Name and SourceUrl parameters and any writable reference attachment properties in the request body.
Response type
The reference attachment.
Sample request
The following example adds a reference attachment to an existing event. The attachment is a link to a file on OneDrive for Business.
POST https://outlook.office.com/api/beta/me/events('AAMkAGE1Mbs88AADggYEcAAA=')/attachments
Content-Type: application/json
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Name": "Hydrangea picture",
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
"ProviderType": "oneDriveBusiness",
"Permission": "Edit",
"IsFolder": "False"
}
Sample response
Status code: 201 Created
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#users('ddfcd489-628b-40d7-b48b-57002df800e5')/events('AAMkAGE1Mbs88AADggYEcAAA%3D')/attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Id": "AAMkAGE1Mbs88AADggYEcAAABEgAQAABWAoLgP3REt_LWRG8ORv4=",
"LastModifiedDateTime": "2016-03-22T22:27:20Z",
"Name": "Hydrangea picture",
"ContentType": null,
"Size": 412,
"IsInline": false,
"SourceUrl": "https://contoso-my.spoppe.com/personal/danas_contoso_onmicrosoft_com/Documents/Pics/hydrangea.jpg",
"ProviderType": "oneDriveBusiness",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "edit",
"IsFolder": false
}
Delete attachments
Delete an event attachment
Minimum required scope
One of the following:
- 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, item attachment, or reference attachment.
DELETE https://outlook.office.com/api/beta/me/events/{event_id}/attachments/{attachment_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| event_id | string | The event ID. |
| attachment_id | string | The attachment ID. |
Sample request
DELETE https:/outlook.office.com/api/beta/me/events/AAMkAGE0MG4v1OAAA=/attachments/AAMkAGITG9yAAA=
Sample response
Status code: 204
Get reminders
Get a list of event reminders between two dates and times from a calendar.
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.read
- wl.calendars
- wl.contacts_calendars
GET https://outlook.office.com/api/beta/me/ReminderView(StartDateTime='{DateTime}',EndDateTime='{DateTime}')
| Required parameter | Type | Description |
|---|---|---|
| Header parameters | ||
| Prefer: | outlook.timezone | The default timezone for events in the response. |
| URL parameters | ||
| StartDateTime | string | The starting date and time for returned reminders. |
| EndDateTime | string | The ending date and time for returned reminders. |
Use the Prefer: outlook.timezone header to specify the time zone to use for the event start and end times in the response. If the event was created in a different time zone, the start and end times will be adjusted to the specified time zone.
See this list for the supported time zone names. If the Prefer: outlook.timezone header is not specified, the time zone is set to UTC.
Snooze reminders
Snooze a reminder to postpone the reminder until a new time.
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
POST https://outlook.office.com/api/beta/me/Events('{id}')/SnoozeReminder
| Required paremeters | Type | Description |
|---|---|---|
| URL parameters | ||
| id | string | The ID of the event. |
| Body parameters | ||
| NewReminderTime | DateTimeTimeZone | The new date and time to trigger the reminder. |
Dismiss reminders
Dismiss a reminder that has been triggered.
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
POST https://outlook.office.com/api/beta/me/Events({id})/DismissReminder
| Required paremeters | Type | Description |
|---|---|---|
| URL parameters | ||
| id | string | The ID of the event. |
Get calendars
You can get a calendar collection or get a calendar.
Get a calendar collection
Minimum required scope
One of the following:
- 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/beta/me/calendars
GET https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}/calendars
Note
See OData query parameters for filtering, sorting, and paging parameters.
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calender_group_id | string | The calendar group ID. |
Sample request
GET https://outlook.office.com/api/beta/me/calendars
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Calendars",
"value": [
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Calendars('AAMkAGI2TGuLAAA=')",
"Id": "AAMkAGI2TGuLAAA=",
"Name": "Calendar",
"Color": "Auto",
"ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==",
"IsDefaultCalendar": true,
"CanShare":true,
"CanViewPrivateItems":true,
"IsShared":false,
"IsSharedWithMe":false,
"CanEdit":true,
"Owner":{
"Name":"Fanny Downs",
"Address":"fannyd@adatum.onmicrosoft.com"
}
}
]
}
Get a calendar
Minimum required scope
One of the following:
- 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/beta/me/calendars/{calendar_id}
Note
See OData query parameters for filtering, sorting, and paging parameters.
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calendar_id | string | The calendar ID. |
Sample request
GET https://outlook.office.com/api/beta/me/calendars/AAMkAGI2TGuLAAA=
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Calendars/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Calendars('AAMkAGI2TGuLAAA=')",
"Id": "AAMkAGI2TGuLAAA=",
"Name": "Calendar",
"Color": "Auto",
"IsDefaultCalendar": true,
"ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==",
"CanShare":true,
"CanViewPrivateItems":true,
"IsShared":false,
"IsSharedWithMe":false,
"CanEdit":true,
"Owner":{
"Name":"Fanny Downs",
"Address":"fannyd@adatum.onmicrosoft.com"
}
}
Response type
The requested calendar.
Create calendars
Create a calendar
Minimum required scope
One of the following:
- 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/beta/me/calendars
POST https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}/calendars
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calender_group_id | string | The calendar group ID, if you're getting calendars from a specific group. |
| Body parameters | ||
| Name | string | The name of the new calendar. |
Sample request
POST https://outlook.office.com/api/beta/me/calendars
Content-Type: application/json
{
"Name": "Volunteer"
}
Sample response
Status code: 201
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Calendars/$entity",
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Calendars('AAMkADJmMVAAA=')",
"Id":"AAMkADJmMVAAA=",
"Name":"Volunteer",
"Color":"Auto",
"IsDefaultCalendar":false,
"ChangeKey":"DxYSthXJXEWwAQSYQnXvIgAAIxGttg==",
"CanShare":true,
"CanViewPrivateItems":true,
"IsShared":false,
"IsSharedWithMe":false,
"CanEdit":true,
"Owner":{
"Name":"Fanny Downs",
"Address":"fannyd@adatum.onmicrosoft.com"
}
}
Response type
The new calendar.
Update calendars
Update a calendar
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
Change writable properties of a calendar.
PATCH https://outlook.office.com/api/beta/me/calendars/{calendar_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calendar_id | string | The calendar ID. |
Sample request
PATCH https://outlook.office.com/api/beta/me/calendars/AAMkAGE4xLIAAA=
Content-Type: application/json
{
"Name": "Social events"
}
Sample response
Status code: 200
{
"@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Calendars/$entity",
"@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Calendars('AAMkADJmMVAAA=')",
"Id":"AAMkADJmMVAAA=",
"Name":"Social events",
"Color":"Auto",
"IsDefaultCalendar":false,
"ChangeKey":"DxYSthXJXEWwAQSYQnXvIgAAIxGttg==",
"CanShare":true,
"CanViewPrivateItems":true,
"IsShared":false,
"IsSharedWithMe":false,
"CanEdit":true,
"Owner":{
"Name":"Fanny Downs",
"Address":"fannyd@adatum.onmicrosoft.com"
}
}
Response type
The updated calendar.
Delete calendars
Delete a calendar
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
DELETE https://outlook.office.com/api/beta/me/calendars/{calendar_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calendar_id | string | The calendar ID. |
Sample request
DELETE https://outlook.office.com/api/beta/me/calendars/AAMkAGE4xLIAAA=
Sample response
Status code: 204
Get calendar groups
You can get a calendar group collection or get a calendar group.
Note
Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut.
Get a calendar group collection
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.read
- wl.calendars
- wl.contacts_calendars
Get the calendar groups in a mailbox.
GET https://outlook.office.com/api/beta/me/calendargroups
Note
See OData query parameters for filtering, sorting, and paging parameters.
Sample request
GET https://outlook.office.com/api/beta/me/calendargroups
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups",
"value": [
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGI2TGuKAAA=')",
"Id": "AAMkAGI2TGuKAAA=",
"Name": "My Calendars",
"ClassId": "0006f0b7-0000-0000-c000-000000000046",
"ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g=="
},
{
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGI2TGuMAAA=')",
"Id": "AAMkAGI2TGuMAAA=",
"Name": "Other Calendars",
"ClassId": "0006f0b8-0000-0000-c000-000000000046",
"ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0/A=="
}
]
}
Response type
The requested calendar group collection.
Get a calendar group
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.read
- wl.calendars
- wl.contacts_calendars
Get a calendar group by ID.
GET https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}
Note
See OData query parameters for filtering, sorting, and paging parameters.
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calendar_group_id | string | The calendar group ID. |
Sample request
GET https://outlook.office.com/api/beta/me/calendargroups/AAMkAGI2TGuKAAA=
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGI2TGuKAAA=')",
"Id": "AAMkAGI2TGuKAAA=",
"Name": "My Calendars",
"ClassId": "0006f0b7-0000-0000-c000-000000000046",
"ChangeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+g=="
}
Response type
The requested calendar group.
Create calendar groups
Create a calendar group. Name is the only writable property for a calendar group.
Note
Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut. You cannot
create another calendar group in Outlook.com.
Create a calendar group
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
POST https://outlook.office.com/api/beta/me/calendargroups
| Required parameter | Type | Description |
|---|---|---|
| URL parameter | ||
| Body parameters | ||
| Name | string | The name of the calendar group. |
Sample request
POST https://outlook.office.com/api/beta/me/calendargroups
Content-Type: application/json
{
"Name": "Birthdays"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGE0M4xLGAAA=')",
"@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Rw==\"",
"Id": "AAMkAGE0M4xLGAAA=",
"Name": "Birthdays",
"ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/Rw==",
"ClassId": "4d969bba-8942-42a0-ae33-c7d4410d1e11"
}
Response type
The new calendar group.
Update calendar groups
Update a calendar group
Minimum required scope
One of the following:
- 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/beta/me/calendargroups/{calendar_group_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calendar_group_id | string | The calendar group ID. |
| Body parameters | ||
| Name | string | The name of the updated calendar group. |
Sample request
PATCH https://outlook.office.com/api/beta/me/calendargroups/AAMkAGE0M4xLGAAA=
Content-Type: application/json
{
"Name": "Holidays"
}
Sample response
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/CalendarGroups/$entity",
"@odata.id": "https://https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/CalendarGroups('AAMkAGE0MGM4xLGAAA=')",
"@odata.etag": "W/\"Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SA==\"",
"Id": "AAMkAGE0MGM4xLGAAA=",
"Name": "Holidays",
"ChangeKey": "Jj9S59cHB0Wq4jXUzBgDvQAAFeN/SA==",
"ClassId": "4d969bba-8942-42a0-ae33-c7d4410d1e11"
}
Response type
The updated calendar group.
Delete calendar groups
Note
Outlook.com supports only the default calendar group which is accessible by the ../me/calendars shortcut. Do not
delete this calendar group.
Delete a calendar group
Minimum required scope
One of the following:
- https://outlook.office.com/calendars.readwrite
- wl.calendars_update
- wl.events_create
DELETE https://outlook.office.com/api/beta/me/calendargroups/{calendar_group_id}
| Required parameter | Type | Description |
|---|---|---|
| URL parameters | ||
| calendar_group_id | string | The calendar group ID. |
Sample request
DELETE https://outlook.office.com/api/beta/me/calendargroups/AAMkAGE0MGM4xLGAAA=
Sample response
Status code: 204
Next steps
Whether you're ready to start building an app or just want to learn more, we've got you covered.
Or, learn more about using the Office 365 platform:
- Outlook REST API on the Outlook Dev Center
- Overview of developing on the Office 365 platform
- Office 365 app authentication and resource authorization
- Manually register your app with Azure AD so it can access Office 365 APIs
- Mail API reference
- Contacts API reference
- Task REST API (preview)
- OneDrive API
- Discovery Service REST API operations reference
- Resource reference for the Mail, Calendar, Contacts, and Task REST APIs