Create an event in the user's default calendar or specified calendar.
By default, the allowNewTimeProposals property is set to true when an event is created, which means invitees can propose a different date/time for the event. See Propose new meeting times for more information on how to propose a time, and how to receive and accept a new time proposal.
You can specify the time zone for each of the start and end times of the event as part of their values, because the
start and end properties are of dateTimeTimeZone type. First find the supported time zones to make sure you set only time zones that have been configured for the user's mailbox server.
When an event is sent, the server sends invitations to all the attendees.
Setting the location in an event
An Exchange administrator can set up a mailbox and an email address for a resource such as a meeting room, or equipment
like a projector. Users can then invite the resource as an attendee to a meeting. On behalf of the resource, the server accepts or rejects
the meeting request based on the free/busy schedule of the resource.
If the server accepts a meeting for the resource, it creates an event for the meeting in the resource's calendar. If the meeting is rescheduled,
the server automatically updates the event in the resource's calendar.
Another advantage of setting up a mailbox for a resource is to control scheduling of the resource, for example, only executives
or their delegates can book a private meeting room.
If you're organizing an event that involves a meeting location:
Set the location property of the event accordingly.
Set the optional locationEmailAddress property if the meeting location has an email address.
Additionally, if the meeting location has been set up as a resource, or if the event involves some equipment that has been set up as a resource:
Set the attendee emailAddress as the resource email address.
Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.
Permission type
Permissions (from least to most privileged)
Delegated (work or school account)
Calendars.ReadWrite
Delegated (personal Microsoft account)
Calendars.ReadWrite
Application
Calendars.ReadWrite
HTTP request
POST /me/events
POST /users/{id | userPrincipalName}/events
POST /me/calendar/events
POST /users/{id | userPrincipalName}/calendar/events
POST /me/calendars/{id}/events
POST /users/{id | userPrincipalName}/calendars/{id}/events
Request headers
Header
Value
Authorization
Bearer {token}. Required.
Content-Type
application/json. Required.
Request body
In the request body, supply a JSON representation of event object.
Since the event resource supports extensions, you can use the POST operation and add custom properties with your own data to the event while creating it.
Response
If successful, this method returns 201 Created response code and event object in the response body.
Examples
Example 1: Create an event in the specified time zone, and assign the event an optional transactionId value.
Request
Here is an example of the request. It uses the Prefer: outlook.timezone request header to specify the time zone for the start and end times in the response. It also sets the transactionId property to reduce unnecessary retries on the server.
POST https://graph.microsoft.com/v1.0/me/events
Prefer: outlook.timezone="Pacific Standard Time"
Content-type: application/json
{
"subject": "Let's go for lunch",
"body": {
"contentType": "HTML",
"content": "Does noon work for you?"
},
"start": {
"dateTime": "2017-04-15T12:00:00",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2017-04-15T14:00:00",
"timeZone": "Pacific Standard Time"
},
"location":{
"displayName":"Harry's Bar"
},
"attendees": [
{
"emailAddress": {
"address":"samanthab@contoso.onmicrosoft.com",
"name": "Samantha Booth"
},
"type": "required"
}
],
"allowNewTimeProposals": true,
"transactionId":"7E163156-7762-4BEB-A1C6-729EA81755A7"
}
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Event
{
Subject = "Let's go for lunch",
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "Does noon work for you?",
},
Start = new DateTimeTimeZone
{
DateTime = "2017-04-15T12:00:00",
TimeZone = "Pacific Standard Time",
},
End = new DateTimeTimeZone
{
DateTime = "2017-04-15T14:00:00",
TimeZone = "Pacific Standard Time",
},
Location = new Location
{
DisplayName = "Harry's Bar",
},
Attendees = new List<Attendee>
{
new Attendee
{
EmailAddress = new EmailAddress
{
Address = "samanthab@contoso.onmicrosoft.com",
Name = "Samantha Booth",
},
Type = AttendeeType.Required,
},
},
AllowNewTimeProposals = true,
TransactionId = "7E163156-7762-4BEB-A1C6-729EA81755A7",
};
var result = await graphClient.Me.Events.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "outlook.timezone=\"Pacific Standard Time\"");
});
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Event();
$requestBody->setSubject('Let\'s go for lunch');
$body = new ItemBody();
$body->setContentType(new BodyType('html'));
$body->setContent('Does noon work for you?');
$requestBody->setBody($body);
$start = new DateTimeTimeZone();
$start->setDateTime('2017-04-15T12:00:00');
$start->setTimeZone('Pacific Standard Time');
$requestBody->setStart($start);
$end = new DateTimeTimeZone();
$end->setDateTime('2017-04-15T14:00:00');
$end->setTimeZone('Pacific Standard Time');
$requestBody->setEnd($end);
$location = new Location();
$location->setDisplayName('Harry\'s Bar');
$requestBody->setLocation($location);
$attendeesAttendee1 = new Attendee();
$attendeesAttendee1EmailAddress = new EmailAddress();
$attendeesAttendee1EmailAddress->setAddress('samanthab@contoso.onmicrosoft.com');
$attendeesAttendee1EmailAddress->setName('Samantha Booth');
$attendeesAttendee1->setEmailAddress($attendeesAttendee1EmailAddress);
$attendeesAttendee1->setType(new AttendeeType('required'));
$attendeesArray []= $attendeesAttendee1;
$requestBody->setAttendees($attendeesArray);
$requestBody->setAllowNewTimeProposals(true);
$requestBody->setTransactionId('7E163156-7762-4BEB-A1C6-729EA81755A7');
$requestConfiguration = new EventsRequestBuilderPostRequestConfiguration();
$headers = [
'Prefer' => 'outlook.timezone="Pacific Standard Time"',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->me()->events()->post($requestBody, $requestConfiguration);
In the request body, supply a JSON representation of event object.
Response
Here is an example of the response, which shows the start and end properties use the time zone specified in the Prefer: outlook.timezone header.
Note: The response object shown here might be shortened for readability.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Event
{
Subject = "Plan summer company picnic",
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "Let's kick-start this event planning!",
},
Start = new DateTimeTimeZone
{
DateTime = "2017-08-30T11:00:00",
TimeZone = "Pacific Standard Time",
},
End = new DateTimeTimeZone
{
DateTime = "2017-08-30T12:00:00",
TimeZone = "Pacific Standard Time",
},
Attendees = new List<Attendee>
{
new Attendee
{
EmailAddress = new EmailAddress
{
Address = "DanaS@contoso.onmicrosoft.com",
Name = "Dana Swope",
},
Type = AttendeeType.Required,
},
new Attendee
{
EmailAddress = new EmailAddress
{
Address = "AlexW@contoso.onmicrosoft.com",
Name = "Alex Wilber",
},
Type = AttendeeType.Required,
},
},
Location = new Location
{
DisplayName = "Conf Room 3; Fourth Coffee; Home Office",
LocationType = LocationType.Default,
},
Locations = new List<Location>
{
new Location
{
DisplayName = "Conf Room 3",
},
new Location
{
DisplayName = "Fourth Coffee",
Address = new PhysicalAddress
{
Street = "4567 Main St",
City = "Redmond",
State = "WA",
CountryOrRegion = "US",
PostalCode = "32008",
},
Coordinates = new OutlookGeoCoordinates
{
Latitude = 47.672d,
Longitude = -102.103d,
},
},
new Location
{
DisplayName = "Home Office",
},
},
AllowNewTimeProposals = true,
};
var result = await graphClient.Me.Events.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "outlook.timezone=\"Pacific Standard Time\"");
});
The following example response shows the created event that specifies information for the 3 locations for the meeting. Because of the
Prefer: outlook.timezone="Pacific Standard Time" request header, the start and end properties are expressed in PST.
Note: The response object shown here might be shortened for readability.
The third example shows how to create a recurring event that occurs once a week. The event occurs from 12:00pm to 2:00pm, every Monday starting September 4, 2017, through the end of the year.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Event
{
Subject = "Let's go for lunch",
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "Does noon time work for you?",
},
Start = new DateTimeTimeZone
{
DateTime = "2017-09-04T12:00:00",
TimeZone = "Pacific Standard Time",
},
End = new DateTimeTimeZone
{
DateTime = "2017-09-04T14:00:00",
TimeZone = "Pacific Standard Time",
},
Recurrence = new PatternedRecurrence
{
Pattern = new RecurrencePattern
{
Type = RecurrencePatternType.Weekly,
Interval = 1,
DaysOfWeek = new List<DayOfWeekObject?>
{
DayOfWeekObject.Monday,
},
},
Range = new RecurrenceRange
{
Type = RecurrenceRangeType.EndDate,
StartDate = new Date(DateTime.Parse("2017-09-04")),
EndDate = new Date(DateTime.Parse("2017-12-31")),
},
},
Location = new Location
{
DisplayName = "Harry's Bar",
},
Attendees = new List<Attendee>
{
new Attendee
{
EmailAddress = new EmailAddress
{
Address = "AdeleV@contoso.onmicrosoft.com",
Name = "Adele Vance",
},
Type = AttendeeType.Required,
},
},
AllowNewTimeProposals = true,
};
var result = await graphClient.Me.Events.PostAsync(requestBody);
Example 4: Create and enable an event as an online meeting
Request
Here is an example of a request which creates an event and enables it as an online meeting. It uses the Prefer: outlook.timezone request header to specify the time zone for the start and end
times in the response.
POST https://graph.microsoft.com/v1.0/me/events
Prefer: outlook.timezone="Pacific Standard Time"
Content-type: application/json
{
"subject": "Let's go for lunch",
"body": {
"contentType": "HTML",
"content": "Does noon work for you?"
},
"start": {
"dateTime": "2017-04-15T12:00:00",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2017-04-15T14:00:00",
"timeZone": "Pacific Standard Time"
},
"location":{
"displayName":"Harry's Bar"
},
"attendees": [
{
"emailAddress": {
"address":"samanthab@contoso.onmicrosoft.com",
"name": "Samantha Booth"
},
"type": "required"
}
],
"allowNewTimeProposals": true,
"isOnlineMeeting": true,
"onlineMeetingProvider": "teamsForBusiness"
}
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Event
{
Subject = "Let's go for lunch",
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "Does noon work for you?",
},
Start = new DateTimeTimeZone
{
DateTime = "2017-04-15T12:00:00",
TimeZone = "Pacific Standard Time",
},
End = new DateTimeTimeZone
{
DateTime = "2017-04-15T14:00:00",
TimeZone = "Pacific Standard Time",
},
Location = new Location
{
DisplayName = "Harry's Bar",
},
Attendees = new List<Attendee>
{
new Attendee
{
EmailAddress = new EmailAddress
{
Address = "samanthab@contoso.onmicrosoft.com",
Name = "Samantha Booth",
},
Type = AttendeeType.Required,
},
},
AllowNewTimeProposals = true,
IsOnlineMeeting = true,
OnlineMeetingProvider = OnlineMeetingProviderType.TeamsForBusiness,
};
var result = await graphClient.Me.Events.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "outlook.timezone=\"Pacific Standard Time\"");
});
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Event();
$requestBody->setSubject('Let\'s go for lunch');
$body = new ItemBody();
$body->setContentType(new BodyType('html'));
$body->setContent('Does noon work for you?');
$requestBody->setBody($body);
$start = new DateTimeTimeZone();
$start->setDateTime('2017-04-15T12:00:00');
$start->setTimeZone('Pacific Standard Time');
$requestBody->setStart($start);
$end = new DateTimeTimeZone();
$end->setDateTime('2017-04-15T14:00:00');
$end->setTimeZone('Pacific Standard Time');
$requestBody->setEnd($end);
$location = new Location();
$location->setDisplayName('Harry\'s Bar');
$requestBody->setLocation($location);
$attendeesAttendee1 = new Attendee();
$attendeesAttendee1EmailAddress = new EmailAddress();
$attendeesAttendee1EmailAddress->setAddress('samanthab@contoso.onmicrosoft.com');
$attendeesAttendee1EmailAddress->setName('Samantha Booth');
$attendeesAttendee1->setEmailAddress($attendeesAttendee1EmailAddress);
$attendeesAttendee1->setType(new AttendeeType('required'));
$attendeesArray []= $attendeesAttendee1;
$requestBody->setAttendees($attendeesArray);
$requestBody->setAllowNewTimeProposals(true);
$requestBody->setIsOnlineMeeting(true);
$requestBody->setOnlineMeetingProvider(new OnlineMeetingProviderType('teamsforbusiness'));
$requestConfiguration = new EventsRequestBuilderPostRequestConfiguration();
$headers = [
'Prefer' => 'outlook.timezone="Pacific Standard Time"',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->me()->events()->post($requestBody, $requestConfiguration);
In the request body, supply a JSON representation of event object.
Response
Here is an example of the response, which shows the start and end properties use the time zone specified in the Prefer: outlook.timezone header.
Note: The response object shown here might be shortened for readability.