Microsoft Exchange Scheduling API

openapi: 3.2.0
info:
  title: Microsoft Exchange Microsoft Graph Calendar Scheduling API
  description: Manage calendar events, meetings, and scheduling for Exchange Online users through the Microsoft Graph API. Provides endpoints for creating, updating, and deleting events, managing attendees, handling recurring meetings, finding meeting times, and getting free/busy schedules. Supports both user calendars and Microsoft 365 group calendars.
  version: 1.0.0
  contact:
    name: Microsoft Support
    url: https://support.microsoft.com
    email: support@microsoft.com
  license:
    name: Microsoft API License
    url: https://www.microsoft.com/en-us/legal/terms-of-use
  x-date-modified: '2026-03-04'
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
security:
- oauth2: []
tags:
- name: Scheduling
  description: Operations for scheduling and free/busy information
paths:
  /me/calendarView:
    get:
      operationId: listCalendarView
      summary: Microsoft Exchange List calendar view
      description: Get the occurrences, exceptions, and single instances of events in a calendar view defined by a time range, from the user's primary calendar. Recurring events are expanded into their occurrences within the time range.
      tags:
      - Scheduling
      parameters:
      - name: startDateTime
        in: query
        required: true
        description: The start date and time of the time range in ISO 8601 format
        schema:
          type: string
          format: date-time
      - name: endDateTime
        in: query
        required: true
        description: The end date and time of the time range in ISO 8601 format
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: Successfully retrieved calendar view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/calendar/getSchedule:
    post:
      operationId: getSchedule
      summary: Microsoft Exchange Get free/busy schedule
      description: Get the free/busy availability information for a collection of users, distribution lists, or resources for a specified time period.
      tags:
      - Scheduling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schedules:
                  type: array
                  items:
                    type: string
                  description: Collection of SMTP addresses of users, distribution lists, or resources
                startTime:
                  $ref: '#/components/schemas/DateTimeTimeZone'
                endTime:
                  $ref: '#/components/schemas/DateTimeTimeZone'
                availabilityViewInterval:
                  type: integer
                  description: Duration of each time slot in minutes (default 30, minimum 5, maximum 1440)
              required:
              - schedules
              - startTime
              - endTime
      responses:
        '200':
          description: Successfully retrieved schedule information
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScheduleInformation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/findMeetingTimes:
    post:
      operationId: findMeetingTimes
      summary: Microsoft Exchange Find meeting times
      description: Suggest meeting times and locations based on organizer and attendee availability, and time or location constraints specified as parameters.
      tags:
      - Scheduling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                attendees:
                  type: array
                  items:
                    $ref: '#/components/schemas/AttendeeBase'
                  description: Collection of attendees or resources for the meeting
                timeConstraint:
                  $ref: '#/components/schemas/TimeConstraint'
                locationConstraint:
                  $ref: '#/components/schemas/LocationConstraint'
                meetingDuration:
                  type: string
                  description: The length of the meeting in ISO 8601 duration format
                maxCandidates:
                  type: integer
                  description: Maximum number of meeting time suggestions to return
                isOrganizerOptional:
                  type: boolean
                  description: Indicates whether the organizer's attendance is optional
                returnSuggestionReasons:
                  type: boolean
                  description: Whether to return a reason for each suggestion
                minimumAttendeePercentage:
                  type: number
                  format: double
                  description: Minimum percentage of attendees that must be available
      responses:
        '200':
          description: Successfully found meeting times
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeetingTimeSuggestionsResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    EmailAddress:
      type: object
      description: The name and email address of a person
      properties:
        name:
          type: string
          description: The display name
        address:
          type: string
          format: email
          description: The email address
    PhysicalAddress:
      type: object
      description: Physical street address
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        countryOrRegion:
          type: string
        postalCode:
          type: string
    DateTimeTimeZone:
      type: object
      description: Describes a date, time, and time zone
      properties:
        dateTime:
          type: string
          description: A date and time in ISO 8601 format
        timeZone:
          type: string
          description: A time zone name (e.g. Pacific Standard Time)
    OutlookGeoCoordinates:
      type: object
      description: Geographic coordinates and elevation of a location
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        accuracy:
          type: number
          format: double
        altitude:
          type: number
          format: double
        altitudeAccuracy:
          type: number
          format: double
    TimeSlot:
      type: object
      description: A time period
      properties:
        start:
          $ref: '#/components/schemas/DateTimeTimeZone'
        end:
          $ref: '#/components/schemas/DateTimeTimeZone'
    ScheduleInformation:
      type: object
      description: Free/busy information for a user
      properties:
        scheduleId:
          type: string
          description: SMTP address of the user or resource
        availabilityView:
          type: string
          description: Merged view of availability using single characters (0=free, 1=tentative, 2=busy, 3=oof, 4=workingElsewhere)
        scheduleItems:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleItem'
        workingHours:
          $ref: '#/components/schemas/WorkingHours'
        error:
          type: object
          properties:
            message:
              type: string
            responseCode:
              type: string
    Location:
      type: object
      description: Represents location information for an event
      properties:
        displayName:
          type: string
          description: The name associated with the location
        locationType:
          type: string
          enum:
          - default
          - conferenceRoom
          - homeAddress
          - businessAddress
          - geoCoordinates
          - streetAddress
          - hotel
          - restaurant
          - localBusiness
          - postalAddress
          description: The type of location
        locationUri:
          type: string
          description: URI representing the location
        locationEmailAddress:
          type: string
          description: Email address of the location
        address:
          $ref: '#/components/schemas/PhysicalAddress'
        coordinates:
          $ref: '#/components/schemas/OutlookGeoCoordinates'
        uniqueId:
          type: string
          description: An internal identifier for the location
        uniqueIdType:
          type: string
          enum:
          - unknown
          - locationStore
          - directory
          - private
          - bing
    Recipient:
      type: object
      description: Represents the recipient of an event
      properties:
        emailAddress:
          $ref: '#/components/schemas/EmailAddress'
    MeetingTimeSuggestion:
      type: object
      description: A suggested meeting time
      properties:
        confidence:
          type: number
          format: double
          description: Confidence percentage of all attendees attending
        meetingTimeSlot:
          $ref: '#/components/schemas/TimeSlot'
        organizerAvailability:
          type: string
          enum:
          - free
          - tentative
          - busy
          - oof
          - workingElsewhere
          - unknown
        attendeeAvailability:
          type: array
          items:
            type: object
            properties:
              attendee:
                $ref: '#/components/schemas/AttendeeBase'
              availability:
                type: string
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        suggestionReason:
          type: string
        order:
          type: integer
    ODataError:
      type: object
      description: OData error response
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                date:
                  type: string
                  format: date-time
    PatternedRecurrence:
      type: object
      description: The recurrence pattern and range for an event
      properties:
        pattern:
          $ref: '#/components/schemas/RecurrencePattern'
        range:
          $ref: '#/components/schemas/RecurrenceRange'
    MeetingTimeSuggestionsResult:
      type: object
      description: A collection of meeting time suggestions
      properties:
        '@odata.context':
          type: string
        emptySuggestionsReason:
          type: string
          description: Reason for empty suggestions
        meetingTimeSuggestions:
          type: array
          items:
            $ref: '#/components/schemas/MeetingTimeSuggestion'
    ItemBody:
      type: object
      description: Represents the body content of an event
      properties:
        contentType:
          type: string
          enum:
          - text
          - html
          description: The type of the content
        content:
          type: string
          description: The content of the item body
    RecurrenceRange:
      type: object
      description: The duration of a recurrence
      properties:
        type:
          type: string
          enum:
          - endDate
          - noEnd
          - numbered
        startDate:
          type: string
          format: date
          description: The start date of the recurring series
        endDate:
          type: string
          format: date
          description: The end date of the recurring series
        recurrenceTimeZone:
          type: string
          description: Time zone for the start and end dates
        numberOfOccurrences:
          type: integer
          description: Number of times to repeat the event
    LocationConstraint:
      type: object
      description: Conditions for a meeting location
      properties:
        isRequired:
          type: boolean
        suggestLocation:
          type: boolean
        locations:
          type: array
          items:
            $ref: '#/components/schemas/LocationConstraintItem'
    RecurrencePattern:
      type: object
      description: The frequency of an event recurrence
      properties:
        type:
          type: string
          enum:
          - daily
          - weekly
          - absoluteMonthly
          - relativeMonthly
          - absoluteYearly
          - relativeYearly
        interval:
          type: integer
          description: The number of units between occurrences
        month:
          type: integer
          description: The month in which the event occurs (1-12)
        dayOfMonth:
          type: integer
          description: The day of the month on which the event occurs
        daysOfWeek:
          type: array
          items:
            type: string
            enum:
            - sunday
            - monday
            - tuesday
            - wednesday
            - thursday
            - friday
            - saturday
        firstDayOfWeek:
          type: string
          enum:
          - sunday
          - monday
          - tuesday
          - wednesday
          - thursday
          - friday
          - saturday
        index:
          type: string
          enum:
          - first
          - second
          - third
          - fourth
          - last
    WorkingHours:
      type: object
      description: Working hours for the user
      properties:
        daysOfWeek:
          type: array
          items:
            type: string
            enum:
            - sunday
            - monday
            - tuesday
            - wednesday
            - thursday
            - friday
            - saturday
        startTime:
          type: string
          description: The time of the day the work day starts
        endTime:
          type: string
          description: The time of the day the work day ends
        timeZone:
          type: object
          properties:
            name:
              type: string
    TimeConstraint:
      type: object
      description: Restricts meeting time suggestions to certain time periods
      properties:
        activityDomain:
          type: string
          enum:
          - work
          - personal
          - unrestricted
          - unknown
        timeSlots:
          type: array
          items:
            $ref: '#/components/schemas/TimeSlot'
    Event:
      type: object
      description: An event in a user calendar or the default calendar of a Microsoft 365 group
      properties:
        id:
          type: string
          readOnly: true
          description: Unique identifier for the event
        subject:
          type: string
          description: The text of the event's subject line
        body:
          $ref: '#/components/schemas/ItemBody'
        bodyPreview:
          type: string
          readOnly: true
          description: The preview of the message associated with the event in text format
        start:
          $ref: '#/components/schemas/DateTimeTimeZone'
        end:
          $ref: '#/components/schemas/DateTimeTimeZone'
        location:
          $ref: '#/components/schemas/Location'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
          description: The locations where the event is held or attended from
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/Attendee'
          description: The collection of attendees for the event
        organizer:
          $ref: '#/components/schemas/Recipient'
        isAllDay:
          type: boolean
          description: Whether the event lasts all day
        isCancelled:
          type: boolean
          readOnly: true
          description: Whether the event has been canceled
        isDraft:
          type: boolean
          readOnly: true
          description: Whether the user has updated the event but not sent updates to attendees
        isOnlineMeeting:
          type: boolean
          description: Whether this event has online meeting information
        isOrganizer:
          type: boolean
          readOnly: true
          description: Whether the calendar owner is the organizer
        isReminderOn:
          type: boolean
          description: Whether an alert is set to remind the user
        onlineMeeting:
          $ref: '#/components/schemas/OnlineMeetingInfo'
        onlineMeetingProvider:
          type: string
          enum:
          - unknown
          - teamsForBusiness
          - skypeForBusiness
          - skypeForConsumer
          description: The online meeting service provider
        onlineMeetingUrl:
          type: string
          readOnly: true
          description: URL for an online meeting
        recurrence:
          $ref: '#/components/schemas/PatternedRecurrence'
        reminderMinutesBeforeStart:
          type: integer
          description: Minutes before start time that the reminder alert occurs
        responseRequested:
          type: boolean
          description: Whether the organizer requests invitees to send a response
        responseStatus:
          $ref: '#/components/schemas/ResponseStatus'
        sensitivity:
          type: string
          enum:
          - normal
          - personal
          - private
          - confidential
          description: The event sensitivity level
        seriesMasterId:
          type: string
          readOnly: true
          description: The ID for the recurring series master if this is part of a series
        showAs:
          type: string
          enum:
          - free
          - tentative
          - busy
          - oof
          - workingElsewhere
          - unknown
          description: The status to show for the event
        type:
          type: string
          readOnly: true
          enum:
          - singleInstance
          - occurrence
          - exception
          - seriesMaster
          description: The event type
        importance:
          type: string
          enum:
          - low
          - normal
          - high
          description: The importance of the event
        hasAttachments:
          type: boolean
          readOnly: true
          description: Whether the event has attachments
        categories:
          type: array
          items:
            type: string
          description: The categories associated with the event
        allowNewTimeProposals:
          type: boolean
          description: Whether the organizer allows invitees to propose new times
        iCalUId:
          type: string
          readOnly: true
          description: A unique identifier for an event across calendars
        changeKey:
          type: string
          readOnly: true
          description: Identifies the version of the event
        createdDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the event was created
        lastModifiedDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the event was last changed
        webLink:
          type: string
          format: uri
          readOnly: true
          description: The URL to open the event in Outlook on the web
        transactionId:
          type: string
          description: Custom identifier for client retries to avoid duplicate creation
        hideAttendees:
          type: boolean
          description: When true, each attendee only sees themselves in the meeting request
        originalStartTimeZone:
          type: string
          description: The start time zone set when the event was created
        originalEndTimeZone:
          type: string
          description: The end time zone set when the event was created
    AttendeeBase:
      type: object
      description: Attendee information for meeting time suggestions
      properties:
        emailAddress:
          $ref: '#/components/schemas/EmailAddress'
        type:
          type: string
          enum:
          - required
          - optional
          - resource
          description: The type of attendee
    OnlineMeetingInfo:
      type: object
      description: Details for joining an online meeting
      properties:
        joinUrl:
          type: string
          format: uri
          description: The URL to join the online meeting
        conferenceId:
          type: string
          description: The ID of the conference
        tollNumber:
          type: string
          description: The toll number for the online meeting
        tollFreeNumbers:
          type: array
          items:
            type: string
          description: Toll-free numbers for the online meeting
        quickDial:
          type: string
          description: Quick dial number for the online meeting
        phones:
          type: array
          items:
            type: object
            properties:
              number:
                type: string
              type:
                type: string
                enum:
                - unknown
                - home
                - business
                - mobile
                - other
                - pager
    ResponseStatus:
      type: object
      description: Response status of an attendee or organizer
      properties:
        response:
          type: string
          enum:
          - none
          - organizer
          - tentativelyAccepted
          - accepted
          - declined
          - notResponded
          description: The response type
        time:
          type: string
          format: date-time
          description: The date and time that the response was returned
    EventCollectionResponse:
      type: object
      description: Collection of events
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
          format: uri
        value:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Attendee:
      type: object
      description: An event attendee with response status
      properties:
        emailAddress:
          $ref: '#/components/schemas/EmailAddress'
        type:
          type: string
          enum:
          - required
          - optional
          - resource
          description: The type of attendee
        status:
          $ref: '#/components/schemas/ResponseStatus'
        proposedNewTime:
          $ref: '#/components/schemas/TimeSlot'
    LocationConstraintItem:
      type: object
      description: A location constraint item
      properties:
        displayName:
          type: string
        locationEmailAddress:
          type: string
        resolveAvailability:
          type: boolean
    ScheduleItem:
      type: object
      description: An item that describes availability
      properties:
        start:
          $ref: '#/components/schemas/DateTimeTimeZone'
        end:
          $ref: '#/components/schemas/DateTimeTimeZone'
        isPrivate:
          type: boolean
        status:
          type: string
          enum:
          - free
          - tentative
          - busy
          - oof
          - workingElsewhere
          - unknown
        subject:
          type: string
        location:
          type: string
  parameters:
    TopParam:
      name: $top
      in: query
      description: The number of items to return
      schema:
        type: integer
        minimum: 1
    SelectParam:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response
      schema:
        type: string
    SkipParam:
      name: $skip
      in: query
      description: The number of items to skip
      schema:
        type: integer
        minimum: 0
    FilterParam:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization with Microsoft identity platform
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Calendars.Read: Read user calendars
            Calendars.ReadWrite: Read and write access to user calendars
            Calendars.Read.Shared: Read shared calendars
            Calendars.ReadWrite.Shared: Read and write shared calendars