Upsert group

Namespace: microsoft.graph

Create a new group object if it doesn't exist, or update the properties of an existing group object. You can create or update the following types of group:

  • Microsoft 365 group (unified group)
  • Security group

By default, this operation returns only a subset of the properties for each group. For a list of properties that are returned by default, see the Properties section of the group resource. To get properties that are not returned by default, do a GET operation and specify the properties in a $select OData query option.

Note: To create a team, first create a group then add a team to it. For more information, see Create team.

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 Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Group.ReadWrite.All Directory.ReadWrite.All

In order for an app with Group.Create permission to create a group with owners or members, it must have the privileges to read the object type that it wants to assign as the group owner or member. Therefore:

  • The app can assign itself as the group's owner or member.
  • To create the group with users as owners or members, the app must have at least the User.Read.All permission.
  • To create the group with other service principals as owners or members, the app must have at least the Application.Read.All permission.
  • To create the group with either users or service principals as owners or members, the app must have at least the Directory.Read.All permission.

HTTP request

PATCH /groups/(uniqueName='uniqueName')

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.
Prefer create-if-missing. Required for upsert behavior, otherwise the request is treated as an update operation.

Request body

In the request body, supply a JSON representation of the group object.

The following table lists the properties that are required when you create the group. Specify other writable properties as necessary for your group on creation or update.

Property Type Description
displayName String The name to display in the address book for the group. Maximum length is 256 characters. Required.
mailEnabled Boolean Set to true for mail-enabled groups. Required.
mailNickname String The mail alias for the group, unique for Microsoft 365 groups in the organization. Maximum length is 64 characters. This property can contain only characters in the ASCII character set 0 - 127 except the following: @ () \ [] " ; : <> , SPACE. Required.
securityEnabled Boolean Set to true for security-enabled groups, including Microsoft 365 groups. Required. Note: Groups created using the Microsoft Entra admin center or the Azure portal always have securityEnabled initially set to true.

Important

  • Creating a group using the Group.Create application permission without specifying owners will create the group anonymously and the group will not be modifiable. Add owners to the group while creating it to specify owners who can modify the group.
  • Creating a Microsoft 365 group programmatically with an app-only context and without specifying owners will create the group anonymously. Doing so can result in the associated SharePoint Online site not being created automatically until further manual action is taken.
  • A non-admin user can't add themselves to the group owners collection. For more information, see the related known issue.
  • The following properties can't be set in the initial POST request and must be set in a subsequent PATCH request: allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribedByMail, unseenCount.

Because the group resource supports extensions, you can add custom properties with your own data to the group while creating it.

groupTypes options

Use the groupTypes property to control the type of group and its membership, as shown.

Type of group Assigned membership Dynamic membership
Microsoft 365 (aka unified group) ["Unified"] ["Unified","DynamicMembership"]
Dynamic [] (null) ["DynamicMembership"]

Response

If an object with the uniqueName doesn't exist, this method returns a 201 Created response code and a new group object in the response body.

If an object with uniqueName doesn't exist and the Prefer: create-if-missing header is not specified, this method returns a 404 Not Found error code.

If an object with the uniqueName already exists, this method updates the group object and returns a 204 No Content response code.

Examples

Example 1: Create a Microsoft 365 group if it doesn't exist

The following example creates a Microsoft 365 group because a group with the specified uniqueName value does not exist. Because the owners have not been specified, the calling user is automatically added as the owner of the group.

Request

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
Content-type: application/json
Prefer: create-if-missing

{
  "description": "Self help community for golf",
  "displayName": "Golf Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "golfassist",
  "securityEnabled": false
}

Response

The following example shows the response. The value of the preferredDataLocation property is inherited from the group creator's preferred data location.

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

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2018-12-22T02:21:05Z",
    "description": "Self help community for golf",
    "displayName": "Golf Assist",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": null,
    "mail": "golfassist@contoso.com",
    "mailEnabled": true,
    "mailNickname": "golfassist",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "CAN",
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:golfassist@contoso.onmicrosoft.com"
    ],
    "renewedDateTime": "2018-12-22T02:21:05Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
    "theme": null,
    "visibility": "Public",
    "uniqueName": "uniqueName",
    "onPremisesProvisioningErrors": []
}

Example 2: Create a security group with an owner and members if it doesn't exist

The following example creates a security group with an owner and members specified because a group with the specified uniqueName value does not exist. Note that a maximum of 20 relationships, such as owners and members, can be added as part of group creation. You can subsequently add multiple additional members by using the add member API or JSON batching.

A non-admin user can't add themselves to the group owners collection. For more information, see the related known issue.

Request

The following example shows a request.

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
Content-Type: application/json

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
  ],
  "mailEnabled": false,
  "mailNickname": "operations2019",
  "securityEnabled": true,
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

Response

The following is an example of a successful response. It includes only default properties. You can subsequently get the owners or members navigation properties of the group to verify the owner or members. The value of the preferredDataLocation property is inherited from the group creator's preferred data location.

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

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/1226170d-83d5-49b8-99ab-d1ab3d91333e/Microsoft.DirectoryServices.Group",
    "id": "1226170d-83d5-49b8-99ab-d1ab3d91333e",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:14:44Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "infoCatalogs": [],
    "isAssignableToRole": null,
    "isManagementRestricted": null,
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "operations2019",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": null,
    "preferredLanguage": null,
    "proxyAddresses": [],
    "renewedDateTime": "2021-09-21T07:14:44Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-304486157-1236829141-2882644889-1043566909",
    "theme": null,
    "uniqueName": "uniqueName",
    "visibility": null,
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}

Example 3: Update an existing group

In this example, the specified group already exists, so the operation is treated as an update.

A non-admin user can't add themselves to the group owners collection. For more information, see the related known issue.

Request

The following example shows a request.

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": true,
    "mailEnabled": true,
    "securityEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

Response

The following example shows the response. The value of the preferredDataLocation property is inherited from the group creator's preferred data location.

HTTP/1.1 204 No Content