Edit

Share via

Create or update ownerlessGroupPolicy

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.

Create or update the ownerlessGroupPolicy for the tenant. If the policy doesn't exist, it creates a new one; if the policy exists, it updates the existing policy.

To disable the policy, set isEnabled to false. Setting isEnabled to false clears the values of all other policy parameters.

This API is available in the following national cloud deployments.

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

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Group.ReadWrite.All Not available.
Delegated (personal Microsoft account) Not supported. Not supported.
Application Not supported. Not supported.

Important

In delegated scenarios, the calling user must be assigned the Groups Administrator or Exchange Administrator Microsoft Entra roles.

HTTP request

PATCH /policies/ownerlessGroupPolicy

Request headers

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

Request body

In the request body, supply a JSON representation of the ownerlessGroupPolicy object. All required properties must be provided for both create and update operations. The API performs a full replacement of the policy configuration. Unlike the admin portal, the API doesn't apply default values for any properties.

Property Type Description
emailInfo emailDetails The email notification details for the ownerless group policy. Required.
enabledGroupIds String collection The collection of IDs for Microsoft 365 groups for which the policy is enabled. Required.
isEnabled Boolean Indicates whether the ownerless group policy is enabled. Setting this property to false clears the values of all other policy parameters. Required.
maxMembersToNotify Int64 The maximum number of members to notify. Value range is 0-90. Required.
notificationDurationInWeeks Int64 The number of weeks for the notification duration. Value range is 1-7. Required.
policyWebUrl String The URL to the policy documentation. Optional.
targetOwners targetOwners The criteria for selecting target owners. Required.

Response

If successful, this method returns a 200 OK response code and an updated ownerlessGroupPolicy object in the response body when the policy already exists, or a 201 Created response code and a new ownerlessGroupPolicy object in the response body when the policy is created.

Errors

Condition Status code Error code
notificationDurationInWeeks is not in range 1-7 400 Bad Request badRequest
maxMembersToNotify is not in range 0-90 400 Bad Request badRequest

Examples

Example 1: Create or update the ownerless group policy

Request

The following example shows a request.

PATCH https://graph.microsoft.com/beta/policies/ownerlessGroupPolicy
Content-Type: application/json

{
  "isEnabled": true,
  "notificationDurationInWeeks": 3,
  "maxMembersToNotify": 40,
  "policyWebUrl": "https://contoso.com/policies/ownerless-groups",
  "targetOwners": {
    "notifyMembers": "allowSelected",
    "securityGroups": [
      "security-group1@contoso.com",
      "security-group2@contoso.com"
    ]
  },
  "enabledGroupIds": [
    "b14e5eb2-a0a1-4c8f-b83e-940526219200",
    "454dde77-ac2b-421b-a6ab-165be910e0fc"
  ],
  "emailInfo": {
    "senderEmailAddress": "admin@contoso.com",
    "subject": "Need your help with $Group.Name group",
    "body": "Hi $User.DisplayName, \n\nYou'\''re receiving this email because you'\''ve been an active member of the $Group.Name group. This group currently does not have an owner. \n\nPer your organization'\''s policy, the group requires an owner.\n\nThank you"
  }
}

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

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

{
  "@odata.type": "#microsoft.graph.ownerlessGroupPolicy",
  "isEnabled": true,
  "notificationDurationInWeeks": 3,
  "maxMembersToNotify": 40,
  "enabledGroupIds": [
    "b14e5eb2-a0a1-4c8f-b83e-940526219200",
    "454dde77-ac2b-421b-a6ab-165be910e0fc"
  ],
  "emailInfo": {
    "@odata.type": "microsoft.graph.emailDetails",
    "senderEmailAddress": "admin@contoso.com",
    "subject": "Need your help with $Group.Name group",
    "body": "Hi $User.DisplayName, \n\nYou'\''re receiving this email because you'\''ve been an active member of the $Group.Name group. This group currently does not have an owner. \n\nPer your organization'\''s policy, the group requires an owner.\n\nThank you"
  },
  "policyWebUrl": "https://contoso.com/policies/ownerless-groups",
  "targetOwners": {
    "@odata.type": "microsoft.graph.targetOwners",
    "notifyMembers": "allowSelected",
    "securityGroups": [
      "security-group1@contoso.com",
      "security-group2@contoso.com"
    ]
  }
}

Example 2: Disable the ownerless group policy

Request

The following example shows a request.

PATCH https://graph.microsoft.com/beta/policies/ownerlessGroupPolicy
Content-Type: application/json

{
  "isEnabled": false
}

Response

The following example shows the response.

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

{
  "@odata.type": "#microsoft.graph.ownerlessGroupPolicy",
  "isEnabled": false,
  "notificationDurationInWeeks": 0,
  "maxMembersToNotify": 0,
  "enabledGroupIds": [],
  "emailInfo": {
    "@odata.type": "microsoft.graph.emailDetails",
    "senderEmailAddress": "",
    "subject": "",
    "body": ""
  },
  "policyWebUrl": "",
  "targetOwners": {
    "@odata.type": "microsoft.graph.targetOwners",
    "notifyMembers": "all",
    "securityGroups": []
  }
}
  • Last updated on