Microsoft Graph Contacts is the part of Microsoft Graph that lets apps access and manage the contacts stored in Microsoft 365 (Outlook) mailboxes through a single REST API. It enables you to list, search, create, update, and delete contacts and contact folders for the signed-in user or other mailboxes you have permission to access, synchronize changes with delta queries, retrieve or update contact photos, and filter/sort results with OData queries.
openapi: 3.1.0
info:
title: Microsoft Graph Contacts
description: Needs a description.
paths:
/contacts:
description: Provides operations to manage the collection of orgContact entities.
get:
tags:
- contacts.orgContact
summary: Microsoft Graph List orgContacts
description: Get the list of organizational contacts for this organization.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/orgcontact-list?view=graph-rest-1.0
operationId: contacts.orgContact.ListOrgContact
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/microsoft.graph.orgContactCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
/contacts/{orgContact-id}:
description: Provides operations to manage the collection of orgContact entities.
get:
tags:
- contacts.orgContact
summary: Microsoft Graph Get orgContact
description: Get the properties and relationships of an organizational contact.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/orgcontact-get?view=graph-rest-1.0
operationId: contacts.orgContact.GetOrgContact
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.orgContact'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- contacts.orgContact
summary: Microsoft Graph Update entity in contacts
operationId: contacts.orgContact.UpdateOrgContact
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.orgContact'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.orgContact'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- contacts.orgContact
summary: Microsoft Graph Delete entity from contacts
operationId: contacts.orgContact.DeleteOrgContact
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/directReports:
description: >-
Provides operations to manage the directReports property of the
microsoft.graph.orgContact entity.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph List directReports
description: Get the direct reports for this organizational contact.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/orgcontact-list-directreports?view=graph-rest-1.0
operationId: contacts.ListDirectReports
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.directoryObjectCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/directReports/{directoryObject-id}:
description: >-
Provides operations to manage the directReports property of the
microsoft.graph.orgContact entity.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph Get directReports from contacts
description: >-
The contact's direct reports. (The users and contacts that have their
manager property set to this contact.) Read-only. Nullable. Supports
$expand.
operationId: contacts.GetDirectReports
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/contacts/{orgContact-id}/directReports/{directoryObject-id}/graph.orgContact:
description: Casts the previous resource to orgContact.
get:
tags:
- contacts.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.orgContact
operationId: contacts.GetDirectReports.AsOrgContact
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.orgContact'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/contacts/{orgContact-id}/directReports/{directoryObject-id}/graph.user:
description: Casts the previous resource to user.
get:
tags:
- contacts.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.user
operationId: contacts.GetDirectReports.AsUser
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.user'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/contacts/{orgContact-id}/directReports/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph Get the number of the resource
operationId: contacts.directReports.GetCount-94c4
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/directReports/graph.orgContact:
description: Casts the previous resource to orgContact.
get:
tags:
- contacts.directoryObject
summary: >-
Microsoft Graph Get the items of type microsoft.graph.orgContact in the microsoft.graph.directoryObject collection
operationId: contacts.ListDirectReports.AsOrgContact
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/microsoft.graph.orgContactCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/directReports/graph.orgContact/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph Get the number of the resource
operationId: contacts.DirectReports.GetCount.AsOrgContact-315a
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/directReports/graph.user:
description: Casts the previous resource to user.
get:
tags:
- contacts.directoryObject
summary: >-
Microsoft Graph Get the items of type microsoft.graph.user in the microsoft.graph.directoryObject collection
operationId: contacts.ListDirectReports.AsUser
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/microsoft.graph.userCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/directReports/graph.user/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph Get the number of the resource
operationId: contacts.DirectReports.GetCount.AsUser-5746
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/manager:
description: >-
Provides operations to manage the manager property of the
microsoft.graph.orgContact entity.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph Get manager
description: Get this organizational contact's manager.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/orgcontact-get-manager?view=graph-rest-1.0
operationId: contacts.GetManager
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/memberOf:
description: >-
Provides operations to manage the memberOf property of the
microsoft.graph.orgContact entity.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph List memberOf
description: List the groups that this organizational contact is a member of.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/orgcontact-list-memberof?view=graph-rest-1.0
operationId: contacts.ListMemberOf
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.directoryObjectCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
/contacts/{orgContact-id}/memberOf/{directoryObject-id}:
description: >-
Provides operations to manage the memberOf property of the
microsoft.graph.orgContact entity.
get:
tags:
- contacts.directoryObject
summary: Microsoft Graph Get memberOf from contacts
description: >-
Groups that this contact is a member of. Read-only. Nullable. Supports
$expand.
operationId: contacts.GetMemberOf
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/contacts/{orgContact-id}/memberOf/{directoryObject-id}/graph.administrativeUnit:
description: Casts the previous resource to administrativeUnit.
get:
tags:
- contacts.directoryObject
summary: >-
Microsoft Graph Get the item of type microsoft.graph.directoryObject as microsoft.graph.administrativeUnit
operationId: contacts.GetMemberOf.AsAdministrativeUnit
parameters:
- name: ConsistencyLevel
in: header
description: >-
Indicates the requested consistency level. Documentation URL:
https://docs.microsoft.com/graph/aad-advanced-queries
schema:
type: string
examples:
example-1:
description: >-
$search and $count queries require the client to set the
ConsistencyLevel HTTP header to 'eventual'.
value: eventual
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Entity result.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.administrativeUnit'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: orgContact-id
in: path
description: The unique identifier of orgContact
required: true
schema:
type: string
x-ms-docs-key-type: orgContact
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema
# --- truncated at 32 KB (373 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/contacts-openapi-original.yml