group: evaluateDynamicMembership

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Evaluate whether a user or device is or would be a member of a dynamic group. The membership rule is returned along with other details that were used in the evaluation. You can complete this operation in the following ways:

  • Evaluate whether a user or device is a member of a specified dynamic group.
  • Evaluate whether a user or device would be a member of a dynamic group based on the ID of the user or device and a membership rule.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

The following table shows the least privileged permission or permissions required to call this API on each supported resource type. Follow best practices to request least privileged permissions. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Evaluate dynamic membership with member ID and group ID

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
device Group.Read.All and Device.Read.All Not supported. Not supported.
user Group.Read.All and User.Read.All Not supported. Not supported.

Evaluate dynamic membership with member ID and membership rule

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
device Device.Read.All Not supported. Not supported.
user User.Read.All Not supported. Not supported.

HTTP request

POST /groups/{id}/evaluateDynamicMembership
POST /groups/evaluateDynamicMembership

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-type application/json

Request body

In the request body, supply the required properties.

The following table lists the properties that are required when you evaluate group membership.

Parameter Type Description
memberId String collection memberId is the object Id of the user or device to be evaluated.
membershipRule String collection The rule that is used for membership evaluation. If this property is not provided, the rule for the existing group is evaluated. If this property is provided, the user or device is evaluated for possible membership in a group with the same rule. For more information, see Dynamic membership rules for groups in Microsoft Entra ID.

Response

If successful, this method returns a 200 OK response code and an evaluateDynamicMembershipResult object.

Examples

Example 1: Evaluate if a user or device is a member of an existing group

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/groups/{id}/evaluateDynamicMembership
Content-type: application/json

{
  "memberId": "319b41e8-d9e4-42f8-bdc9-741113f48b33"
}

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
  "membershipRule": "(user.displayName -startsWith \"EndTestUser\")",
  "membershipRuleEvaluationResult": true,
  "membershipRuleEvaluationDetails": {
    "expressionResult": true,
    "expression": "user.displayName -startsWith \"EndTestUser\"",
    "propertyToEvaluate": {
      "propertyName": "displayName",
      "propertyValue": "EndTestUser001"
    }
  }
}

Example 2: Evaluate if a user or device would be a member of a group based on a membership rule

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/groups/evaluateDynamicMembership
Content-type: application/json

{
  "memberId": "319b41e8-d9e4-42f8-bdc9-741113f48b33",
  "membershipRule": "(user.displayName -startsWith \"EndTestUser\")"
}

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
  "membershipRule": "(user.displayName -startsWith \"EndTestUser\")",
  "membershipRuleEvaluationResult": true,
  "membershipRuleEvaluationDetails": {
    "expressionResult": true,
    "expression": "user.displayName -startsWith \"EndTestUser\"",
    "propertyToEvaluate": {
      "propertyName": "displayName",
      "propertyValue": "EndTestUser001"
    }
  }
}