Microsoft Exchange Contacts API

openapi: 3.1.0
info:
  title: Microsoft Exchange Exchange Online Admin Accepted Domains Contacts 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: Contacts
  description: Operations for managing personal contacts
paths:
  /me/contacts:
    get:
      operationId: listContacts
      summary: Microsoft Exchange List contacts
      description: Get a contact collection from the default contacts folder of the signed-in user. Returns all contacts in the user's mailbox.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/FilterParam'
      - $ref: '#/components/parameters/OrderByParam'
      - $ref: '#/components/parameters/SearchParam'
      responses:
        '200':
          description: Successfully retrieved contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createContact
      summary: Microsoft Exchange Create contact
      description: Add a contact to the root contacts folder or the contacts endpoint of another contact folder.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '201':
          description: Successfully created contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/contacts/{contact-id}:
    get:
      operationId: getContact
      summary: Microsoft Exchange Get contact
      description: Read properties and relationships of a contact object.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ContactIdParam'
      - $ref: '#/components/parameters/SelectParam'
      responses:
        '200':
          description: Successfully retrieved contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateContact
      summary: Microsoft Exchange Update contact
      description: Update the properties of a contact object.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ContactIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Successfully updated contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteContact
      summary: Microsoft Exchange Delete contact
      description: Delete a contact object. The contact is moved to the Deleted Items folder.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ContactIdParam'
      responses:
        '204':
          description: Successfully deleted contact
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/contacts/delta:
    get:
      operationId: getContactDelta
      summary: Microsoft Exchange Get contact delta
      description: Get a set of contacts that have been added, deleted, or updated in the user's mailbox. A delta function call for contacts is similar to a GET request, except that by applying state tokens, you can query for incremental changes.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/SelectParam'
      - name: $deltatoken
        in: query
        description: The delta token returned from a previous delta call
        schema:
          type: string
      - name: $skiptoken
        in: query
        description: The skip token for paging through results
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved contact delta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactDeltaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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:
      - Contacts
      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:
      - Contacts
      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'
components:
  parameters:
    ContactIdParam:
      name: contact-id
      in: path
      required: true
      description: The unique identifier of the contact
      schema:
        type: string
    SelectParam:
      name: $select
      in: query
      description: Comma-separated list of properties to include
      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
    SearchParam:
      name: $search
      in: query
      description: Search string to filter results
      schema:
        type: string
    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
  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'
    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
    ContactDeltaResponse:
      type: object
      description: Delta response for contacts
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
          format: uri
        '@odata.deltaLink':
          type: string
          format: uri
          description: URL to get the next set of changes
        value:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    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