Microsoft 365 Calendar

Use calendarView (not /events) for date-range queries — it correctly expands recurring events.

Check Free/Busy Time

Get availability for a set of users:

POST /v1.0/users/{userId}/calendar/getSchedule
Content-Type: application/json

{
  "schedules": ["[email protected]", "[email protected]"],
  "startTime": { "dateTime": "2024-01-20T08:00:00", "timeZone": "Eastern Standard Time" },
  "endTime":   { "dateTime": "2024-01-20T17:00:00", "timeZone": "Eastern Standard Time" },
  "availabilityViewInterval": 30
}

Response:

{
  "value": [
    {
      "scheduleId": "[email protected]",
      "availabilityView": "000022220000",
      "scheduleItems": [
        {
          "status": "busy",
          "start": { "dateTime": "2024-01-20T10:00:00" },
          "end":   { "dateTime": "2024-01-20T11:00:00" }
        }
      ]
    }
  ]
}

availabilityView is a string where each character represents a 30-min slot: 0=free, 1=tentative, 2=busy, 3=out-of-office, 4=working elsewhere.

Create a Meeting (with Teams Link)

POST /v1.0/users/{organizerId}/events
Content-Type: application/json

{
  "subject": "IT Onboarding — Jane Smith",
  "start": { "dateTime": "2024-01-20T10:00:00", "timeZone": "Eastern Standard Time" },
  "end":   { "dateTime": "2024-01-20T11:00:00", "timeZone": "Eastern Standard Time" },
  "attendees": [
    { "emailAddress": { "address": "[email protected]" }, "type": "required" },
    { "emailAddress": { "address": "[email protected]" }, "type": "required" }
  ],
  "isOnlineMeeting": true,
  "onlineMeetingProvider": "teamsForBusiness",
  "body": { "contentType": "HTML", "content": "<p>IT onboarding session agenda...</p>" }
}

Get Room Resources

GET /v1.0/places/microsoft.graph.room?$select=id,displayName,emailAddress,capacity,building,floorNumber

Check Room Availability

Use getSchedule with the room's email address as a schedule ID (same as users above).

Cancel an Event

POST /v1.0/users/{userId}/events/{eventId}/cancel
Content-Type: application/json

{
  "comment": "Meeting has been rescheduled. New invite to follow."
}

Update an Event

PATCH /v1.0/users/{userId}/events/{eventId}
Content-Type: application/json

{
  "subject": "Updated: IT Onboarding — Jane Smith",
  "start": { "dateTime": "2024-01-21T14:00:00", "timeZone": "Eastern Standard Time" },
  "end":   { "dateTime": "2024-01-21T15:00:00", "timeZone": "Eastern Standard Time" }
}

Common MSP Workflows

Find Available Meeting Time

1. Get list of required attendees
2. Call getSchedule for all attendees + desired room
3. Parse availabilityView strings to find overlapping free slots
4. Return top 3 options within the user's working hours

Out-of-Office and Calendar Coordination

When setting OOO (via mailbox settings), also check if the user has events during their absence:

1. Get events in the OOO date range
2. List events with other attendees — these may need cancellation or reassignment
3. Cancel/update events as needed
4. Set OOO via mailbox settings

Recurring Event Management

Recurring events are expanded in calendarView results. Each instance has:

• seriesMasterId — the master recurring event ID
• type: "occurrence" — individual instance
• type: "seriesMaster" — the template

To update all future instances: PATCH the series master. To update only one instance: PATCH the specific occurrence.

Error Handling

Permissions Required

Related Skills

• M365 Teams - Teams meetings integration
• M365 Mailboxes - Out-of-office coordination
• M365 Users - Timezone and locale settings