event resource type
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
An event in a user calendar, or the default calendar of a Microsoft 365 group.
The maximum number of attendees included in an event, and the maximum number of recipients in an eventMessage sent from an Exchange Online mailbox is 500. For more information, see sending limits.
This resource supports:
- Adding your own data to custom properties as extensions.
- Subscribing to change notifications.
- Using delta query to track incremental additions, deletions, and updates, by providing a delta function.
Note: There are a few minor differences in the way you can interact with user calendars, group calendars, and their events:
- You can organize only user calendars in a calendarGroup.
- You can add attachment objects to events in only user calendars, but not to events in group calendars.
- Outlook automatically accepts all meeting requests on behalf of groups. You can accept, tentatively accept, or decline meeting requests for user calendars only.
- Outlook doesn't support reminders for group events. You can snooze or dismiss a reminder for user calendars only.
Methods
| Method | Return Type | Description |
|---|---|---|
| List | Event collection | Retrieve a list of event objects in the user's mailbox. The list contains single instance meetings and series masters. |
| Create | event | Create a new event by posting to the instances collection. |
| Get | event | Read properties and relationships of event object. |
| Update | event | Update event object. |
| Delete | None | Delete event object. |
| Permanently delete | None | Permanently delete an event and place it in the Purges folder in the Recoverable Items folder in the user's mailbox. |
| Get delta | event collection | Get a set of events that were added, deleted, or updated in a calendarView (a range of events) of the user's primary calendar. |
| Forward event | None | Lets the organizer or attendee of a meeting event forward the meeting request to a new recipient. |
| Cancel event | None | Send cancellation message from the organizer to all the attendees and cancel the specified meeting. |
| Accept event | None | Accept the specified event in a user calendar. |
| Tentatively accept | None | Tentatively accept the specified event in a user calendar. |
| Decline event | None | Decline invitation to the specified event in a user calendar. |
| Dismiss reminder | None | Dismiss the reminder for the specified event in a user calendar. |
| Snooze reminder | None | Postpone a reminder for the specified event in a user calendar until a new time. |
| List event instances | Event collection | Get an event object collection. |
| Attachments | ||
| List attachments | Attachment collection | Get all attachments on an event. |
| Add attachment | Attachment | Add a new attachment to an event by posting to the attachments collection. |
| Open extensions | ||
| Create open extension | openTypeExtension | Create an open extension and add custom properties to a new or existing resource. |
| Get open extension | openTypeExtension collection | Get an open extension identified by the extension name. |
| Extended properties | ||
| Create single-value property | event | Create one or more single-value extended properties in a new or existing event. |
| Get single-value property | event | Get events that contain a single-value extended property by using $expand or $filter. |
| Create multi-value property | event | Create one or more multi-value extended properties in a new or existing event. |
| Get multi-value property | event | Get an event that contains a multi-value extended property by using $expand. |
Properties
| Property | Type | Description |
|---|---|---|
| allowNewTimeProposals | Boolean | true if the meeting organizer allows invitees to propose a new time when responding; otherwise false. Optional. Default is true. |
| attendees | Attendee collection | The collection of attendees for the event. |
| body | ItemBody | The body of the message associated with the event. It can be in HTML or text format. |
| bodyPreview | String | The preview of the message associated with the event. It is in text format. |
| cancelledOccurrences | String collection | Contains occurrenceId property values of canceled instances in a recurring series, if the event is the series master. Instances in a recurring series that are canceled are called cancelledOccurences. Returned only on $select in a Get operation which specifies the id of a series master event (that is, the seriesMasterId property value). |
| categories | String collection | The categories associated with the event. Each category corresponds to the displayName property of an outlookCategory defined for the user. |
| changeKey | String | Identifies the version of the event object. Every time the event is changed, ChangeKey changes as well. This allows Exchange to apply changes to the correct version of the object. |
| createdDateTime | DateTimeOffset | The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z |
| end | DateTimeTimeZone | The date, time, and time zone that the event ends. By default, the end time is in UTC. |
| exceptionOccurrences | event collection | Contains the id property values of the event instances that are exceptions in a recurring series. Exceptions can differ from other occurrences in a recurring series, such as the subject, start or end times, or attendees. Exceptions don't include canceled occurrences. Returned only on $select and $expand in a GET operation that specifies the id of a series master event (that is, the seriesMasterId property value). |
| hasAttachments | Boolean | Set to true if the event has attachments. |
| hideAttendees | Boolean | When set to true, each attendee only sees themselves in the meeting request and meeting Tracking list. Default is false. |
| iCalUId | String | A unique identifier for an event across calendars. This ID is different for each occurrence in a recurring series. Read-only. |
| id | String | Unique identifier for the event. By default, this value changes when the item is moved from one container (such as a folder or calendar) to another. To change this behavior, use the Prefer: IdType="ImmutableId" header. See Get immutable identifiers for Outlook resources for more information. Case-sensitive and read-only. |
| importance | String | The importance of the event. Possible values are: low, normal, high. |
| isAllDay | Boolean | Set to true if the event lasts all day. If true, regardless of whether it's a single-day or multi-day event, start and end time must be set to midnight and be in the same time zone. |
| isCancelled | Boolean | Set to true if the event has been canceled. |
| isDraft | Boolean | Set to true if the user has updated the meeting in Outlook but hasn't sent the updates to attendees. Set to false if all changes have been sent, or if the event is an appointment without any attendees. |
| isOnlineMeeting | Boolean | True if this event has online meeting information (that is, onlineMeeting points to an onlineMeetingInfo resource), false otherwise. Default is false (onlineMeeting is null). Optional. After you set isOnlineMeeting to true, Microsoft Graph initializes onlineMeeting. Outlook then ignores any further changes to isOnlineMeeting, and the meeting remains available online. |
| isOrganizer | Boolean | Set to true if the calendar owner (specified by the owner property of the calendar) is the organizer of the event (specified by the organizer property of the event). This also applies if a delegate organized the event on behalf of the owner. |
| isReminderOn | Boolean | Set to true if an alert is set to remind the user of the event. |
| lastModifiedDateTime | DateTimeOffset | The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z |
| location | Location | The location of the event. |
| locations | Location collection | The locations where the event is held or attended from. The location and locations properties always correspond with each other. If you update the location property, any prior locations in the locations collection would be removed and replaced by the new location value. |
| occurrenceId | String | An identifier for an occurrence in a recurring event series. Null if the event isn't part of a recurring series. The format of the property value is OID.{seriesMasterId-value}.{occurrence-start-date}. The time zone for {occurrence-start-date} is the recurrenceTimeZone property defined for the corresponding recurrenceRange. This property can identify any occurrence in a recurring series, including an occurrence that has been modified or canceled. You can use this property to perform all operations supported by occurrences in the recurring series. |
| onlineMeeting | OnlineMeetingInfo | Details for an attendee to join the meeting online. Default is null. Read-only. After you set the isOnlineMeeting and onlineMeetingProvider properties to enable a meeting online, Microsoft Graph initializes onlineMeeting. When set, the meeting remains available online, and you can't change the isOnlineMeeting, onlineMeetingProvider, and onlneMeeting properties again. |
| onlineMeetingProvider | onlineMeetingProviderType | Represents the online meeting service provider. By default, onlineMeetingProvider is unknown. The possible values are unknown, teamsForBusiness, skypeForBusiness, and skypeForConsumer. Optional. After you set onlineMeetingProvider, Microsoft Graph initializes onlineMeeting. Subsequently you can't change onlineMeetingProvider again, and the meeting remains available online. |
| onlineMeetingUrl | String | A URL for an online meeting. The property is set only when an organizer specifies in Outlook that an event is an online meeting such as Skype. Read-only. To access the URL to join an online meeting, use joinUrl which is exposed via the onlineMeeting property of the event. The onlineMeetingUrl property will be deprecated in the future. |
| organizer | Recipient | The organizer of the event. |
| originalEndTimeZone | String | The end time zone that was set when the event was created. A value of tzone://Microsoft/Custom indicates that a legacy custom time zone was set in desktop Outlook. |
| originalStart | DateTimeOffset | Represents the start time of an event when it's initially created as an occurrence or exception in a recurring series. This property isn't returned for events that are single instances. Its date and time information is expressed in ISO 8601 format and is always in UTC. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z |
| originalStartTimeZone | String | The start time zone that was set when the event was created. A value of tzone://Microsoft/Custom indicates that a legacy custom time zone was set in desktop Outlook. |
| recurrence | PatternedRecurrence | The recurrence pattern for the event. |
| reminderMinutesBeforeStart | Int32 | The number of minutes before the event start time that the reminder alert occurs. |
| responseRequested | Boolean | Default is true, which represents the organizer would like an invitee to send a response to the event. |
| responseStatus | ResponseStatus | Indicates the type of response sent in response to an event message. |
| sensitivity | String | Possible values are: normal, personal, private, confidential. |
| seriesMasterId | String | The ID for the recurring series master item, if this event is part of a recurring series. |
| showAs | String | The status to show. Possible values are: free, tentative, busy, oof, workingElsewhere, unknown. |
| start | DateTimeTimeZone | The start date, time, and time zone of the event. By default, the start time is in UTC. |
| subject | String | The text of the event's subject line. |
| transactionId | String | A custom identifier specified by a client app for the server to avoid redundant POST operations if the client retries to create the same event. This is useful when low network connectivity causes the client to time out before receiving a response from the server for the client's prior create-event request. After you set transactionId when creating an event, you can't change transactionId in a subsequent update. This property is only returned in a response payload if an app has set it. Optional. |
| type | String | The event type. Possible values are: singleInstance, occurrence, exception, seriesMaster. Read-only |
| uid | String | A unique identifier for calendar events. For recurring events, the value is the same for the series master and all of its occurrences including exceptions. |
| webLink | String | The URL to open the event in Outlook on the web. Outlook on the web opens the event in the browser if you're signed in to your mailbox. Otherwise, Outlook on the web prompts you to sign in. This URL can't be accessed from within an iFrame. |
Note
The webLink property specifies a URL that opens the event in only earlier versions of Outlook on the web. The following is its URL format, with {event-id} being the URL-encoded value of the id property:
For work or school accounts:
https://outlook.office365.com/owa/?itemid={event-id}&exvsurl=1&path=/calendar/itemFor Microsoft accounts:
https://outlook.live.com/owa/?itemid={event-id}&exvsurl=1&path=/calendar/item
To open the event in a current version of Outlook on the web, convert the URL to one of the following formats, and use that URL to open the event:
For work or school accounts:
https://outlook.office365.com/calendar/item/{event-id}For Microsoft accounts:
https://outlook.live.com/calendar/item/{event-id}
Relationships
| Relationship | Type | Description |
|---|---|---|
| attachments | Attachment collection | The collection of FileAttachment, ItemAttachment, and referenceAttachment attachments for the event. Navigation property. Read-only. Nullable. |
| calendar | Calendar | The calendar that contains the event. Navigation property. Read-only. |
| extensions | Extension collection | The collection of open extensions defined for the event. Nullable. |
| instances | Event collection | The occurrences of a recurring series, if the event is a series master. This property includes occurrences that are part of the recurrence pattern and exceptions that have been modified. It doesn't include occurrences that have been canceled from the series. Navigation property. Read-only. Nullable. |
| multiValueExtendedProperties | multiValueLegacyExtendedProperty collection | The collection of multi-value extended properties defined for the event. Read-only. Nullable. |
| singleValueExtendedProperties | singleValueLegacyExtendedProperty collection | The collection of single-value extended properties defined for the event. Read-only. Nullable. |
JSON representation
The following JSON representation shows the resource type.
{
"allowNewTimeProposals": "Boolean",
"attendees": [{"@odata.type": "microsoft.graph.attendee"}],
"body": {"@odata.type": "microsoft.graph.itemBody"},
"bodyPreview": "string",
"cancelledOccurrences":["string"],
"categories": ["string"],
"changeKey": "string",
"createdDateTime": "String (timestamp)",
"end": {"@odata.type": "microsoft.graph.dateTimeTimeZone"},
"exceptionOccurrences":["microsoft.graph.event"],
"hasAttachments": true,
"hideAttendees": false,
"iCalUId": "String",
"id": "string (identifier)",
"importance": "String",
"isAllDay": true,
"isCancelled": true,
"isDraft": false,
"isOnlineMeeting": true,
"isOrganizer": true,
"isReminderOn": true,
"lastModifiedDateTime": "String (timestamp)",
"location": {"@odata.type": "microsoft.graph.location"},
"locations": [{"@odata.type": "microsoft.graph.location"}],
"occurrenceId":"string",
"onlineMeeting": {"@odata.type": "microsoft.graph.onlineMeetingInfo"},
"onlineMeetingProvider": "string",
"onlineMeetingUrl": "string",
"organizer": {"@odata.type": "microsoft.graph.recipient"},
"originalEndTimeZone": "string",
"originalStart": "String (timestamp)",
"originalStartTimeZone": "string",
"recurrence": {"@odata.type": "microsoft.graph.patternedRecurrence"},
"reminderMinutesBeforeStart": 1024,
"responseRequested": true,
"responseStatus": {"@odata.type": "microsoft.graph.responseStatus"},
"sensitivity": "String",
"seriesMasterId": "string",
"showAs": "String",
"start": {"@odata.type": "microsoft.graph.dateTimeTimeZone"},
"subject": "string",
"type": "String",
"uid": "String",
"webLink": "string",
"attachments": [ { "@odata.type": "microsoft.graph.attachment" } ],
"calendar": { "@odata.type": "microsoft.graph.calendar" },
"extensions": [ { "@odata.type": "microsoft.graph.extension" } ],
"instances": [ { "@odata.type": "microsoft.graph.event" }],
"singleValueExtendedProperties": [ { "@odata.type": "microsoft.graph.singleValueLegacyExtendedProperty" }],
"multiValueExtendedProperties": [ { "@odata.type": "microsoft.graph.multiValueLegacyExtendedProperty" }]
}