Entity and complex type reference | Graph API reference

Article
07/25/2016

Applies to: Graph API | Azure Active Directory

This topic discusses the entities and complex types that are exposed by the Graph API.

The Graph API is an OData 3.0 compliant REST API that provides programmatic access to directory objects in Azure Active Directory, such as users, groups, organizational contacts, and applications.

This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see Microsoft Graph REST API v1.0 overview.

Caution

Azure Active Directory (Azure AD) Graph is deprecated and is currently in its retirement path. We recommend that you migrate your apps to Microsoft Graph.

To start migrating your apps, see Migrate your apps from Azure AD Graph to Microsoft Graph.
For the latest announcement, see Important: Azure AD Graph Retirement.

Entity reference

Application Entity

Represents an application. Any application that outsources authentication to Azure AD must be registered in a directory. This involves telling Azure AD about your application, including the URL where it's located, the URL to send replies after authentication, the URI to identify your application, and more. For more information, see Basics of Registering an Application in Azure AD. Inherits from DirectoryObject.

Properties

Declared Properties

Name	Type	Supports	Description
addIns	Collection(AddIn)	POST, GET, PATCH	Defines custom behavior that a consuming service can use to call an app in specific contexts. For example, applications that can render file streams may set the addIns property for its "FileHandler" functionality. This will let services like Office 365 call the application in the context of a document the user is working on. Notes: Requires version 1.6.
appId	Edm.String in version 1.5 Edm.Guid in previous versions	GET ($filter)	The unique identifier for the application.
appRoles	Collection(AppRole)	POST, GET, PATCH	The collection of application roles that an application may declare. These roles can be assigned to users, groups or service principals. Notes: Requires version 1.5, not nullable.
availableToOtherTenants	Edm.Boolean	POST, GET ($filter), PATCH	true if the application is shared with other tenants; otherwise, false.
deletionTimestamp	Edm.DateTime	GET	The time at which the application was deleted from the tenant. If the application has not been deleted, returns null. Deleted applications can be read from the `/deletedApplications` resource collection. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
displayName	Edm.String	POST (Required), GET, PATCH	The display name for the application.
errorUrl	Edm.String	POST, GET, PATCH
groupMembershipClaims	Edm.String	POST, GET, PATCH	A bitmask that configures the "groups" claim issued in a user or OAuth 2.0 access token that the application expects. The bitmask values are: 0: None, 1: Security groups and Azure AD roles, 2: Reserved, and 4: Reserved. Setting the bitmask to 7 will get all of the security groups, distribution groups, and Azure AD directory roles that the signed-in user is a member of. Notes: Requires version 1.5.
homepage	Edm.String	POST, GET, PATCH	The URL to the application's homepage.
identifierUris	Collection(Edm.String)	POST, GET ($filter), PATCH	User-defined URI(s) that uniquely identify a Web application within its Azure AD tenant, or within a verified custom domain (see "Domains" tab in the Azure classic portal) if the application is multi-tenant. The first element is populated from the Web application's "APP ID URI” field if updated via the Azure classic portal (or respective Azure AD PowerShell cmdlet parameter). Additional URIs can be added via the application manifest; see Understanding the Azure AD Application Manifest for details. This collection is also used to populate the Web application's servicePrincipalNames collection. Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
keyCredentials	Collection(KeyCredential)	POST, GET, PATCH	The collection of key credentials associated with the application Notes: not nullable
knownClientApplications	Collection(Edm.Guid)	POST, GET, PATCH	Client applications that are tied to this resource application. Consent to any of the known client applications will result in implicit consent to the resource application through a combined consent dialog (showing the OAuth permission scopes required by the client and the resource). Notes: Requires version 1.5, not nullable.
logoutUrl	Edm.String	POST, GET, PATCH
mainLogo	Edm.Stream	POST, GET, PATCH	The main logo for the application. Notes: not nullable
oauth2AllowImplicitFlow	Edm.Boolean	POST, GET, PATCH	Specifies whether this web application can request OAuth2.0 implicit flow tokens. The default is false. Notes: Requires version 1.5, not nullable.
oauth2AllowUrlPathMatching	Edm.Boolean	POST, GET, PATCH	Specifies whether, as part of OAuth 2.0 token requests, Azure AD will allow path matching of the redirect URI against the application's replyUrls. The default is false. Notes: Requires version 1.5, not nullable.
oauth2Permissions	Collection(OAuth2Permission)	POST, GET, PATCH	The collection of OAuth 2.0 permission scopes that the web API (resource) application exposes to client applications. These permission scopes may be granted to client applications during consent. Notes: Requires version 1.5, not nullable.
oauth2RequiredPostResponse	Edm.Guid	POST, GET, PATCH	Specifies whether, as part of OAuth 2.0 token requests, Azure AD will allow POST requests, as opposed to GET requests. The default is false, which specifies that only GET requests will be allowed. Notes: Requires version 1.5, not nullable.
objectId	Edm.Guid	GET	The unique identifier for the application. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique
objectType	Edm.String	GET	A string that identifies the object type. For applications the value is always "Application". Inherited from DirectoryObject.
optionalClaims	OptionalClaims	POST, GET, PATCH	The optional claims returned in the token by the security token service for this specific app.
passwordCredentials	Collection(PasswordCredential)	POST, GET, PATCH	The collection of password credentials associated with the application. Notes: not nullable
publicClient	Edm.Boolean	POST, GET	Specifies whether this application is a public client (such as an installed application running on a mobile device). Default is false.
recordConsentConditions	Edm.String	GET	Do not use. May be removed in future versions Notes: Requires version 1.6.
replyUrls	Collection(Edm.String)	POST, GET, PATCH	Specifies the URLs that user tokens are sent to for sign in, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to. Notes: not nullable
requiredResourceAccess	Collection(RequiredResourceAccess)	POST, GET, PATCH	Specifies resources that this application requires access to and the set of OAuth permission scopes and application roles that it needs under each of those resources. This pre-configuration of required resource access drives the consent experience. Notes: Requires version 1.5, not nullable.
samlMetadataUrl	Edm.String	POST, GET, PATCH	The URL to the SAML metadata for the application.

Navigation Properties

Name	To	Multiplicity (From/To)	Description
extensionProperties	ExtensionProperty	/	The extension properties associated with the application. Requires 1.5 or newer.
owners	DirectoryObject	/	Directory objects that are owners of the application. The owners are a set of non-admin users who are allowed to modify this object. Requires version 2013-11-08 or newer. Inherited from DirectoryObject.
policies	Policy	/	Policies assigned to the application.
serviceEndpoints	ServiceEndpoint	1/*	Service endpoints available for discovery. For more information, see the ServiceEndpoint topic. HTTP Methods: POST, GET, and DELETE. Requires version 1.6 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on applications (HTTP methods are listed in parentheses):

Create (POST)
Read (GET)
Update (PATCH)
Delete (DELETE)

The following operations are supported on application navigation properties. Not all operations may be supported on every navigation property.

Read (GET)
Update (POST)
Delete (DELETE)

The following action may be called on applications.

restore to restore a deleted application. Requires version 1.5 or newer.

AppRoleAssignment Entity

Used to record when a user or group is assigned to an application. In this case, the role assignment will result in an application tile showing up on the user's app access panel. This entity may also be used to grant another application (modeled as a service principal) access to a resource application in a particular role. You can create, read, update, and delete role assignments. Inherits from DirectoryObject.

Important: Introduced in version 1.5.

Properties

Declared Properties

Name	Type	Supports	Description
creationTimestamp	Edm.DateTime	GET	The time when the grant was created.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for app role assignment and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
id	Edm.Guid	POST (Required), GET, PATCH	The role id that was assigned to the principal. This role must be declared by the target resource application resourceId in its appRoles property. Where the resource does not declare any permissions, a default id (zero GUID) must be specified. Notes: not nullable.
principalDisplayName	Edm.String	GET	The display name of the principal that was granted the access.
objectId	Edm.String	GET	The unique identifier for the application role assignment. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For application role assignments the value is always "AppRoleAssignment". Inherited from DirectoryObject.
principalId	Edm.Guid	POST (Required), GET, PATCH	The unique identifier (objectId) for the principal being granted the access. Notes: required.
principalType	Edm.String	GET	The type of principal. This can either be "User", "Group" or "ServicePrincipal".
resourceDisplayName	Edm.String	GET	The display name of the resource to which the assignment was made.
resourceId	Edm.Guid	POST (Required), GET, PATCH	The unique identifier (objectId) for the target resource (service principal) for which the assignment was made.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Contact Entity

Represents an organizational contact. Inherits from DirectoryObject.

Organizational contacts represent users that are not in your company directory. They are mail-enabled entities and typically represent individuals who are external to your company or organization. Organizational contacts cannot be authenticated using Azure AD, nor can they be assigned licenses.

Organizational contacts can be created in your tenant through syncing with an on-premises directory using Azure AD Connect, or they can be created through one of the Exchange Online management portals or the Exchange Online PowerShell cmdlets. For more information about Azure AD Connect, see Integrating your on-premises identities with Azure Active Directory. For more information about Exchange Online management tools, see Exchange Online Setup and Administration.

You cannot create organizational contacts with the Graph API. You can, however, update and delete contacts that are not currently synced from an on-premises directory; that is, contacts for which the dirSyncEnabled property is null or false. You cannot update or delete contacts for which the dirSyncEnabled property is true.

Note: Organizational contacts are directory entities, which represent external users. They should not be confused with O365 Outlook Personal contacts.

Properties

Declared Properties

Name	Type	Supports	Description
city	Edm.String	GET ($filter), PATCH	The city in which the contact is located.
country	Edm.String	GET ($filter), PATCH	The country/region in which the contact is located.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for contacts and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
department	Edm.String	GET ($filter), PATCH	The name for the department in which the contact works.
dirSyncEnabled	Edm.Boolean	GET ($filter)	true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayName	Edm.String	GET ($filter), PATCH	The display name for the contact.
facsimileTelephoneNumber	Edm.String	GET, PATCH	The telephone number of the contact's business fax machine.
givenName	Edm.String	GET ($filter), PATCH	The given name (first name) of the contact.
jobTitle	Edm.String	GET ($filter), PATCH	The contact's job title.
lastDirSyncTime	Edm.DateTime	GET ($filter)	Indicates the last time at which the object was synced with the on-premises directory.
mail	Edm.String	GET ($filter)	The SMTP address for the contact, for example, "[email protected]".
mailNickname	Edm.String	GET ($filter), PATCH	The mail alias for the contact.
mobile	Edm.String	GET, PATCH	The primary cellular telephone number for the contact.
objectId	Edm.String	GET	The unique identifier for the contact. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For contacts the value is always "Contact". Inherited from DirectoryObject.
physicalDeliveryOfficeName	Edm.String	GET, PATCH	The office location in the contact's place of business.
postalCode	Edm.String	GET, PATCH	The postal code for the contact's postal address. The postal code is specific to the contact's country/region. In the United States of America, this attribute contains the ZIP code.
provisioningErrors	Collection(ProvisioningError)	GET, PATCH	A collection of error details that are preventing this contact from being provisioned successfully. Note: not nullable
proxyAddresses	Collection(Edm.String)	GET ($filter)	Note: unique, not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
sipProxyAddress	Edm.String	GET	Specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the contact. Notes: Requires version 1.5 or newer.
state	Edm.String	GET ($filter), PATCH	The state or province in the contact's address.
streetAddress	Edm.String	GET, PATCH	The street address of the contact's place of business.
surname	Edm.String	GET ($filter), PATCH	The contact's surname (family name or last name).
telephoneNumber	Edm.String	GET, PATCH	The primary telephone number of the contact's place of business.
thumbnailPhoto	Edm.Stream	GET, PATCH	A thumbnail photo to be displayed for the contact. Note: not nullable

Navigation Properties

Name	To	Multiplicity (From/To)	Description
manager	DirectoryObject (Only User and Contact objects are supported.)	*/0..1	The user or contact that is this contact's manager. Inherited from DirectoryObject. HTTP Methods: GET, PUT, DELETE
directReports	DirectoryObject (Only User and Contact objects are supported.)	/	The contact's direct reports. (The users and contacts that have their manager property set to this contact.) Inherited from DirectoryObject. HTTP Methods: GET
memberOf	DirectoryObject (Only Group objects are supported.)	/	Groups that this contact is a member of. Inherited from DirectoryObject. HTTP Methods: GET

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on contacts (the HTTP method used for each is in parentheses):

Read (GET)
Update (PATCH): only contacts that are not synced from an on-premises directory (dirSyncEnabled is null or false).
Delete (DELETE)

The following operations are supported on contact navigation properties; not all operations may be supported on every navigation property.

Read (GET)
Update (PUT): manager property, only on contacts that are not synced from an on-premises directory (dirSyncEnabled is null or false).
Delete (DELETE): manager property, only on contacts that are not synced from an on-premises directory (dirSyncEnabled is null or false).

The following actions and functions may be called on contacts:

checkMemberGroups to check a contact’s membership in a list of groups. The check is transitive.
getMemberGroups to return a list of the groups that a contact is a member of. The check is transitive.
isMemberOf to check whether a contact is a member of a specified group. The check is transitive.

Remarks

Contacts are mail-enabled entities and cannot be created by using the Graph API. They can be updated; however, update is only supported for contacts with the dirSyncEnabled property set null or false. Contacts can be deleted.

Contract Entity

Exists in Partner Tenants only. Partner Tenants are Azure AD tenants that belong to Microsoft Partners who are either part of Office 365 Syndication, Microsoft Cloud Solution Provider, or Microsoft Advisor partner programs. Represents an existing partnership that the Partner Tenant has with a Customer Tenant. Read-only. Inherits from DirectoryObject.

Important: Introduced in version 1.5.

Properties

Declared Properties

Name	Type	Supports	Description
contractType	Edm.String	GET	Type of the contract. Possible values are: "SyndicationPartner", which indicates a partner that exclusively resells and manages O365 and Intune for this customer. They resell and support their customers. "BreadthPartner", which indicates that the partner has the ability to provide administrative support for this customer. However the partner is not allowed to resell to the customer. "ResellerPartner", which indicates a partner that is similar to a syndication partner, except that it doesn’t have exclusive access to a tenant. In the syndication case the customer cannot buy additional direct subscriptions from Microsoft or from other partners.
customerContextId	Edm.Guid	GET ($filter)	The unique identifier for the customer tenant referenced by this partnership. Corresponds to the objectId property of the customer tenant's TenantDetail object.
defaultDomainName	Edm.String	GET ($filter)	A copy of the customer tenant's default domain name. The copy is made when the partnership with the customer is established. It is not automatically updated if the customer tenant's default domain name changes.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for contracts and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
displayName	Edm.String	GET ($filter)	A copy of the customer tenant's display name. The copy is made when the partnership with the customer is established. It is not automatically updated if the customer tenant's display name changes.
objectType	Edm.String	GET	A string that identifies the object type. The value is always “Contract”. Inherited from DirectoryObject.
objectId	Edm.String	GET	The unique identifier for the partnership. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on contracts (the HTTP method used for each is in parentheses):

Read (GET)

Device Entity

Represents a device registered in the directory. Inherits from DirectoryObject.

Properties

Declared Properties

Name	Type	Supports	Description
accountEnabled	Edm.Boolean	POST (required), GET ($filter), PATCH	true if the account is enabled; otherwise, false. Default is true.
alternativeSecurityIds	Collection(AlternativeSecurityId)	POST (required), GET ($filter), PATCH	Notes: For internal use only. Not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
approximateLastLogonTimeStamp	Edm.DateTime	POST, GET, PATCH	The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'. Read-only.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for devices and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
deviceId	Edm.Guid	POST (Required), GET ($filter), PATCH	Unique identifier set by Azure Device Registration Service at the time of registration.
deviceObjectVersion	Edm.Int32	POST, GET, PATCH	For internal use only.
deviceOSType	Edm.String	POST (Required), GET, PATCH	The type of operating system on the device. Required.
deviceOSVersion	Edm.String	POST (Required), GET, PATCH	The version of the operating system on the device. Required.
devicePhysicalIds	Collection(Edm.String)	POST, GET ($filter), PATCH	Notes: For internal use. Not nullable.
dirSyncEnabled	Edm.Boolean	GET ($filter)	true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayName	Edm.String	POST (Required), GET ($filter), PATCH	The display name for the device. Required.
isCompliant	Edm.Boolean	POST, GET, PATCH	true if the device complies with Mobile Device Management (MDM) policies; otherwise, false. This can only be updated by Intune for any device OS type or by an approved MDM app for Windows OS devices.
IsManaged	Edm.Boolean	POST, GET, PATCH	true if the device is managed by a Mobile Device Management (MDM) app such as Intune; otherwise, false. This can only be updated by Intune for any device OS type or by an approved MDM app for Windows OS devices.
lastDirSyncTime	Edm.DateTime	GET ($filter)	The last time at which the object was synced with the on-premises directory. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'. Read-only.
objectId	Edm.String	GET	The unique identifier for the device. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique, read-only
objectType	Edm.String	GET	A string that identifies the object type. For devices the value is always "Device". Inherited from DirectoryObject

Navigation Properties

Name	To	Multiplicity (From/To)	Description
registeredOwners	User	/	Users that are registered owners of the device.
registeredUsers	User	/	Users that are registered users of the device.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on devices (HTTP methods are listed in parentheses):

Create (CREATE)
Read (GET)
Update (PATCH)
Delete (DELETE)

The following operations are supported on device navigation properties. Not all operations may be supported on every navigation property.

Read (GET)
Update (PUT)
Delete (DELETE)

No functions or actions are supported on devices.

DirectoryLinkChange Entity

A DirectoryLinkChange object is returned in the result set of a differential query to indicate that a property of a contact, a user, or a group that is represented by a link has changed since the last differential query. The DirectoryLinkChange object will represent a change to a user’s or contact’s manager property or a change to a group’s members property. For more information about differential queries, see Differential Query. Inherits from DirectoryObject.

Properties

Declared Properties

Name	Type	Supports	Description
associationType	Edm.String	GET	A string that identifies the association type to which the change applies. The value is either "Member" or "Manager".
deletionTimestamp	Edm.DateTime	GET	This property is not valid for directory link change objects and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
objectId	Edm.String	GET	The unique identifier for the directory link change object. For DirectoryLinkChange objects, the value is always 00000000-0000-0000-0000-000000000000. Inherited from DirectoryObject. Note: key immutable, not nullable, unique
objectType	Edm.String	GET	A string that identifies the object type. For DirectoryLinkChange objects, the value is always "DirectoryLinkChange". DirectoryObject
sourceObjectId	Edm.String	GET	The object ID for the source object; for example, "7373b0af-d462-406e-ad26-f2bc96d823d8".
sourceObjectType	Edm.String	GET	A string that identifies the source object type; this will be one of the following: "Group", "User", or "Contact".
sourceObjectUri	Edm.String	GET	The URI for the source object; for example, `"https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8"`.
targetObjectId	Edm.String	GET	The object ID for the target object; for example, "dca803ab-bf26-4753-bf20-e1c56a9c34e2".
targetObjectType	Edm.String	GET	A string that identifies the source object type; this will be one of the following: "Group", "User", or "Contact".
targetObjectUri	Edm.String	GET	The URI for the target object; for example, `"https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"`.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

DirectoryObject Entity

Represents an Azure Active Directory object. The DirectoryObject type is the base type for most of the other directory entity types.

Properties

Declared Properties

Name	Type	Supports	Description
deletionTimestamp	Edm.DateTime	GET	The time at which the directory object was deleted. It only applies to those directory objects which can be restored. Currently it is only supported for deleted Application objects; all other entities return null for this property. Notes: Requires version 1.5 or newer.
objectId	Edm.String	GET	A Guid that is the unique identifier for the object; for example, 12345678-9abc-def0-1234-56789abcde. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For example, for groups the value is always "Group".

Navigation Properties

Name	To	Multiplicity (From/To)	Description
createdObjects	DirectoryObject	/	The directory objects that were created by the current object. Read only. Requires version 2013-11-08 or newer.
createdOnBehalfOf	DirectoryObject	*/0..1	The directory object that that this object was created on behalf of. Read only. Requires version 2013-11-08 or newer.
manager	DirectoryObject	*/0..1	This object's manager. Valid on users and contacts. Returns a user or a contact.
directReports	DirectoryObject	/	Users and contacts that report to this object. Valid on users and contacts. Returns users and contacts. Read only.
members	DirectoryObject	/	Objects that are members of this object. Valid on groups and roles. On groups, returns contacts, users, and groups. On roles, returns users and service principals.
memberOf	DirectoryObject	/	Objects that this object is a member of. Valid on contacts, groups, service principals, and users. On contacts, returns groups. On groups, returns groups. On users, returns groups and roles. On service principals, returns roles. Read only. The property is not transitive. For example, if User A is a member of Group B and Group B is a member of Group C, the memberOf property on User A will not return Group C.
ownedObjects	DirectoryObject	/	The directory objects that are owned by the current object. Read only. Requires version 2013-11-08 or newer.
owners	DirectoryObject	/	The directory objects that are owners of the current object. The owners are a set of non-admin users who are allowed to modify this object. Requires version 2013-11-08 or newer.

Note: Not all navigation properties are necessarily valid on the entity types that inherit from DirectoryObject. If a request for a property that is not valid for a specific entity is sent, a 400 Bad Request response is returned. For more information about which navigation properties are valid on specific entities, consult the documentation for that entity type.

Supported Operations

The full set of operations that are supported on directory objects are the following (the HTTP method used for each is in parentheses): Create (POST), Read (GET), Update (PATCH), and Delete (DELETE). However, not all of these operations are supported on every entity type. The declared properties of directory object are read-only; they cannot be specified in create or update operations.

The potential set of operations supported on each of the navigation properties are:

createdObjects: Read (GET).
createdOnBehalfOf: Read (GET).
manager: Read (GET), Update (PUT), and Delete (DELETE).
directReports: Read (GET).
members: Read (GET), Update (POST), and Delete (DELETE).
memberOf: Read (GET).
ownedObjects: Read (GET).
owners: Read (GET), Update (POST), and Delete (DELETE).

Not all navigation properties are necessarily supported on every entity type, nor are the set of potential operations for a navigation property necessarily supported on every entity type.

Whether a particular directory object supports a particular action or function, depends on the type of the directory object (the objectType property). For information about which object types support which functions or actions, see the documentation of the particular object, for example, user, group, etc., or of a particular function.

Consult the documentation for the specific entity type for information about operations supported for an entity.

DirectoryRole Entity

Represents an Azure AD directory role. Azure AD directory roles are also known as administrator roles. For more information about directory (administrator) roles, see Assigning administrator roles in Azure AD.

With the Graph API, you can assign users and service principals to directory roles to grant them the permissions of the target role. You can read directory role objects and update the members navigation property of directory roles, but you cannot delete directory roles or update their declared properties. Inherits from DirectoryObject.

To read a directory role or update its members, it must first be activated in the tenant. In versions prior to 1.5, all directory roles are activated by default. Beginning with version 1.5, only the Company Administrators directory role is activated by default. To activate other available directory roles you send a POST request with the objectId of the DirectoryRoleTemplate on which the directory role is based. See Supported Operations and Remarks for more information.

Important: Beginning with version 1.5, the Role entity type is renamed to DirectoryRole.

Properties

Declared Properties

Name	Type	Supports	Description
deletionTimestamp	Edm.DateTime	GET	This property is not valid for directory roles and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
description	Edm.String	GET	The description for the directory role.
displayName	Edm.String	GET	The display name for the directory role.
isSystem	Edm.Boolean	GET	true if the role is a system role; otherwise, false.
objectId	Edm.String	GET	The unique identifier for the directory role. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For directory roles the value is always "DirectoryRole". Inherited from DirectoryObject. Note: In versions prior to 1.5, the value will be "Role".
roleDisabled	Edm.Boolean	GET	true if the directory role is disabled; otherwise, false.
roleTemplateId	String	POST (Required), GET	The objectId of the DirectoryRoleTemplate that this role is based on. Notes: In versions prior to version 1.5, the property is read only. In version 1.5 and later, the property must be specified when activating a directory role in a tenant with a POST operation. After the directory role has been activated, the property is read only.

Navigation Properties

Name	To	Multiplicity (From/To)	Description
members	DirectoryObject (User and ServicePrincipal are supported.)	/	Users and service principals that are members of this directory role. Inherited from DirectoryObject. HTTP Methods: GET, POST, DELETE

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on directory roles (the HTTP method used for each is in parentheses):

Create (POST): Supported in version 1.5 and later. Activates a directory role in the tenant using the DirectoryRoleTemplate specified by the roleTemplateId property in the request. After the directory role is activated, you can add and delete users and service principals from the role.
Read (GET)

The following operations are supported on directory role navigation properties:

Read (GET)
Update (POST)
Delete (DELETE)

No functions or actions may be called on directory roles; however, you can call getMemberObjects on a User or ServicePrincipal to determine its directory role memberships. Note that for users, this function also returns its direct and transitive group memberships.

Remarks

In version 1.5 and later, only the Company Adminstrators role is activated (and visible) in a tenant by default. Use the Create (POST) operation to activate additional directory roles. The operation specifies the roleTemplateId property in the request. This property contains the objectId of the DirectoryRoleTemplate instance that corresponds to the role you want to activate. After the directory role is activated you can add and delete users and service principals from it with the Graph API. In versions prior to 1.5, all directory roles (represented by the Role entity) are activated by default and the Create (POST) operation is not supported.
Directory roles cannot be deleted using the Graph API. Updates are supported on the members navigation property only. Both add and remove are supported on this property.
Query filter expressions are not supported on directory roles.

DirectoryRoleTemplate Entity

Represents a directory role template. A directory role template specifies the property values of a directory role (DirectoryRole). There is an associated directory role template object for each of the directory roles that may be activated in a tenant. Inherits from DirectoryObject.

To read a directory role or update its members, it must first be activated in the tenant. In versions prior to 1.5, all directory roles are activated by default. Beginning with version 1.5, only the Company Administrators directory role is activated by default. To activate other available directory roles you send a POST request to the /directoryRoles endpoint with the objectId of the directory role template on which the directory role is based specified in the roleTemplateId parameter of the request. For more information, see DirectoryRole.

Note: A directory role template is exposed for the Users directory role. The Users directory role is implicit and is not visible to directory clients. Every User in the tenant is assigned to this role by the infrastructure. The role is already activated. Do not use this template.

Important: Introduced in version 1.5.

Properties

Declared Properties

Name	Type	Supports	Description
description	Edm.String	GET	The description to set for the directory role.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for directory role templates and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
displayName	Edm.String	GET	The display name to set for the directory role.
objectId	Edm.String	GET	The unique identifier for the template. Inherited from DirectoryObject. In version 1.5 and later, you specify the objectId of the directory role template for the roleTemplateId property in the POST request activate a DirectoryRole in a tenant. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For role templates the value is always "RoleTemplate". Inherited from DirectoryObject.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on directory role templates (HTTP methods are listed in parentheses):

read (GET)

Domain Entity

Represents a domain associated with the tenant.

Important: Only available in version beta.

Properties

Declared Properties

Name	Type	Supports	Description
authenticationType	Edm.String	GET	Indicates what authentication type the domain is configured for. The value is either "Managed" or "Federated".
availabilityStatus	Edm.String	GET	This property is always null except when the verify action is used. When the verify action is used, a Domain entity is returned in the response. The availabilityStatus property of the Domain entity in the response is either "AvailableImmediately" or "EmailVerifiedDomainTakeoverScheduled".
isAdminManaged	Edm.Boolean	GET	false, if the DNS record management of the domain has been delegated to Office 365. Otherwise, true. Notes: not nullable
isDefault	Edm.Boolean	GET, PATCH	Indicates whether or not this is the default domain that is used for user creation. There is only one default domain per company. Notes: not nullable
isInitial	Edm.Boolean	GET	Indicates whether or not this is the initial domain created by Microsoft Online Services (companyname.onmicrosoft.com). There is only one initial domain per company. Notes: not nullable
isRoot	Edm.Boolean	GET	For subdomains, this represents the root domain. Only root domains need to be verified, and all subdomains will be automatically verified. Notes: not nullable
isVerified	Edm.Boolean	GET	Indicates whether this domain has completed domain ownership verification or not. Notes: not nullable
name	Edm.String	POST (Required), GET ($filter)	The fully qualified name of the domain. Notes: key, immutable, not nullable, unique
supportedServices	Collection(Edm.String)	GET, PATCH	The capabilities assigned to the domain. Can include 0, 1 or more of following values: "Email" "Sharepoint" "EmailInternalRelayOnly" "OfficeCommunicationsOnline" "SharePointDefaultDomain" "FullRedelegation" "SharePointPublic" "OrgIdAuthentication" "Yammer" "Intune" Most of these values are read-only. The values which you can add/remove using Graph API includes: "Email" "OfficeCommunicationsOnline" "Yammer" Notes: not nullable

Navigation Properties

Name	To	Multiplicity (From/To)	Description
serviceConfigurationRecords	DomainDnsRecord	/	DNS records that the customer has to add to the DNS zone file of the domain before the domain can be used by Microsoft Online services.
verificationDnsRecords	DomainDnsRecord	/	DNS records that the customer has to add to the DNS zone file of the domain before the customer can complete domain ownership verification with Azure AD.

DomainDnsRecord Entity

For each domain in the tenant, you may be required to add DNS record(s) to the DNS zone file of the domain before the domain can be used by Microsoft Online Services. The DomainDnsRecord entity is used to present such DNS records. Base entity for DomainDnsCnameRecord, DomainDnsMxRecord, DomainDnsSrvRecord and DomainDnsSrvRecord entities.

Important: Only available in version beta.

Properties

Declared Properties

Name	Type	Supports	Description
dnsRecordId	Edm.Guid	GET	Unique identifier assigned to this entity. Notes: not nullable
isOptional	Edm.Boolean	GET	Indicates whether this record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain. Notes: not nullable
label	Edm.String	GET	Indicates the value to use when configuring the name of the DNS record at the DNS host.
recordType	Edm.String	GET	Indicates what type of DNS record this entity represents. The value can be one of the following: "CName" "Mx" "Srv" "Txt" Notes: key
supportedService	Edm.String	GET	Indicates which Microsoft Online Service or feature has a dependency on this DNS record. Can be one of the following values: null "Email" "Sharepoint" "EmailInternalRelayOnly" "OfficeCommunicationsOnline" "SharePointDefaultDomain" "FullRedelegation" "SharePointPublic" "OrgIdAuthentication" "Yammer" "Intune"
ttl	Edm.Int32	GET	Indicates the value to use when configuring the time-to-live (ttl) property of the DNS record at the DNS host. Notes: not nullable

DomainDnsCnameRecord Entity

Represents a CNAME record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Important: Only available in version beta.

Properties

Declared Properties

Name	Type	Supports	Description
canonicalName	Edm.String	GET	Indicates the value to use when configuring the canonical name of the CNAME record at the DNS host.
dnsRecordId	Edm.Guid	GET	Unique identifier assigned to this entity. Notes: not nullable
isOptional	Edm.Boolean	GET	Indicates whether this CNAME record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain. Notes: not nullable
label	Edm.String	GET	Indicates the value to use when configuring the name of the CNAME record at the DNS host.
recordType	Edm.String	GET	Indicates what type of DNS record this entity represents. The value is always "CName". Notes: key
supportedService	Edm.String	GET	Indicates which Microsoft Online Service or feature has a dependency on this CNAME record. Can be one of the following values: null "Email" "Sharepoint" "EmailInternalRelayOnly" "OfficeCommunicationsOnline" "SharePointDefaultDomain" "FullRedelegation" "SharePointPublic" "OrgIdAuthentication" "Yammer" "Intune"
ttl	Edm.Int32	GET	Indicates the value to use when configuring the time-to-live (ttl) property of the CNAME record at the DNS host. Notes: not nullable

DomainDnsMxRecord Entity

Represents an MX record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Important: Only available in version beta.

Properties

Declared Properties

Name	Type	Supports	Description
dnsRecordId	Edm.Guid	GET	Unique identifier assigned to this entity. Notes: not nullable
isOptional	Edm.Boolean	GET	Indicates whether this MX record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain. Notes: not nullable
label	Edm.String	GET	Value to use when configuring the Alias/Host/Name property of the MX record at the DNS host.
mailExchange	Edm.String	GET	Value to use when configuring the Answer/Destination/Value of the MX record at the DNS host.
recordType	Edm.String	GET	Indicates what type of DNS record this entity represents. The value is always "Mx". Notes: key
preference	Edm.Int32	GET	Value to use when configuring the Preference/Priority property of the MX record at the DNS host.
supportedService	Edm.String	GET	Indicates which Microsoft Online Service or feature has a dependency on this CNAME record. Can be one of the following values: null "Email" "Sharepoint" "EmailInternalRelayOnly" "OfficeCommunicationsOnline" "SharePointDefaultDomain" "FullRedelegation" "SharePointPublic" "OrgIdAuthentication" "Yammer" "Intune"
ttl	Edm.Int32	GET	Value to use when configuring the time-to-live (ttl) property of the MX record at the DNS host. Notes: not nullable

DomainDnsSrvRecord Entity

Represents an SRV record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Important: Only available in version beta.

Properties

Declared Properties

Name	Type	Supports	Description
dnsRecordId	Edm.Guid	GET	Unique identifier assigned to this entity. Notes: not nullable
isOptional	Edm.Boolean	GET	Indicates whether this SRV record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain. Notes: not nullable
label	Edm.String	GET	Value to use when configuring the Name property of the SRV record at the DNS host.
nameTarget	Edm.String	GET	Value to use when configuring the Target property of the SRV record at the DNS host.
port	Edm.Int32	GET	Value to use when configuring the Port property of the SRV record at the DNS host.
priority	Edm.Int32	GET	Value to use when configuring the Priority property of the SRV record at the DNS host.
protocol	Edm.String	GET	Value to use when configuring the Protocol property of the SRV record at the DNS host.
recordType	Edm.String	GET	Indicates what type of DNS record this entity represents. The value is always "Srv". Notes: key
Service	Edm.String	GET	Value to use when configuring the Service property of the SRV record at the DNS host.
supportedService	Edm.String	GET	Indicates which Microsoft Online Service or feature has a dependency on this SRV record. Can be one of the following values: null "Email" "Sharepoint" "EmailInternalRelayOnly" "OfficeCommunicationsOnline" "SharePointDefaultDomain" "FullRedelegation" "SharePointPublic" "OrgIdAuthentication" "Yammer" "Intune"
ttl	Edm.Int32	GET	Value to use when configuring the Time-To-Live property of the SRV record at the DNS host. Notes: not nullable
weight	Edm.Int32	GET	Value to use when configuring the Weight property of the SRV record at the DNS host.

DomainDnsTxtRecord Entity

Represents a TXT record which needs to be added to the DNS zone file of a particular domain in the tenant. Inherited from DomainDnsRecord entity.

Properties

Declared Properties

Name	Type	Supports	Description
dnsRecordId	Edm.Guid	GET	Unique identifier assigned to this entity. Notes: not nullable
isOptional	Edm.Boolean	GET	Indicates whether this MX record must be configured by the customer at the DNS host for Microsoft Online Services to operate correctly with the domain. Notes: not nullable
label	Edm.String	GET	Value to use when configuring the Alias/Host/Name property of the MX record at the DNS host.
recordType	Edm.String	GET	Indicates what type of DNS record this entity represents. The value is always "Mx". Notes: key
supportedService	Edm.String	GET	Indicates which Microsoft Online Service or feature has a dependency on this CNAME record. Can be one of the following values: null "Email" "Sharepoint" "EmailInternalRelayOnly" "OfficeCommunicationsOnline" "SharePointDefaultDomain" "FullRedelegation" "SharePointPublic" "OrgIdAuthentication" "Yammer" "Intune"
text	Edm.String	GET
ttl	Edm.Int32	GET	Value (in seconds) to use when configuring the Time-To-Live property of the TXT record at the DNS host. Notes: not nullable

DomainDnsUnavailableRecord Entity

Inherited from DomainDnsRecord entity. When you query for the navigation property serviceConfigurationRecords for a Domain entity, you may get back one or more DomainDnsCnameRecord, DomainDnsMxRecord, DomainDnsSrvRecord and/or DomainDnsTxtRecord entities. These entities indicate what DNS records you must add to the zone file of the domain, before the domain can be used by Microsoft Online Services. When it is not possible to generate such entities, a DomainDnsUnavailableRecord Entity is returned instead.

Properties

Declared Properties

Name	Type	Supports	Description
description	Edm.String	GET	Provides the reason why the DomainDnsUnavailableRecord entity is returned.

ExtensionProperty Entity

Allows an application to define and use a set of additional properties that can be added to directory objects (users, groups, tenant details, devices, applications, and service principals) without the application requiring an external data store. For more information about extension properties, see Directory Schema Extensions. Inherits from DirectoryObject.

Important: ExtensionProperty is introduced in version 1.5.

Properties

Declared Properties

Name	Type	Supports	Description
appDisplayName	Edm.String	GET
dataType	Edm.String	POST, GET, PATCH	Specifies the type of the directory extension property being added. Supported types are: Integer, LargeInteger, DateTime (must be specified in ISO 8601 - DateTime is stored in UTC), Binary, Boolean, and String.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for extension properties and always returns null. Inherited from DirectoryObject.
objectId	Edm.String	GET	The unique identifier for the extension property. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For extension properties the value is always "ExtensionProperty". Inherited from DirectoryObject.
name	Edm.String	POST, GET, PATCH	Specifies the display name for the directory extension property. Notes: not nullable.
isSyncedFromOnPremises	Edm.Boolean	GET	Indicates whether the extension property is synced from the on premises directory. Notes: not nullable.
targetObjects	Collection(Edm.String)	POST, GET, PATCH	The directory objects to which the directory extension property is being added. Supported directory entities that can be extended are: "User", "Group", "TenantDetail", "Device", and "Application" Notes: not nullable.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Group Entity

Represents an Azure Active Directory Group. Inherits from DirectoryObject.

Properties

Declared Properties

Name	Type	Supports	Description
deletionTimestamp	Edm.DateTime	GET	This property is not valid for groups and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
description	Edm.String	POST, GET, PATCH	An optional description for the group.
dirSyncEnabled	Edm.Boolean	GET ($filter)	true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayName	Edm.String	POST (Required), GET ($filter), PATCH	The display name for the group. This property is required when a group is created and it cannot be cleared during updates.
lastDirSyncTime	Edm.DateTime	GET ($filter)	Indicates the last time at which the object was synced with the on-premises directory.
mail	Edm.String	GET ($filter)	The SMTP address for the group, for example, "[email protected]".
mailEnabled	Edm.Boolean	POST (Required), GET, PATCH	Specifies whether the group is mail-enabled. If the securityEnabled property is also true, the group is a mail-enabled security group; otherwise, the group is a Microsoft Exchange distribution group. Only (pure) security groups can be created using Azure AD Graph. For this reason, the property must be set false when creating a group and it cannot be updated using Azure AD Graph.
mailNickname	Edm.String	POST (Required), GET ($filter), PATCH	The mail alias for the group. This property must be specified when a group is created.
objectId	Edm.String	GET	The unique identifier for the group. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For groups the value is always "Group". Inherited from DirectoryObject.
onPremisesSecurityIdentifier	String	GET	Contains the on-premises security identifier (SID) for the group that was synchronized from on-premises to the cloud. Notes: Requires version 1.5 or newer.
provisioningErrors	Collection(ProvisioningError)	GET	A collection of error details that are preventing this group from being provisioned successfully. Notes: not nullable.
preferredLanguage	String	POST, GET, PATCH	The preferred language for an Office 365 group. Should follow ISO 639-1 Code; for example "en-US".
proxyAddresses	Collection(Edm.String)	GET ($filter)	Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
securityEnabled	Edm.Boolean	POST (Required), GET ($filter), PATCH	Specifies whether the group is a security group. If the mailEnabled property is also true, the group is a mail-enabled security group; otherwise it is a security group. Only (pure) security groups can be created using Azure AD Graph. For this reason, the property must be set true when creating a group.
theme	String	POST, GET, PATCH	Specifies an Office 365 group's color theme. Possible values are Teal, Purple, Green, Blue, Pink, Orange or Red.

Navigation Properties

Name	To	To Multiplicity	Description
members	DirectoryObject (Only Contact, Group, ServicePrincipal, and User objects are supported)	/	Users, contacts, groups, and service principals that are members of this group. Inherited from DirectoryObject. HTTP Methods: GET (supported for all groups), POST (supported for security groups and mail-enabled security groups), DELETE (supported only for security groups)
memberOf	DirectoryObject (Only Group objects are supported)	/	Groups that this group is a member of. Inherited from DirectoryObject. HTTP Methods: GET (supported for all groups)
owners	DirectoryObject	/	The owners of the group. The owners are a set of non-admin users who are allowed to modify this object. Requires version 2013-11-08 or newer. Inherited from DirectoryObject. HTTP Methods: GET (supported for all groups), POST (supported for security groups and mail-enabled security groups), DELETE (supported only for security groups)
appRoleAssignments	DirectoryObject	/	Contains the set of applications that a group is assigned to. Notes: Requires version 1.5 or newer.
extensionProperties	DirectoryObject	/	Contains the extension properties associated with the application. Notes: Requires version 1.5 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on users (the HTTP method used for each is in parentheses):

Create (POST): Supported only for security groups.
Read (GET): Supported for all groups.
Update (PATCH): Supported only for security groups and mail-enabled security groups. Not all properties can be updated.
Delete (DELETE): Supported only for security groups.

The following operations are supported on group navigation properties:

Read (GET): Supported for all groups.
Update (POST): Supported only for security groups and mail-enabled security groups. (members and owners only.)
Delete (DELETE): Supported only for security groups. (members and owners only.)

The following actions and functions may be called on groups:

checkMemberGroups to check a group’s membership in a list of groups. The check is transitive.
getAvailableExtensionProperties to return a list of the extension properties that have been registered for a group. Requires version 1.5 or newer.
getMemberGroups to return a list of the groups that a group is a member of. The check is transitive.
isMemberOf to check whether a group is a member of a specified group. The check is transitive.

Remarks

There are three kinds of groups: mail distribution groups (mailEnabled property true and securityEnabled property false); mail-enabled security groups (mailEnabled property true and securityEnabled property true); and, (pure) security groups (mailEnabled property false and securityEnabled property true).
You can only create security groups using the Graph API (you cannot create mail-enabled security groups or mail distribution groups). For this reason the mailEnabled property must be set false and the securityEnabled property must be set true when creating a group.
All properties marked required must be specified when creating a security group using the Graph API. These properties are: displayName, mailNickname, mailEnabled (false), securityEnabled (true).
You cannot update a group from a security group to a mail-enabled security group or to a mail distribution group using the Graph API.

LicenseDetail Entity

Contains information about a license assigned to a user.

The licenseDetails property of the User entity is of type LicenseDetail.

Important: Introduced in version 1.6.

Properties

Declared Properties

Property	Type	Supports	Description
objectId	Edm.String	GET	The unique identifier for the license detail object. Notes: key, not nullable.
servicePlans	Collection(ServicePlanInfo)	GET	Information about the service plans assigned with the license. Notes: not nullable.
skuId	Edm.Guid	GET	Unique identifier (GUID) for the service SKU. Equal to the skuId property on the related SubscribedSku object.
skuPartNumber	Edm.String	GET	Unique SKU display name. Equal to the skuPartNumber on the related SubscribedSku object; for example: "AAD_Premium".

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on license detail (the HTTP method used for each is in parentheses):

Create (POST)
Read (GET)
Update (PATCH)
Delete (DELETE)

No functions or actions may be called on license detail.

OAuth2PermissionGrant Entity

Represents the OAuth 2.0 delegated permission scopes that have been granted to an application (represented by a service principal) as part of the user or admin consent process.

Important: Beginning with version 1.5, the Permission entity type is renamed to OAuth2PermissionGrant. In versions prior to 1.5, permissions created during consent were added to the permissions property of a user or service principal.

Properties

Declared Properties

Property	Type	Supports	Description
clientId	Edm.String	POST, GET	Specifies the objectId of the service principal granted consent to impersonate the user when accessing the resource (represented by the resourceId).
consentType	Edm.String	POST, GET	Specifies whether consent was provided by the administrator on behalf of the organization or whether consent was provided by an individual. The possible values are "AllPrincipals" or "Principal".
expiryTime	Edm.DateTime	POST, GET, PATCH	Reserved. Returns null. Do not use.
objectId	Edm.String	GET	The unique identifier for the permission scope. Notes: key, not nullable.
principalId	Edm.String	POST, GET	If consentType is "AllPrincipals" this value is null, and the consent applies to all users in the organization. If consentType is "Principal" then this property specifies the objectId of the user that granted consent, and applies only for that user.
resourceId	Edm.String	POST, GET	Specifies the objectId of the resource service principal to which access has been granted.
scope	Edm.String	POST, GET, PATCH	Specifies the value of the scope claim that the resource application should expect in the OAuth 2.0 access token.
startTime	Edm.DateTime	POST, GET	Reserved. Returns null. Do not use.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on permission scopes (the HTTP method used for each is in parentheses):

Create (POST)
Read (GET)
Update (PATCH): scope property only.
Delete (DELETE)

No functions or actions may be called on permission scopes.

Remarks

In version 1.5 and newer, the oauth2PermissionGrants navigation property of the User entity and of the ServicePrincipal entity returns the OAuth2PermissionGrant objects associated with the user or service principal.
Prior to version 1.5, the permissions navigation property of the User entity and of the ServicePrincipal entity returns the Permission objects associated with the user or service principal.

Policy Entity

Represents an Azure AD policy. Policies are custom rules that can be enforced on applications, service principals, groups, or the entire organization they are assigned to. Currently only two types of policy are available:

Token Lifetime Policy - Specifies the lifetime duration of tokens issued for applications and service principals. This policy is described in further detail below.
Token Issuance Policy - Specifies characteristics of SAML tokens issued by Azure AD. This policy is described in further detail below.

Property	Type	Supports	Description
definition	Edm.String	POST, GET	The string version of the specific policy. See the information regarding the format of this string in the sections below.
displayName	Edm.String	POST, GET, PATCH	A custom name for the policy.
IsOrganizationDefault	Edm.Boolean	POST, GET, PATCH	If set to true, activates this policy for the tenant. There can be many policies for the same policy type, but only one can be activated as the organization default. Optional, default value is false.
type	Edm.String	POST, GET	Specifies the type of policy. Currently must be `TokenLifetimePolicy` or `TokenIssuancePolicy`.

Navigation Properties

Name	To	Multiplicity (From/To)	Description
appliesTo	DirectoryObject	/	The applications, service principals, groups, or organization the policy applies to.

Supported Operations

The following operations are supported on permission scopes (the HTTP method used for each is in parentheses):

Create (POST)
Read (GET)
Update (PATCH)
Delete (DELETE)

Token Lifetime Policy

Specifies the lifetimes of tokens issued for various purposes. This kind of policy can be assigned to applications and service principals. There are four kinds of tokens whose lifetimes can be configured. Access/Refresh token pairs are obtained during authentication through a client, whereas ID/Session token pairs are obtained during authentication through a browser.

Access Token contains information about the identity and privileges associated with a user account that is used by clients to access protected resources like applications.
Refresh Token is obtained together with the access token when a user authenticates against Azure AD through a client to access a protected resource. While it is not revoked or left unused for more than the MaxInactiveTime (below), it can be used to obtain a new access/refresh token pair when the current access token expires.
ID Token behaves like an access token, but obtained through the browser.
Session Token behaves like a refresh token, but obtained through the browser.

Token Lifetime Policy Properties

The properties below form the JSON object that represents a token lifetime policy. This JSON object must be converted to a string with quotations escaped to be inserted into the "definition" common policy property. Examples are provided on this page.

Note: All time durations in these properties are specified in the format "dd.hh:mm:ss".

Note: Max values for properties denoted in "days" are 1 second short of the denoted number of days. For example, the max value of 1 days is specified as "23:59:59".

Property	Type	Description	Min Value	Max Value	Default Value
AccessTokenLifetime	String	Controls how long both access and ID tokens are considered valid.	10 minutes	1 day	1 hour
MaxInactiveTime	String	Controls how old a refresh token can be before a client can no longer use it to retrieve a new access/refresh token pair to access a resource.	10 minutes	90 days	14 days
MaxAgeSingleFactor	String	Controls how long a user can continue to use refresh tokens to get new access/refresh token pairs after the last time they authenticated successfully with only a single factor. Because single-factor is considered less secure than multi-factor authentication, it is recommended that this policy is set to an equal or lesser value than the MultiFactorRefreshTokenMaxAge.	10 minutes	until-revoked	365 days or until-revoked
MaxAgeMultiFactor	String	Controls how long a user can continue to use refresh tokens to get new access/refresh token pairs after the last time they authenticated successfully with multi factors.	10 minutes	until-revoked	365 days or until-revoked
MaxAgeSessionSingleFactor	String	Controls how long a user can continue to use session tokens to get new ID/session tokens after the last time they authenticated successfully with only a single factor. Because single-factor is considered less secure than multi-factor authentication, it is recommended that this policy is set to an equal or lesser value than the MultiFactorSessionTokenMaxAge	10 minutes	until-revoked	365 or until-revoked
MaxAgeSessionMultiFactor	String	Controls how long a user can continue to use session tokens to get new ID/session tokens after the last time they authenticated successfully with multi factors.	10 minutes	until-revoked	365 or until-revoked
Version	Integer	Set value of 1. Required.	None	None	None

Token Issuance Policy

Token issuance policies can be used to specify certain properties of SAML tokens issued by Azure AD during the Ws-Federation authentication protocol. This kind of policy can be assigned to applications and service principals. Currently, token issuance policies can modify three properties of SAML tokens:

The algorithm used to sign the SAML token. SHA-256 is used by default, but can be changed to use SHA-1.
Whether the SAML token is signed, the entire SAML response is signed, or both. By default, only the SAML token is signed.
The version of the SAML token issued. SAML 2.0 tokens are issued by default, but can be changd to use SAML 1.1.

Token Issuance Policy Properties

The properties below form the JSON object that represents a token issuance policy. This JSON object must be converted to a string with quotations escaped to be inserted into the "definition" common policy property. Examples are provided on this page.

Property	Type	Description	Values	Default Value
SamlTokenVersion	String	Controls the version of the SAML token issued.	`1.1` `2.0`	`2.0`
SigningAlgorithm	String	Controls the algorithm used for signing the SAML token and/or response.	`http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` `http://www.w3.org/2000/09/xmldsig#rsa-sha1`	`http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
TokenResponseSigningPolicy	String	Controls whether the SAML token is signed, the SAML response is signed, or both. If the SAML token version is set to `1.1`, then `TokenOnly` is the only allowed value.	`TokenOnly` `ResponseOnly` `ResponseAndToken`	`TokenOnly`
Version	Integer	The version of the token issuance policy. Required.	`1`	None

ServiceEndpoint Entity

The service endpoint entity contains service discovery information. Inherits from DirectoryObject.

The serviceEndpoints property of the Application and ServicePrincipal entities is of type ServiceEndpoint. Other services can use the information stored in the ServiceEndpoint entity to find this service and its addressable endpoints.

Important: Introduced in version 1.6.

Properties

Declared Properties

Property	Type	Supports	Description
capability	Edm.String	POST (Required), GET	A text identifier for the service's capability. Examples are "Documents" and "Mail".
deletionTimestamp	Edm.DateTime	GET	This property is not valid for service endpoints and always returns null. Inherited from DirectoryObject.
objectId	Edm.String	GET	The unique identifier for the service endpoint. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For service endpoints the value is always "ServiceEndpoint". Inherited from DirectoryObject.
serviceId	Edm.String	POST, GET	The identifier of the service
serviceName	Edm.String	POST, GET	The display name of the service.
Uri	Edm.String	POST (Required), GET	Uri of the service’s endpoint.
resourceId	Edm.String	POST, GET	An identifier for a specific resource within the service.

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

No direct operations may be performed on service endpoints. They are only addressable through the serviceEndpoints property on an Application or a ServicePrincipal. The following operations are supported (the HTTP method used for each is in parentheses):

Create (POST) -- only on the serviceEndpoints navigation property of an Application.
Read (GET) -- on the serviceEndpoints navigation property of an Application or ServicePrincipal.
Delete (DELETE) -- only on the serviceEndpoints property of an Application.

No functions or actions may be called on service endpoints.

Remarks

The capability and uri properties are required when you add a service endpoint to an Application.

ServicePrincipal Entity

Represents an instance of an application in a directory. Inherits from DirectoryObject.

Properties

Declared Properties

Name	Type	Supports	Description
accountEnabled	Edm.Boolean	POST, GET ($filter), PATCH	true if the service principal account is enabled; otherwise, false.
addIns	Collection(AddIn)	GET	Defines custom behavior that a consuming service can use to call an app in specific contexts. For example, applications which can render file streams may set the addIns property for its "FileHandler" functionality. This will let services like Office 365 call the application in the context of a document the user is working on. Notes: Requires version 1.6.
appDisplayName	Edm.String	GET	The display name exposed by the associated application.
appId	Edm.Guid	POST (Required), GET ($filter), PATCH	The unique identifier for the associated application (its appId property).
appOwnerTenantId	Edm.Guid	GET
appRoleAssignmentRequired	Edm.Boolean	POST, GET, PATCH	Specifies whether an AppRoleAssignment to a user or group is required before Azure AD will issue a user or access token to the application. Notes: Requires version 1.5 or newer, not nullable.
appRoles	Collection(AppRole)	GET	The application roles exposed by the associated application. For more information see the appRoles property definition on the Application entity Notes: Requires version 1.5 or newer, not nullable.
authenticationPolicy	ServicePrincipalAuthenticationPolicy	GET	Reserved for internal use only. Do not use. Removed in version 1.5. Notes: Available in version 2013-11-08 only.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for service principals and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
displayName	Edm.String	POST, GET ($filter), PATCH	The display name for the service principal.
errorUrl	Edm.String	POST, GET, PATCH
homepage	Edm.String	POST, GET, PATCH	The URL to the homepage of the associated application.
keyCredentials	Collection(KeyCredential)	POST, GET, PATCH	The collection of key credentials associated with the service principal. Notes: not nullable.
logoutUrl	Edm.String	POST, GET, PATCH
oauth2Permissions	Collection(OAuth2Permission)	GET	The OAuth 2.0 permissions exposed by the associated application. For more information see the oauth2Permissions property definition on the Application entity. Notes: Requires version 1.5 or newer, not nullable.
objectId	Edm.String	GET	The unique identifier for the service principal. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For service principals the value is always "ServicePrincipal". Inherited from DirectoryObject.
passwordCredentials	Collection(PasswordCredential)	POST, GET, PATCH	The collection of password credentials associated with the service principal. Notes: not nullable.
preferredTokenSigningKeyThumbprint	Edm.String	GET	Reserved for internal use only. Do not write or otherwise rely on this property. May be removed in future versions. Notes: Requires version 1.5 or newer.
publisherName	Edm.String	POST, GET ($filter), PATCH	The display name of the tenant in which the associated application is specified.
replyUrls	Collection(Edm.String)	POST, GET, PATCH	The URLs that user tokens are sent to for sign in with the associated application, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to for the associated application. Notes: not nullable.
samlMetadataUrl	Edm.String	POST, GET, PATCH
servicePrincipalNames	Collection(Edm.String)	POST, GET ($filter), PATCH	Based on the identifierURIs collection, plus the application's appId property, these URIs are used to reference an application's service principal. A client will use these to: • populate requiredResourceAccess, via "Permissions to other applications” in the Azure classic portal. • specify a resource URI to acquire an access token, which is the URI returned in the “aud” claim. See identifierURIs in the Application entity for details on how to update. Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
tags	Collection(Edm.String)	POST, GET ($filter), PATCH	Notes: not nullable.

Navigation Properties

Name	To	Multiplicity (From/To)	Description
appRoleAssignedTo	AppRoleAssignment	/	Principals (users, groups, and service principals) that are assigned to this service principal. Requires version 1.5 or newer.
appRoleAssignments	AppRoleAssignment	/	Applications that the service principal is assigned to. Requires version 1.5 or newer.
createdObjects	DirectoryObject	/	Directory objects created by this service principal. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
memberOf	DirectoryObject (Only DirectoryRole and Group objects are supported)	/	Roles and groups that this service principal is a direct member of. Inherited from DirectoryObject. HTTP Methods: GET
oauth2PermissionGrants	OAuth2PermissionGrant	/	User impersonation grants associated with this service principal. Requires version 1.5 or newer.
ownedObjects	DirectoryObject	/	Directory objects that are owned by this service principal. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
owners	DirectoryObject	/	Directory objects that are owners of this service principal. The owners are a set of non-admin users who are allowed to modify this object. Inherited from DirectoryObject. Requires version 2013-11-08 or newer.
permissions	Permission	/	Renamed to oauth2PermissionGrants in version 1.5 and newer. In previous versions pointed to the permissions associated with the service principal. For information about the Permission entity type, see OAuth2PermissionGrant.
policies	Policy	/	Policies assigned to the service principal.
serviceEndpoints	ServiceEndpoint	1/*	Service endpoints available for discovery. For more information, see the ServiceEndpoint topic. HTTP Methods: GET. Requires version 1.6 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on service principals (the HTTP method used for each is in parentheses):

Create (POST)
Read (GET)
Update (PATCH)
Delete (DELETE)

The following operation is supported on navigation properties:

Read (GET)

The following actions and functions may be called on groups:

checkMemberGroups to check a service principal’s membership in a list of groups. The check is transitive.
getMemberGroups to return a list of the groups that a service principal is a member of. The check is transitive.
getMemberObjects to return a list of the groups and directory roles that a service principal is a member of. The check is transitive.

A principal must be in the Company Administrator role to perform operations on service principals.

Remarks

You must set the appId property to the ID of an application in the directory when you create a service principal.

SubscribedSku Entity

Contains information about a service SKU that a company is subscribed to.

Only the read operation is supported on subscribed SKUs; create, update, and delete are not supported. Query filter expressions are not supported.

Properties

Declared Properties

Property	Type	Supports	Description
appliesTo	Edm.String	GET	For example, "User" or "Company". Notes: Requires version 1.6.
capabilityStatus	Edm.String	GET	For example, "Enabled".
consumedUnits	Edm.Int32	GET	The number of licenses that have been assigned.
objectId	Edm.String	GET	The unique identifier for the subscribed sku object. Notes: key, not nullable.
prepaidUnits	LicenseUnitsDetail	GET	Information about the number and status of prepaid licenses.
servicePlans	Collection(ServicePlanInfo)	GET	Information about the service plans that are available with the SKU. Notes: not nullable.
skuId	Edm.Guid	GET	The unique identifier (GUID) for the service SKU.
skuPartNumber	Edm.String	GET	The SKU part number; for example: "AAD_PREMIUM" or "RMSBASIC".

Navigation Properties
None.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on subscribed SKUs (the HTTP method used for each is in parentheses):

Read (GET)

Subscribed SKUs do not expose any navigation properties.

No functions or actions may be called on subscribed SKUs.

TenantDetail Entity

Represents an Azure Active Directory tenant. Only the read and update operations are supported on tenants; create and delete are not supported. Inherits from DirectoryObject.

Properties

Declared Properties

Name	Type	Supports	Description
assignedPlans	Collection(AssignedPlan)	GET	The collection of service plans associated with the tenant. Notes: not nullable.
city	Edm.String	GET
companyLastDirSyncTime	Edm.DateTime	GET	The time and date at which the tenant was last synced with the on-premise directory.
country	Edm.String	GET
countryLetterCode	Edm.String	GET
deletionTimestamp	Edm.DateTime	GET	This property is not valid for tenants and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
dirSyncEnabled	Edm.Boolean	GET	true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayName	Edm.String	GET	The display name for the tenant.
marketingNotificationEmails	Collection(Edm.String)	GET, PATCH	Notes: not nullable.
objectId	Edm.String	GET	The unique identifier for the tenant. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For tenants the value is always "Company". Inherited from DirectoryObject.
postalCode	Edm.String	GET
preferredLanguage	Edm.String	GET
provisionedPlans	Collection(ProvisionedPlan)	GET	Notes: not nullable.
provisioningErrors	Collection(ProvisioningError)	GET	Notes: not nullable.
state	Edm.String	GET
street	Edm.String	GET
technicalNotificationMails	Collection(Edm.String)	GET, PATCH	Notes: not nullable.
telephoneNumber	Edm.String	GET
tenantType	Edm.String	GET	Notes: removed in version 1.5 and newer.
verifiedDomains	Collection(VerifiedDomain)	GET	The collection of domains associated with this tenant. Notes: not nullable.

Navigation Properties

Name	To	To Multiplicity	Description
trustedCAsForPasswordlessAuth	TrustedCAsForPasswordlessAuth	1/1	The set of certificate authorities used to validate the trust chain while performing password-less authentication. For more information, see Remarks. Notes: Requires version 1.6 or newer.

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on tenants (the HTTP method used for each is in parentheses):

Read (GET)
Update (PATCH); only the marketingNotificationMails and technicalNotificationMails properties can be updated using the Graph API.

The following operations are supported on tenant navigation properties:

Read (GET)
Update (POST)
Delete (DELETE)

No functions or actions may be called on tenants.

Remarks

You cannot create or delete tenants using the Graph API.
Only the marketingNotificationMails and technicalNotificationMails properties can be updated using the Graph API.
Trusted certificate authorities enable users in a federated tenant to sign in using certificate-based authentication. To enable this scenario, configure the public certificates of the certificate authorities trusted for sign-in by setting the trustedCAsForPasswordlessAuth navigation property.
Query filter expressions are not supported on tenants.

TrustedCAsForPasswordlessAuth Entity

Represents a set of certificate authorities to validate the trust chain while performing password-less authentication.

The trustedCAsForPasswordlessAuth navigation property of the TenantDetail entity is a collection of trustedCAsForPasswordlessAuth. Clients can use this property to configure the public certificates of the authorities trusted for sign-in in order to enable users in a federated tenant to sign in using certificate-based authentication.

Important: Introduced in version 1.6.

Properties

Declared Properties

Name	Type	Supports	Description
id	Edm.String	GET	Unique identifier. Notes: key, not nullable.
certificateAuthorities	Collection(CertificateAuthorityInformation)	POST (Required), GET, PATCH	Collection of certificate authority information.

Navigation Properties
None.

Supported Operations

The following operations are supported on trusted certificate authorities (the HTTP method used for each is in parentheses):

Create (POST); only the certificateAuthorities property can be specified.
Read (GET)
Update (PATCH); only the certificateAuthorities property

Trusted certificates do not expose any navigation properties.

No functions or actions may be called on trusted certificate authorities.

User Entity

Represents an Azure AD user account. Inherits from DirectoryObject.

Properties

Declared Properties

Name	Type	Supports	Description
accountEnabled	Edm.Boolean	POST (Required), GET ($filter), PATCH	true if the account is enabled; otherwise, false. This property is required when a user is created.
assignedLicenses	Collection(AssignedLicense)	POST, GET, PATCH	The licenses that are assigned to the user. Notes: not nullable.
assignedPlans	Collection(AssignedPlan)	GET	The plans that are assigned to the user. Notes: not nullable.
city	Edm.String	POST, GET ($filter), PATCH	The city in which the user is located.
country	Edm.String	POST, GET ($filter), PATCH	The country/region in which the user is located; for example, "US" or "UK".
creationType	Edm.String	POST (Required for local accounts), GET ($filter)	Indicates whether the user account is a local account for an Azure Active Directory B2C tenant. Possible values are "LocalAccount" and null. When creating a local account, the property is required and you must set it to "LocalAccount". When creating a work or school account, do not specify the property or set it to null. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation. Notes: Requires version 1.6 or newer.
deletionTimestamp	Edm.DateTime	GET	This property is not valid for users and always returns null. Inherited from DirectoryObject. Notes: Requires version 1.5 or newer.
department	Edm.String	POST, GET ($filter), PATCH	The name for the department in which the user works.
dirSyncEnabled	Edm.Boolean	GET ($filter)	true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced; null if this object has never been synced from an on-premises directory (default).
displayName	Edm.String	POST (Required), GET ($filter), PATCH (but cannot be cleared)	The name displayed in the address book for the user. This is usually the combination of the user's first name, middle initial and last name. This property is required when a user is created and it cannot be cleared during updates.
employeeId	Edm.String	POST, GET ($filter), PATCH	The employee identifier assigned to the user by the organization.
facsimileTelephoneNumber	Edm.String	POST, GET, PATCH	The telephone number of the user's business fax machine.
givenName	Edm.String	POST, GET ($filter), PATCH	The given name (first name) of the user.
immutableId	Edm.String	POST (Required if using a federated domain for the UPN), GET ($filter), PATCH	This property is used to associate an on-premises Active Directory user account to their Azure AD user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user's userPrincipalName (UPN) property. Important: The $ and _ characters cannot be used when specifying this property. Notes: Requires version 2013-11-08 or newer.
jobTitle	Edm.String	POST, GET ($filter), PATCH	The user's job title.
lastDirSyncTime	Edm.DateTime	GET ($filter)	Indicates the last time at which the object was synced with the on-premises directory; for example: "2013-02-16T03:04:54Z"
mail	Edm.String	POST, GET ($filter)	The SMTP address for the user, for example, "[email protected]".
mailNickname	Edm.String	POST (Required for work or school accounts), GET ($filter), PATCH	The mail alias for the user. This property is required when you create a work or school account; it is optional for a local account.
mobile	Edm.String	POST, GET, PATCH	The primary cellular telephone number for the user.
objectId	Edm.Guid	GET	The unique identifier for the user. Inherited from DirectoryObject. Notes: key, immutable, not nullable, unique.
objectType	Edm.String	GET	A string that identifies the object type. For users the value is always "User". Inherited from DirectoryObject.
onPremisesSecurityIdentifier	Edm.String	GET	Contains the on-premises security identifier (SID) for the user that was synchronized from on-premises to the cloud. Notes: Requires version 1.5 or newer.
otherMails	Collection(Edm.String)	POST, GET ($filter), PATCH	A list of additional email addresses for the user; for example: ["[email protected]", "[email protected]"]. Notes: not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
passwordPolicies	Edm.String	POST, GET, PATCH	Specifies password policies for the user. This value is an enumeration with one possible value being "DisableStrongPassword", which allows weaker passwords than the default policy to be specified. "DisablePasswordExpiration" can also be specified. The two may be specified together; for example: "DisablePasswordExpiration, DisableStrongPassword".
passwordProfile	PasswordProfile	POST (Required), PATCH	Specifies the password profile for the user. The profile contains the user's password. This property is required when a user is created. The password in the profile must satisfy minimum requirements as specified by the passwordPolicies property. By default, a strong password is required. For information about the constraints that must be satisfied for a strong password, see Password policy under Change your password in the Microsoft Office 365 help pages. The passwordProfile is a write only property.
physicalDeliveryOfficeName	Edm.String	POST, GET, PATCH	The office location in the user's place of business.
postalCode	Edm.String	POST, GET, PATCH	The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code.
preferredLanguage	Edm.String	POST, GET, PATCH	The preferred language for the user. Should follow ISO 639-1 Code; for example "en-US".
provisionedPlans	Collection(ProvisionedPlan)	GET	The plans that are provisioned for the user. Notes: not nullable.
provisioningErrors	Collection(ProvisioningError)	GET	A collection of error details that are preventing this user from being provisioned successfully.
proxyAddresses	Collection(Edm.String)	GET ($filter)	Fpr example: ["SMTP: [email protected]", "smtp: [email protected]"] Notes: unique, not nullable, the any operator is required for filter expressions on multi-valued properties; for more information, see Supported Queries, Filters, and Paging Options.
refreshTokensValidFromDateTime	Edm.DateTime	POST, GET, PATCH	Any refresh tokens or sessions tokens (session cookies) issued before this time are invalid, and applications will get an error when using an invalid refresh or sessions token to acquire a delegated access token (to access APIs such as AD Graph). If this happens, the application will need to acquire a new refresh token by making a request to the authorize endpoint. Use Invalidate all refresh tokens to reset.
showInAddressList	Edm.Boolean	POST, GET, PATCH	true if the Outlook global address list should contain this user, otherwise false. If not set, this will be treated as true. For users invited through the invitation manager, this property will be set to false.
signInNames	Collection(SignInName)	POST (Required for local accounts), GET ($filter)	Specifies the collection of sign-in names for a local account in an Azure Active Directory B2C tenant. Each sign-in name must be unique in the tenant. The property must be specified when you create a local account user; do not specify it when you create a work or school account. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation. Notes: Requires version 1.6 or newer.
sipProxyAddress	Edm.String	GET	Specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the user. Notes: Requires version 1.5 or newer.
state	Edm.String	POST, GET ($filter), PATCH	The state or province in the user's address.
streetAddress	Edm.String	POST, GET, PATCH	The street address of the user's place of business.
surname	Edm.String	POST, GET ($filter), PATCH	The user's surname (family name or last name). Notes: filterable, must be between 1 and 64 characters.
telephoneNumber	Edm.String	POST, GET, PATCH	The primary telephone number of the user's place of business.
thumbnailPhoto	Edm.Stream	POST, GET, PATCH	A thumbnail photo to be displayed for the user. Notes: not nullable.
usageLocation	Edm.String	POST, GET ($filter), PATCH	A two letter country code (ISO standard 3166). Required for users that will be assigned licenses due to legal requirement to check for availability of services in countries. Examples include: "US", "JP", and "GB". Notes: not nullable.
userIdentities	Collection(UserIdentity)	POST (Required for social accounts), GET ($filter)	Specifies the collection of userIdentities for a social user account in an Azure Active Directory B2C tenant. Each userIdentity (issuer and issuerIdentity as a pair) must be unique in the tenant. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation. Notes: Requires version 1.6 or newer.
userPrincipalName	Edm.String	POST (Required for work or school accounts), GET ($filter), PATCH	The user principal name (UPN) of the user. The UPN is an Internet-style login name for the user based on the Internet standard RFC 822. By convention, this should map to the user's email name. The general format is "alias@domain". For work or school accounts, the domain must be present in the tenant's collection of verified domains. This property is required when a work or school account is created; it is optional for local accounts. The verified domains for the tenant can be accessed from the VerifiedDomains property of TenantDetail. Notes: key, unique.
userType	Edm.String	POST, GET ($filter), PATCH	A string value that can be used to classify user types in your directory, such as "Member" and "Guest". Notes: Requires version 2013-11-08 or newer.

Navigation Properties

Name	To	Multiplicity (From/To)	Description
manager	DirectoryObject (Only User and Contact objects are supported.)	*/0..1	The user or contact that is this user's manager. Inherited from DirectoryObject. HTTP Methods: GET, PUT, DELETE
directReports	DirectoryObject (Only User and Contact objects are supported.)	/	The users and contacts that report to the user. (The users and contacts that have their manager property set to this user.) Inherited from DirectoryObject. HTTP Methods: GET
licenseDetails	LicenseDetail	/	Notes: Requires version 1.6 or later.
memberOf	DirectoryObject (Only Group and DirectoryRole objects are supported.)	/	The groups and directory roles that the user is a member of. Inherited from DirectoryObject. HTTP Methods: GET
ownedDevices	Device	/	Devices that are owned by the user.
permissions	Permission	/	The permissions associated with the user. The property is renamed to oauth2PermissionGrants and the Permission entity is renamed to OAuth2PermissionGrant in version 1.5 and newer. See the documentation for OAuth2PermssionGrant for documentation of the Permission entity type.
registeredDevices	Device	/	Devices that are registered for the user.
createdObjects	DirectoryObject	/	Directory objects that were created by the user. Requires version 2013-11-08 or newer.
ownedObjects	DirectoryObject	/	Directory objects that are owned by the user. Requires version 2013-11-08 or newer.
appRoleAssignments	AppRoleAssignment	/	The set of applications that this user is assigned to. Requires version 1.5 or newer. HTTP Methods: GET, POST, DELETE
oauth2PermissionGrants	OAuth2PermissionGrant	/	The set of applications that are granted consent to impersonate this user. Requires version 1.5 or newer. HTTP Methods: GET, POST, DELETE

Note: Inherited navigation properties that are not listed are not supported. Requests addressed to unsupported navigation properties return 400 Bad Request.

Supported Operations

The following operations are supported on users (the HTTP method used for each is in parentheses):

Create (POST)
Read (GET)
Update (PATCH)
Delete (DELETE)

The following operations are supported on user navigation properties; not all operations are supported on every navigation property.

Read (GET)
Update (PUT)
Delete (DELETE)

The following actions and functions may be called on users:

assignLicense to assign and/or remove a specified list of licenses from a user. Requires version 2013-11-08 or newer.
checkMemberGroups to check the user’s membership in a list of groups. The check is transitive.
getAvailableExtensionProperties to return a list of the extension properties that have been registered for a user. Requires version 1.5 or newer.
getMemberGroups to return a list of the groups that a user is a member of. The check is transitive.
getMemberObjects to return a list of the groups and directory roles that a user is a member of. The check is transitive.
isMemberOf to check whether a user is a member of a specified group. The check is transitive.

Remarks

To create a work or school account, the required properties are: accountEnabled, displayName, mailNickname, passwordProfile, and userPrincipalName. The password specified in the passwordProfile property must meet the tenant’s password complexity requirements. For more information, see the passwordPolicies property.
To create a local account, the required properties are: accountEnabled, creationType (must be set to “LocalAccount”), displayName, passwordProfile, and signInNames. The password specified in the passwordProfile property must meet the tenant’s password complexity requirements. For more information, see the passwordPolicies property.
In version 2013-11-08 and newer, the immutableId property must be specified when creating a new user account in the Graph if you are using a federated domain for the user’s userPrincipalName (UPN) property.
The displayName property cannot be cleared on updates.
The passwordProfile property always returns null. This is to prevent the user’s password from being displayed. You can reset the user’s password by updating the passwordProfile property.
In addition to the standard addressing available for all directory entities, users may be addressed by using the userPrincipalName property; for example, https://graph.windows.net/contoso.onmicrosoft.com/users/[email protected]?api-version=1.5.

Complex type reference

AddIn Type

Defines custom behavior that a consuming service can use to call an app in specific contexts. For example, applications which can render file streams may set the addIns property for its "FileHandler" functionality. This will let services like Office 365 call the application in context of the document the user is working on. The addins property of the Application and ServicePrincipal entities is a collection of AddIn.

Important: Introduced in version 1.6.

Properties

Name	Type	Read/Write	Description
id	Edm.Guid	R	A unique identifier within the addins collection on a specific Application.
type	Edm.String	RW	The unique name for the functionality exposed by the app.
properties	Collection(KeyValue)	RW (Required on writes)	The collection of key-value pairs that define parameters the consuming service can use or call. You must specify this property when performing a POST or a PATCH operation on the addIns collection.

AlternativeSecurityId Type

Contains an alternative security ID associated with a device. The alternativeSecurityIds property of the Device entity is a collection of AlternativeSecurityId.

Properties

Name	Type	Read/Write	Description
identityProvider	Edm.String
key	Edm.Binary
type	Edm.Int32

AppRole Type

Represents an application role that may be requested by a client application calling another application or that may be used to assign an application to users or groups in a specified application role. The appRoles property of the ServicePrincipal entity and of the Application entity is a collection of AppRole.

Important: Requires version 1.5 or newer.

Properties

Name	Type	Read/Write	Description
allowedMemberTypes	Collection(Edm.String)	RW	Specifies whether this app role definition can be assigned to users and groups by setting to "User", or to other applications (that are accessing this application in daemon service scenarios) by setting to "Application", or to both. Notes: not nullable.
description	Edm.String	RW	Permission help text that appears in the admin app assignment and consent experiences.
displayName	Edm.String	RW	Display name for the permission that appears in the admin consent and app assignment experiences.
id	Edm.Guid	RW	Unique role identifier inside the appRoles collection.
isEnabled	Edm.Boolean	RW	When creating or updating a role definition, this must be set to true (which is the default). To delete a role, this must first be set to false. At that point, in a subsequent call, this role may be removed.
value	Edm.String	RW	Specifies the value of the roles claim that the application should expect in the authentication and access tokens.

AssignedLicense Type

Represents a license assigned to a user. The assignedLicenses property of the User entity is a collection of AssignedLicense.

Properties

Name	Type	Read/Write	Description
disabledPlans	Collection(Edm.Guid)	R	A collection of the unique identifiers for plans that have been disabled. Notes: not nullable.
skuId	Edm.Guid	R	The unique identifier for the service SKU. Same value as the skuId property of the related SubscribedSku object.

AssignedPlan Type

The assignedPlans property of both the User entity and the TenantDetail entity is a collection of AssignedPlan.

Properties

Name	Type	Read/Write	Description
assignedTimestamp	Edm.DateTime	R	The date and time at which the plan was assigned; for example: 2013-01-02T19:32:30Z.
capabilityStatus	Edm.String	R	For example, "Enabled".
service	Edm.String	R	The name of the service; for example, "SharePoint", "MicrosoftOffice", or "Exchange".
servicePlanId	Edm.Guid	R	A GUID that identifies the service plan.

CertificateAuthorityInformation Type

Represents a certificate authority used when validating the trust chain while performing password-less authentication. The certificateAuthorities property of the TrustedCAsForPasswordlessAuth entity is a collection of CertificateAuthorityInformation.

Important: Introduced in version 1.6.

Properties

Name	Type	Read/Write	Description
authorityType	Edm.String	RW (Required on POST)	Required. Must be set to one of two possible values: “RootAuthority” or “IntermediateAuthority”. It is used while validating certificates during authentication.
crlDistributionPoint	Edm.String	RW	Certificate Revocation List (CRL) distribution points hold files which store the serial numbers of all certificates that have been revoked. This is typically a URI.
deltaCrlDistributionPoint	Edm.String	RW	A URI that contains the list of all revoked certificates since the last time a full CRL was created.
trustedCertificate	Edm.Binary	RW (Required on POST)	Required. The public certificate in binary form.
trustedIssuer	Edm.String	R	Read only. Calculated from the trustedCertificate value.
trustedIssuerSki	Edm.String	R	Read only. The subject key identifier is calculated from the trustedCertificate value.

KeyCredential Type

Contains a key credential associated with an application or a service principal. The keyCredentials property of the Application and ServicePrincipal entities is a collection of KeyCredential.

Properties

Name	Type	Description
customKeyIdentifier	Edm.Binary
endDate	Edm.DateTime	The date and time at which the credential expires.
keyId	Edm.Guid	The unique identifier (GUID) for the key.
startDate	Edm.DateTime	The date and time at which the credential becomes valid.
type	Edm.String	The type of key credential; for example, "Symmetric".
usage	Edm.String	A string that describes the purpose for which the key can be used; for example, "Verify".
value	Edm.String

KeyValue Type

Contains a key-value pair that defines a parameter that a consuming service can use or call on an application specified in an AddIn. The properties property of the AddIn type is a collection of KeyValue.

Important: Introduced in version 1.6.

Properties

Name	Type	Read/Write	Description
key	Edm.String	RW	The key in the key value pair.
value	Edm.String	RW	The value of the key value pair.

LicenseUnitsDetail Type

Contains information and status about the prepaid units of a service SKU that a company is subscribed to.

The prepaidUnits property of the SubscribedSku entity is of type LicenseUnitsDetail.

Properties

Name	Type	Read/Write	Description
enabled	Edm.Int32	R	The number of units that are enabled.
suspended	Edm.Int32	R	The number of units that are suspended.
warning	Edm.Int32	R	The number of units that are in warning status.

OAuth2Permission Type

Represents an OAuth 2.0 delegated permission scope. The specified OAuth 2.0 delegated permission scopes may be requested by client applications (through the requiredResourceAccess collection on the Application object) when calling a resource application. The oauth2Permissions property of the ServicePrincipal entity and of the Application entity is a collection of OAuth2Permission.

Important: Requires version 1.5 or newer.

Properties

Name	Type	Read/Write	Description
adminConsentDescription	Edm.String	RW	Permission help text that appears in the admin consent and app assignment experiences.
adminConsentDisplayName	Edm.String	RW	Display name for the permission that appears in the admin consent and app assignment experiences.
id	Edm. Guid	RW	Unique scope permission identifier inside the oauth2Permissions collection.
isEnabled	Edm.Boolean	RW	When creating or updating a permission, this property must be set to true (which is the default). To delete a permission, this property must first be set to false. At that point, in a subsequent call, the permission may be removed. Notes: not nullable.
type	Edm.String	RW	Specifies whether this scope permission can be consented to by an end user, or whether it is a tenant-wide permission that must be consented to by a Company Administrator. Possible values are "User" or "Admin".
userConsentDescription	Edm.String	RW	Permission help text that appears in the end user consent experience.
userConsentDisplayName	Edm.String	RW	Display name for the permission that appears in the end user consent experience.
value	Edm.String	RW	The value of the scope claim that the resource application should expect in the OAuth 2.0 access token.

OptionalClaims Type

Contains optional claims associated with an application. An application can configure optional claims to be returned in each of three types of tokens (ID token, access token, SAML 2 token) it receives from the security token service. The application can configure a different set of optional claims to be returned in each token type. The OptionalClaims property of the Application entity is an OptionalClaims object.

Properties

Name	Type	Read/Write	Description
idToken	Collection (OptionalClaim)	RW	The optional claims returned in the JWT ID token.
accessToken	Collection (OptionalClaim)	RW	The optional claims returned in the JWT access token.
saml2Token	Collection (OptionalClaim)	RW	The optional claims returned in the SAML2 token.

OptionalClaim Type

Contains an optional claim associated with an application or a service principal. The idToken, accessToken, and saml2Token properties of the of the OptionalClaims type is a collection of OptionalClaim.

Properties

Name	Type	Read/Write	Description
name	Edm.String	RW	The name of the optional claim.
source	Edm.String	RW	The source (directory object) of the claim. There are predefined claims and user defined claims from extension properties. If the source value is null, the claim is a predefined optional claim. If the source value is user, the value in the name property is the extension property from the user object.
essential	Edm.Boolean	RW	If the value is true, the claim specified by the client is necessary to ensure a smooth authorization experience for the specific task requested by the end user. The default value is false.
additionalProperties	Collection (Edm.String)	RW	Additional boolean properties of the claim. If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

PasswordCredential Type

Contains a password credential associated with an application or a service principal. The passwordCredentials property of the ServicePrincipal entity and of the Application entity is a collection of PasswordCredential.

Properties

Name	Type	Description
customKeyIdentifier	Edm.Binary
endDate	Edm.DateTime	The date and time at which the password expires.
keyId	Edm.Guid
startDate	Edm.DateTime	The date and time at which the password becomes valid.
value	Edm.String

PasswordProfile Type

Contains the password profile associated with a user. The passwordProfile property of the User entity is a PasswordProfile object.

Properties

Name	Type	Notes	Description
password	Edm.String	W	The password for the user. This property is required when a user is created. It can be updated, but the user will be required to change the password on the next login. The password must satisfy minimum requirements as specified by the user's PasswordPolicies property. By default, a strong password is required. The password property is write only.
forceChangePasswordNextLogin	Edm.Boolean	RW	true if the user must change her password on the next login; otherwise false.

ProvisionedPlan Type

The provisionedPlans property of the User entity and the TenantDetail entity is a collection of ProvisionedPlan.

Properties

Name	Type	Read/Write	Description
capabilityStatus	Edm.String	R	For example, "Enabled" or "Deleted".
provisioningStatus	Edm.String	R	For example, "Success".
service	Edm.String	R	The name of the service; for example, "SharePoint", "MicrosoftOffice", or "Exchange".

ProvisioningError Type

The provisioningErrors property of the Contact, User, and Group entities is a collection of ProvisioningError.

Properties

Name	Type	Read/Write	Description
errorDetail	Edm.String	R	A description of the error.
resolved	Edm.Boolean	R	true if the error was resolved; otherwise, false.
serviceInstance	Edm.String	R	The service instance for which the error occurred.
timestamp	Edm.DateTime	R	The date and time at which the error occurred.

RequiredResourceAccess Type

Specifies the set of OAuth 2.0 permission scopes and app roles under the specified resource that an application requires access to. The specified OAuth 2.0 permission scopes may be requested by client applications (through the requiredResourceAccess collection) when calling a resource application. The requiredResourceAccess property of the Application entity is a collection of ReqiredResourceAccess.

Important: Requires version 1.5 or newer.

Properties

Name	Type	Read/Write	Description
resourceAppId	Edm.String	RW	The unique identifier for the resource that the application requires access to. This should be equal to the appId declared on the target resource application.
resourceAccess	Collection(ResourceAccess)	RW	The list of OAuth2.0 permission scopes and app roles that the application requires from the specified resource. Notes: not nullable.

ResourceAccess Type

Specifies an OAuth 2.0 permission scope or an app role that an application requires. The resourceAccess property of the RequiredResourceAccess type is a collection of ResourceAccess.

Important: Requires version 1.5 or newer.

Properties

Name	Type	Read/Write	Description
id	Edm.Guid	RW	The unique identifier for one of the OAuth2Permission or AppRole instances that the resource application exposes. Notes: not nullable.
type	Edm.String	RW	Specifies whether the id property references an OAuth2Permission or an AppRole. Possible values are "scope" or "role".

ServicePlanInfo Type

Contains information about a service plan associated with a subscribed SKU or a license assigned to a user. The servicePlans property of the SubscribedSku and LicenseDetail entity is a collection of ServicePlanInfo.

Properties

Name	Type	Read/Write	Description
appliesTo	Edm.String	R	The object the service plan can be assigned to. Possible values: "User" - service plan can be assigned to individual users. "Company" - service plan can be assigned to the entire tenant. Notes: Requires version 1.6.
provisioningStatus	Edm.String	R	Possible values: "Success" - Service is fully provisioned. "Disabled" - Service has been disabled. "PendingInput" - Service is not yet provisioned; awaiting service confirmation. "PendingActivation" - Service is provisioned but requires explicit activation by administrator (e.g. Intune_O365 service plan) "PendingProvisioning" - Microsoft has added a new service to the product SKU and it has not been activated in the tenant, yet. Notes: Requires version 1.6.
servicePlanId	Edm.Guid	R	The unique identifier (GUID) of the service plan.
servicePlanName	Edm.String	R	The name of the service plan. For example, "MFA_PREMIUM", "AAD_PREMIUM", or "RMS_S_BASIC".

ServicePrincipalAuthenticationPolicy Type

Contains the authentication policy of a service principal.

Important: Available only in version 2013-11-08; however it is reserved for internal use only and is removed in version 1.5 and newer.

Properties

Name	Type	Read/Write	Description
defaultPolicy	Edm.String	RW	Reserved for internal use only. Do not use. Removed in version 1.5.
allowedPolicies	Collection(Edm.String)	RW	Reserved for internal use only. Do not use. Removed in version 1.5. Notes: not nullable.

SignInName Type

Contains information about a sign-in name of a local account user in an Azure Active Directory B2C tenant. The signInNames property of the User entity is a collection of SignInName. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation.

Important: Introduced in version 1.6.

Properties

Name	Type	Read/Write	Description
type	Edm.String	RW	A string value that can be used to classify user sign-in types in your directory, such as "emailAddress" or "userName".
value	Edm.String	RW	The sign-in used by the local account. Must be unique across the company/tenant. For example, "[email protected]".

UserIdentity Type

Contains information about a identity of a social account user in an Azure Active Directory B2C tenant. The userIdentities property of the User entity is a collection of userIdentity. For more information about Azure Active Directory B2C, see the Azure Active Directory B2C documentation.

Important: Introduced in version 1.6.

Properties

Name	Type	Read/Write	Description
issuer	Edm.String	RW	The string representation of the identity provider that issued the user identifier, such as `facebook.com`.
issuerUserId	Edm.Binary	RW	The unique user identifier used by the social identity provider.

VerifiedDomain Type

Specifies a domain for a tenant. The verifiedDomains property of the TenantDetail entity is a collection of VerifiedDomain.

Properties

Name	Type	Read/Write	Description
capabilities	Edm.String	R	For example, "Email", "OfficeCommunicationsOnline".
default	Edm.Boolean	R	true if this is the default domain associated with the tenant; otherwise, false.
id	Edm.String	R	For example, "00057FFE80187238".
initial	Edm.Boolean	R
name	Edm.String	R	The domain name; for example, "contoso.onmicrosoft.com"
type	Edm.String	R	For example, "Managed".

Additional Resources

Learn more about Graph API supported features, capabilities, and preview features in Graph API concepts

Share via

Entity and complex type reference | Graph API reference

Entity reference

Application Entity

Properties

Supported Operations

AppRoleAssignment Entity

Properties

Contact Entity

Properties

Supported Operations

Remarks

Contract Entity

Properties

Supported Operations

Device Entity

Properties

Supported Operations

DirectoryLinkChange Entity

Properties

DirectoryObject Entity

Properties

Supported Operations

DirectoryRole Entity

Properties

Supported Operations

Remarks

DirectoryRoleTemplate Entity

Properties

Supported Operations

Domain Entity

Properties

DomainDnsRecord Entity

Properties

DomainDnsCnameRecord Entity

Properties

DomainDnsMxRecord Entity

Properties

DomainDnsSrvRecord Entity

Properties

DomainDnsTxtRecord Entity

Properties

DomainDnsUnavailableRecord Entity

Properties

ExtensionProperty Entity

Properties

Group Entity

Properties

Supported Operations

Remarks

LicenseDetail Entity

Properties

Supported Operations

OAuth2PermissionGrant Entity

Properties

Supported Operations

Remarks

Policy Entity

Supported Operations

Token Lifetime Policy

Token Lifetime Policy Properties

Token Issuance Policy

Token Issuance Policy Properties

ServiceEndpoint Entity

Properties

Supported Operations

Remarks

ServicePrincipal Entity

Properties

Supported Operations

Remarks

SubscribedSku Entity

Properties

Supported Operations

TenantDetail Entity

Properties

Supported Operations

Remarks

TrustedCAsForPasswordlessAuth Entity

Properties