Microsoft Exchange Scheduling API

openapi: 3.1.0
info:
  title: Microsoft Exchange Exchange Online Admin Accepted Domains Scheduling API
  description: REST-based administrative API that enables a focused set of Exchange cmdlets and parameters as POST-only endpoints. Provides access to key tasks previously available through Exchange Web Services (EWS), including organization configuration, accepted domains, mailbox properties, mailbox folder permissions, and distribution group membership. Built as a complementary REST-first surface for specific administrative tasks caused by the EWS deprecation planned for October 2026.
  version: 2.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://outlook.office365.com/adminapi/v2.0
  description: Exchange Online Admin API v2.0 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:
    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
    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
    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
    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
    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'
    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
    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
    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)
    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
    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
    PatternedRecurrence:
      type: object
      description: The recurrence pattern and range for an event
      properties:
        pattern:
          $ref: '#/components/schemas/RecurrencePattern'
        range:
          $ref: '#/components/schemas/RecurrenceRange'
    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'
    LocationConstraintItem:
      type: object
      description: A location constraint item
      properties:
        displayName:
          type: string
        locationEmailAddress:
          type: string
        resolveAvailability:
          type: boolean
    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
    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
    PhysicalAddress:
      type: object
      description: Physical street address
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        countryOrRegion:
          type: string
        postalCode:
          type: string
    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
    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
    Recipient:
      type: object
      description: Represents the recipient of an event
      properties:
        emailAddress:
          $ref: '#/components/schemas/EmailAddress'
    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
    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
    TimeSlot:
      type: object
      description: A time period
      properties:
        start:
          $ref: '#/components/schemas/DateTimeTimeZone'
        end:
          $ref: '#/components/schemas/DateTimeTimeZone'
    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
    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'
    LocationConstraint:
      type: object
      description: Conditions for a meeting location
      properties:
        isRequired:
          type: boolean
        suggestLocation:
          type: boolean
        locations:
          type: array
          items:
            $ref: '#/components/schemas/LocationConstraintItem'
    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'
  parameters:
    FilterParam:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
    SkipParam:
      name: $skip
      in: query
      description: The number of items to skip
      schema:
        type: integer
        minimum: 0
    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
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization with Microsoft identity platform
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            https://outlook.office365.com/.default: Default scope for Exchange Online Admin API