Microsoft Graph Directory Objects is the common base resource that represents any identity object stored in Microsoft Entra ID (Azure AD)—including users, groups, devices, service principals, applications, and contacts—and gives them a consistent ID, metadata, and set of relationships.
openapi: 3.1.0
info:
title: Microsoft Graph Directoryobjects
description: Needs a description.
paths:
/directoryObjects:
description: Provides operations to manage the collection of directoryObject entities.
get:
tags:
- directoryObjects.directoryObject
summary: Microsoft Graph Get entities from directoryObjects
operationId: directoryObjects.directoryObject.ListDirectoryObject
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
post:
tags:
- directoryObjects.directoryObject
summary: Microsoft Graph Add new entity to directoryObjects
operationId: directoryObjects.directoryObject.CreateDirectoryObject
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
required: true
responses:
2XX:
description: Created entity
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
/directoryObjects/{directoryObject-id}:
description: Provides operations to manage the collection of directoryObject entities.
get:
tags:
- directoryObjects.directoryObject
summary: Microsoft Graph Get directoryObject
description: Retrieve the properties and relationships of a directoryObject object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-get?view=graph-rest-1.0
operationId: directoryObjects.directoryObject.GetDirectoryObject
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.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- directoryObjects.directoryObject
summary: Microsoft Graph Update entity in directoryObjects
operationId: directoryObjects.directoryObject.UpdateDirectoryObject
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
required: true
responses:
2XX:
description: Success
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
delete:
tags:
- directoryObjects.directoryObject
summary: Microsoft Graph Delete directoryObject
description: >-
Delete a directory object, for example, a group, user, application, or
service principal.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-delete?view=graph-rest-1.0
operationId: directoryObjects.directoryObject.DeleteDirectoryObject
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: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryObjects/{directoryObject-id}/checkMemberGroups:
description: Provides operations to call the checkMemberGroups method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action checkMemberGroups
description: "Check for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object can be of one of the following types:\r\n- user\r\n- group\r\n- service principal\r\n- organizational contact\r\n- device\r\n- directory object This function is transitive. You can check up to a maximum of 20 groups per request. This function supports all groups provisioned in Microsoft Entra ID. Because Microsoft 365 groups cannot contain other groups, membership in a Microsoft 365 group is always direct."
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-checkmembergroups?view=graph-rest-1.0
operationId: directoryObjects.directoryObject.checkMemberGroups
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
groupIds:
type: array
items:
type: string
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
type: string
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
parameters:
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryObjects/{directoryObject-id}/checkMemberObjects:
description: Provides operations to call the checkMemberObjects method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action checkMemberObjects
operationId: directoryObjects.directoryObject.checkMemberObjects
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
ids:
type: array
items:
type: string
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
type: string
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
parameters:
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryObjects/{directoryObject-id}/getMemberGroups:
description: Provides operations to call the getMemberGroups method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action getMemberGroups
description: >-
Return all the group IDs for the groups that the specified user, group,
service principal, organizational contact, device, or directory object
is a member of. This function is transitive. This API returns up to
11,000 group IDs. If more than 11,000 results are available, it returns
a 400 Bad Request error with the DirectoryResultSizeLimitExceeded error
code. If you get the DirectoryResultSizeLimitExceeded error code, use
the List group transitive memberOf API instead.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-getmembergroups?view=graph-rest-1.0
operationId: directoryObjects.directoryObject.getMemberGroups
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
securityEnabledOnly:
type: boolean
default: false
nullable: true
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
type: string
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
parameters:
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryObjects/{directoryObject-id}/getMemberObjects:
description: Provides operations to call the getMemberObjects method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action getMemberObjects
description: "Return all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of:\r\n- user\r\n- group\r\n- service principal\r\n- organizational contact\r\n- device\r\n- directory object This function is transitive. Only users and role-enabled groups can be members of directory roles."
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-getmemberobjects?view=graph-rest-1.0
operationId: directoryObjects.directoryObject.getMemberObjects
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
securityEnabledOnly:
type: boolean
default: false
nullable: true
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
type: string
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
parameters:
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryObjects/{directoryObject-id}/restore:
description: Provides operations to call the restore method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action restore
description: "Restore a recently deleted application, group, servicePrincipal, administrative unit, or user object from deleted items. Restore a recently deleted directory object from deleted items. The following types are supported:\r\n- administrativeUnit\r\n- application\r\n- certificateBasedAuthPki\r\n- certificateAuthorityDetail\r\n- group\r\n- servicePrincipal\r\n- user If an item is accidentally deleted, you can fully restore the item. Additionally, restoring an application doesn't automatically restore the associated service principal automatically. You must call this API to explicitly restore the deleted service principal. A recently deleted item remains available for up to 30 days. After 30 days, the item is permanently deleted."
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directory-deleteditems-restore?view=graph-rest-1.0
operationId: directoryObjects.directoryObject.restore
responses:
2XX:
description: Success
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.directoryObject'
- type: object
nullable: true
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/directoryObjects/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- directoryObjects.directoryObject
summary: Microsoft Graph Get the number of the resource
operationId: directoryObjects.GetCount-3210
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'
/directoryObjects/delta():
description: Provides operations to call the delta method.
get:
tags:
- directoryObjects.directoryObject.Functions
summary: Microsoft Graph Invoke function delta
description: >-
Get newly created, updated, or deleted directory objects without
performing a full read of the entire directoryObject collection. For
more information, see Use delta query to track changes in Microsoft
Graph data for details.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-delta?view=graph-rest-1.0
operationId: directoryObjects.delta
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $orderby
in: query
description: Order items by property values
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: Success
content:
application/json:
schema:
title: Collection of directoryObject
type: object
allOf:
- $ref: '#/components/schemas/BaseDeltaFunctionResponse'
- type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: function
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
/directoryObjects/getAvailableExtensionProperties:
description: Provides operations to call the getAvailableExtensionProperties method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action getAvailableExtensionProperties
description: >-
Return all directory extension definitions that are registered in a
directory, including through multitenant apps. The following entities
support extension properties:
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-getavailableextensionproperties?view=graph-rest-1.0
operationId: directoryObjects.getAvailableExtensionProperties
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
isSyncedFromOnPremises:
type: boolean
default: false
nullable: true
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
title: Collection of extensionProperty
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
$ref: >-
#/components/schemas/microsoft.graph.extensionProperty
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
/directoryObjects/getByIds:
description: Provides operations to call the getByIds method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action getByIds
description: >-
Return the directory objects specified in a list of IDs. Only a subset
of user properties are returned by default in v1.0. Some common uses for
this function are to:
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-getbyids?view=graph-rest-1.0
operationId: directoryObjects.getByIds
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
ids:
type: array
items:
type: string
types:
type: array
items:
type: string
nullable: true
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
title: Collection of directoryObject
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
/directoryObjects/validateProperties:
description: Provides operations to call the validateProperties method.
post:
tags:
- directoryObjects.directoryObject.Actions
summary: Microsoft Graph Invoke action validateProperties
description: "Validate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display name or mail nickname is valid before trying to create a Microsoft 365 group. To validate the properties of an existing group, use the group: validateProperties function. The following policy validations are performed for the display name and mail nickname properties:\r\n1. Validate the prefix and suffix naming policy\r\n2. Validate the custom banned words policy\r\n3. Validate that the mail nickname is unique This API only returns the first validation failure that is encountered. If the properties fail multiple validations, only the first validation failure is returned. However, you can validate both the mail nickname and the display name and receive a collection of validation errors if you're only validating the prefix and suffix naming policy. To learn more about configuring naming policies, see Configure naming policy."
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/directoryobject-validateproperties?view=graph-rest-1.0
operationId: directoryObjects.validateProperties
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
entityType:
type: string
nullable: true
displayName:
type: string
nullable: true
mailNickname:
type: string
nullable: true
onBehalfOfUserId:
pattern: >-
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
type: string
format: uuid
nullable: true
required: true
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
components:
schemas:
microsoft.graph.directoryObject:
allOf:
- $ref: '#/components/schemas/microsoft.graph.entity'
- title: directoryObject
required:
- '@odata.type'
type: object
properties:
deletedDateTime:
pattern: >-
^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
type: string
description: >-
Date and time when this object was deleted. Always null when the
object hasn't been deleted.
format: date-time
nullable: true
'@odata.type':
type: string
discriminator:
propertyName: '@odata.type'
mapping:
'#microsoft.graph.administrativeUnit': '#/components/schemas/microsoft.graph.administrativeUnit'
'#microsoft.graph.application': '#/components/schemas/microsoft.graph.application'
'#microsoft.graph.appRoleAssignment': '#/components/schemas/microsoft.graph.appRoleAssignment'
'#microsoft.graph.certificateAuthorityDetail': '#/components/schemas/microsoft.graph.certificateAuthorityDetail'
'#microsoft.graph.certificateBasedAuthPki': '#/components/schemas/microsoft.graph.certificateBasedAuthPki'
'#microsoft.graph.contract': '#/components/schemas/microsoft.graph.contract'
'#microsoft.graph.device': '#/components/schemas/microsoft.graph.device'
'#microsoft.graph.directoryObjectPartnerReference': >-
#/components/schemas/microsoft.graph.directoryObjectPartnerReference
'#microsoft.graph.directoryRole': '#/components/schemas/microsoft.graph.directoryRole'
'#microsoft.graph.directoryRoleTemplate': '#/components/schemas/microsoft.graph.directoryRoleTemplate'
'#microsoft.graph.endpoint': '#/components/schemas/microsoft.graph.endpoint'
'#microsoft.graph.extensionProperty': '#/components/schemas/microsoft.graph.extensionProperty'
'#microsoft.graph.group': '#/components/schemas/microsoft.graph.group'
'#microsoft.graph.groupSettingTemplate': '#/components/schemas/microsoft.graph.groupSettingTemplate'
'#microsoft.graph.multiTenantOrganizationMember': >-
#/components/schemas/microsoft.graph.multiTenantOrganizationMember
'#microsoft.graph.organization': '#/components/schemas/microsoft.graph.organization'
'#microsoft.graph.orgContact': '#/components/schemas/microsoft.graph.orgContact'
'#microsoft.graph.policyBase': '#/components/schemas/microsoft.graph.policyBase'
'#microsoft.graph.appManagementPolicy': '#/components/schemas/microsoft.graph.appManagementPolicy'
'#microsoft.graph.authorizationPolicy': '#/components/schemas/microsoft.graph.authorizationPolicy'
'#microsoft.graph.crossTenantAccessPolicy': '#/components/schemas/microsoft.graph.crossTenantAccessPolicy'
'#microsoft.graph.identitySecurityDefaultsEnforcementPolicy': >-
#/components/schemas/microsoft.graph.identitySecurityDefaultsEnforcementPolicy
'#microsoft.graph.permissionGrantPolicy': '#/components/schemas/microsoft.graph.permissionGrantPolicy'
'#microsoft.graph.stsPolicy': '#/components/schemas/microsoft.graph.stsPolicy'
'#microsoft.graph.activityBasedTimeoutPolicy': '#/components/schemas/microsoft.graph.activityBasedTimeoutPolicy'
'#microsoft.graph.claimsMappingPolicy': '#/components/schemas/microsoft.graph.claimsMappingPolicy'
'#microsoft.graph.homeRealmDiscoveryPolicy': '#/components/schemas/microsoft.graph.homeRealmDiscoveryPolicy'
'#microsoft.graph.tokenIssuancePolicy': '#/components/schemas/microsoft.graph.tokenIssuancePolicy'
'#microsoft.graph.tokenLifetimePolicy': '#/components/schemas/microsoft.graph.tokenLifetimePolicy'
'#microsoft.graph.tenantAppManagementPolicy': '#/components/schemas/microsoft.graph.tenantAppManagementPolicy'
'#microsoft.graph.resourceSpecificPermissionGrant': >-
#/components/schemas/microsoft.graph.resourceSpecificPermissionGrant
'#microsoft.graph.servicePrincipal': '#/components/schemas/microsoft.graph.servicePrincipal'
'#microsoft.graph.user': '#/components/schemas/microsoft.graph.user'
BaseCollectionPaginationCountResponse:
title: Base collection pagination and count responses
type: object
properties:
'@odata.count':
type: integer
format: int64
nullable: true
'@odata.nextLink':
type: string
nullable: true
BaseDeltaFunctionResponse:
title: Base delta function response
type: object
properties:
'@odata.nextLink':
type: string
nullable: true
'@odata.deltaLink':
type: string
nullable: true
parameters:
top:
name: $top
in: query
description: Show only the first n items
style: form
explode: false
schema:
minimum: 0
type: integer
example: 50
skip:
name: $skip
in: query
description: Skip the first n items
style: form
explode: false
schema:
minimum: 0
type: integer
search:
name: $search
in: query
description: Search items by search phrases
style: form
explode: false
schema:
type: string
filter:
name: $filter
in: query
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/directoryobjects-openapi-original.yml