Microsoft Exchange Contact Folders API

openapi: 3.1.0
info:
  title: Microsoft Exchange Exchange Online Admin Accepted Domains Contact Folders 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: Contact Folders
  description: Operations for managing contact folders
paths:
  /me/contactFolders:
    get:
      operationId: listContactFolders
      summary: Microsoft Exchange List contact folders
      description: Get the contact folder collection in the default contacts folder of the signed-in user.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      responses:
        '200':
          description: Successfully retrieved contact folders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFolderCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createContactFolder
      summary: Microsoft Exchange Create contact folder
      description: Create a new contact folder as a child of a specified folder or as a top-level folder.
      tags:
      - Contact Folders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactFolder'
      responses:
        '201':
          description: Successfully created contact folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFolder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/contactFolders/{contactFolder-id}:
    get:
      operationId: getContactFolder
      summary: Microsoft Exchange Get contact folder
      description: Get a contact folder by using the contact folder ID.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/ContactFolderIdParam'
      - $ref: '#/components/parameters/SelectParam'
      responses:
        '200':
          description: Successfully retrieved contact folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFolder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateContactFolder
      summary: Microsoft Exchange Update contact folder
      description: Update the properties of a contact folder object.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/ContactFolderIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactFolder'
      responses:
        '200':
          description: Successfully updated contact folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFolder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteContactFolder
      summary: Microsoft Exchange Delete contact folder
      description: Delete a contact folder. The folder is moved to the Deleted Items folder.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/ContactFolderIdParam'
      responses:
        '204':
          description: Successfully deleted contact folder
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/contactFolders/{contactFolder-id}/contacts:
    get:
      operationId: listContactsInFolder
      summary: Microsoft Exchange List contacts in folder
      description: Get a contact collection from the specified contact folder.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/ContactFolderIdParam'
      - $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 contacts in folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createContactInFolder
      summary: Microsoft Exchange Create contact in folder
      description: Add a contact to the specified contact folder.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/ContactFolderIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '201':
          description: Successfully created contact in folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/contactFolders/{contactFolder-id}/childFolders:
    get:
      operationId: listContactChildFolders
      summary: Microsoft Exchange List child contact folders
      description: Get a collection of child folders under the specified contact folder.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/ContactFolderIdParam'
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      responses:
        '200':
          description: Successfully retrieved child folders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFolderCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createContactChildFolder
      summary: Microsoft Exchange Create child contact folder
      description: Create a new contact folder as a child of the specified folder.
      tags:
      - Contact Folders
      parameters:
      - $ref: '#/components/parameters/ContactFolderIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactFolder'
      responses:
        '201':
          description: Successfully created child folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactFolder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    SelectParam:
      name: $select
      in: query
      description: Comma-separated list of properties to include
      schema:
        type: string
    FilterParam:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
    TopParam:
      name: $top
      in: query
      description: The number of items to return
      schema:
        type: integer
        minimum: 1
    ContactFolderIdParam:
      name: contactFolder-id
      in: path
      required: true
      description: The unique identifier of the contact folder
      schema:
        type: string
    OrderByParam:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort by
      schema:
        type: string
    SkipParam:
      name: $skip
      in: query
      description: The number of items to skip
      schema:
        type: integer
        minimum: 0
  schemas:
    ContactCollectionResponse:
      type: object
      description: Collection of contacts
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
          format: uri
        value:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    ContactFolder:
      type: object
      description: A folder that contains contacts
      properties:
        id:
          type: string
          readOnly: true
          description: The contact folder's unique identifier
        displayName:
          type: string
          description: The folder's display name
        parentFolderId:
          type: string
          readOnly: true
          description: The ID of the folder's parent folder
    PhysicalAddress:
      type: object
      description: Physical street address
      properties:
        street:
          type: string
          description: The street address
        city:
          type: string
          description: The city
        state:
          type: string
          description: The state or province
        countryOrRegion:
          type: string
          description: The country or region
        postalCode:
          type: string
          description: The postal code
    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: Email address of a contact
      properties:
        name:
          type: string
          description: The display name
        address:
          type: string
          format: email
          description: The email address
    ContactFolderCollectionResponse:
      type: object
      description: Collection of contact folders
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
          format: uri
        value:
          type: array
          items:
            $ref: '#/components/schemas/ContactFolder'
    Contact:
      type: object
      description: A contact is an item in Outlook where you can organize and save information about people and organizations you communicate with. Contacts are contained in contact folders.
      properties:
        id:
          type: string
          readOnly: true
          description: The contact's unique identifier
        displayName:
          type: string
          description: The contact's display name
        givenName:
          type: string
          description: The contact's given name (first name)
        surname:
          type: string
          description: The contact's surname (last name)
        middleName:
          type: string
          description: The contact's middle name
        nickName:
          type: string
          description: The contact's nickname
        title:
          type: string
          description: The contact's title
        initials:
          type: string
          description: The contact's initials
        generation:
          type: string
          description: The contact's suffix
        emailAddresses:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          description: The contact's email addresses
        businessPhones:
          type: array
          items:
            type: string
          description: The contact's business phone numbers
        homePhones:
          type: array
          items:
            type: string
          description: The contact's home phone numbers
        mobilePhone:
          type: string
          description: The contact's mobile phone number
        imAddresses:
          type: array
          items:
            type: string
          description: The contact's instant messaging addresses
        jobTitle:
          type: string
          description: The contact's job title
        companyName:
          type: string
          description: The name of the contact's company
        department:
          type: string
          description: The contact's department
        officeLocation:
          type: string
          description: The location of the contact's office
        profession:
          type: string
          description: The contact's profession
        manager:
          type: string
          description: The name of the contact's manager
        assistantName:
          type: string
          description: The name of the contact's assistant
        businessHomePage:
          type: string
          description: The business home page of the contact
        businessAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        homeAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        otherAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        spouseName:
          type: string
          description: The name of the contact's spouse or partner
        birthday:
          type: string
          format: date-time
          description: The contact's birthday in ISO 8601 format (always UTC)
        children:
          type: array
          items:
            type: string
          description: The names of the contact's children
        personalNotes:
          type: string
          description: The user's notes about the contact
        fileAs:
          type: string
          description: The name the contact is filed under
        categories:
          type: array
          items:
            type: string
          description: The categories associated with the contact
        parentFolderId:
          type: string
          readOnly: true
          description: The ID of the contact's parent folder
        changeKey:
          type: string
          readOnly: true
          description: Identifies the version of the contact
        createdDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The time the contact was created
        lastModifiedDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The time the contact was last modified
        yomiGivenName:
          type: string
          description: Phonetic Japanese given name
        yomiSurname:
          type: string
          description: Phonetic Japanese surname
        yomiCompanyName:
          type: string
          description: Phonetic Japanese company name
  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'
  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