Microsoft Exchange Calendars API

openapi: 3.1.0
info:
  title: Microsoft Exchange Exchange Online Admin Accepted Domains Calendars 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: Calendars
  description: Operations for managing calendars
paths:
  /me/calendars:
    get:
      operationId: listCalendars
      summary: Microsoft Exchange List calendars
      description: Get all the user's calendars, or the calendars in the default or other specific calendar group. Returns the calendar collection for the signed-in user.
      tags:
      - Calendars
      parameters:
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      responses:
        '200':
          description: Successfully retrieved calendars
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCalendar
      summary: Microsoft Exchange Create calendar
      description: Create a new calendar in the default calendar group or specified calendar group for the user.
      tags:
      - Calendars
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Calendar'
      responses:
        '201':
          description: Successfully created calendar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/calendars/{calendar-id}:
    get:
      operationId: getCalendar
      summary: Microsoft Exchange Get calendar
      description: Get the properties and relationships of a calendar object. The calendar can be one for a user or the default calendar of a Microsoft 365 group.
      tags:
      - Calendars
      parameters:
      - $ref: '#/components/parameters/CalendarIdParam'
      - $ref: '#/components/parameters/SelectParam'
      responses:
        '200':
          description: Successfully retrieved calendar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCalendar
      summary: Microsoft Exchange Update calendar
      description: Update the properties of a calendar object. The calendar can be one for a user or the default calendar of a Microsoft 365 group.
      tags:
      - Calendars
      parameters:
      - $ref: '#/components/parameters/CalendarIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Calendar'
      responses:
        '200':
          description: Successfully updated calendar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCalendar
      summary: Microsoft Exchange Delete calendar
      description: Delete a calendar other than the user's default calendar.
      tags:
      - Calendars
      parameters:
      - $ref: '#/components/parameters/CalendarIdParam'
      responses:
        '204':
          description: Successfully deleted calendar
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/calendars/{calendar-id}/events:
    get:
      operationId: listCalendarEvents
      summary: Microsoft Exchange List events in calendar
      description: Retrieve a list of events in a specified calendar. The list contains single-instance meetings and series masters.
      tags:
      - Calendars
      parameters:
      - $ref: '#/components/parameters/CalendarIdParam'
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/FilterParam'
      - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Successfully retrieved events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createEventInCalendar
      summary: Microsoft Exchange Create event in calendar
      description: Create a new event in the specified calendar.
      tags:
      - Calendars
      parameters:
      - $ref: '#/components/parameters/CalendarIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '201':
          description: Successfully created event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '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
    PatternedRecurrence:
      type: object
      description: The recurrence pattern and range for an event
      properties:
        pattern:
          $ref: '#/components/schemas/RecurrencePattern'
        range:
          $ref: '#/components/schemas/RecurrenceRange'
    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
    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
    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
    CalendarCollectionResponse:
      type: object
      description: Collection of calendars
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
          format: uri
        value:
          type: array
          items:
            $ref: '#/components/schemas/Calendar'
    TimeSlot:
      type: object
      description: A time period
      properties:
        start:
          $ref: '#/components/schemas/DateTimeTimeZone'
        end:
          $ref: '#/components/schemas/DateTimeTimeZone'
    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'
    Calendar:
      type: object
      description: A container for event resources. Can be a user calendar or a group calendar.
      properties:
        id:
          type: string
          readOnly: true
          description: The calendar's unique identifier
        name:
          type: string
          description: The calendar name
        color:
          type: string
          enum:
          - auto
          - lightBlue
          - lightGreen
          - lightOrange
          - lightGray
          - lightYellow
          - lightTeal
          - lightPink
          - lightBrown
          - lightRed
          - maxColor
          description: Specifies the color theme of the calendar in the UI
        hexColor:
          type: string
          readOnly: true
          description: The calendar color in hex format
        isDefaultCalendar:
          type: boolean
          description: Whether this is the default calendar for new events
        changeKey:
          type: string
          readOnly: true
          description: Identifies the version of the calendar object
        canEdit:
          type: boolean
          readOnly: true
          description: Whether the user can write to the calendar
        canShare:
          type: boolean
          readOnly: true
          description: Whether the user can share the calendar
        canViewPrivateItems:
          type: boolean
          readOnly: true
          description: Whether the user can read private calendar items
        isRemovable:
          type: boolean
          readOnly: true
          description: Whether this user calendar can be deleted
        isTallyingResponses:
          type: boolean
          readOnly: true
          description: Whether this calendar supports tracking meeting responses
        owner:
          $ref: '#/components/schemas/EmailAddress'
        allowedOnlineMeetingProviders:
          type: array
          items:
            type: string
            enum:
            - unknown
            - skypeForBusiness
            - skypeForConsumer
            - teamsForBusiness
          description: Online meeting providers available for this calendar
        defaultOnlineMeetingProvider:
          type: string
          enum:
          - unknown
          - skypeForBusiness
          - skypeForConsumer
          - teamsForBusiness
          description: Default online meeting provider for this calendar
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  parameters:
    OrderByParam:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort by
      schema:
        type: string
    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
    CalendarIdParam:
      name: calendar-id
      in: path
      required: true
      description: The unique identifier of the calendar
      schema:
        type: string
    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
  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