Microsoft Exchange Contact Folders API

openapi: 3.2.0
info:
  title: Microsoft Exchange Microsoft Graph Contacts Contact Folders API
  description: Manage Outlook personal contacts and contact folders for Exchange Online users through the Microsoft Graph API. Supports creating, reading, updating, and deleting contacts, organizing them into folders, and assigning categories. Contacts can be organized into a hierarchy of contact folders.
  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: 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:
  schemas:
    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
    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
    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'
    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
    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
    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'
    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
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  parameters:
    TopParam:
      name: $top
      in: query
      description: The number of items to return
      schema:
        type: integer
        minimum: 1
    SkipParam:
      name: $skip
      in: query
      description: The number of items to skip
      schema:
        type: integer
        minimum: 0
    SelectParam:
      name: $select
      in: query
      description: Comma-separated list of properties to include
      schema:
        type: string
    OrderByParam:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort by
      schema:
        type: string
    ContactFolderIdParam:
      name: contactFolder-id
      in: path
      required: true
      description: The unique identifier of the contact folder
      schema:
        type: string
    FilterParam:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
  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:
            Contacts.Read: Read user contacts
            Contacts.ReadWrite: Read and write user contacts
            Contacts.Read.Shared: Read shared contacts
            Contacts.ReadWrite.Shared: Read and write shared contacts