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.
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.
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.
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
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
Description = "Self help community for golf",
DisplayName = "Golf Assist",
GroupTypes = new List<string>
{
"Unified",
},
MailEnabled = true,
MailNickname = "golfassist",
SecurityEnabled = false,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.GroupsWithUniqueName("{uniqueName}").PatchAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "create-if-missing");
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
group.setDescription("Self help community for golf");
group.setDisplayName("Golf Assist");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("golfassist");
group.setSecurityEnabled(false);
Group result = graphClient.groupsWithUniqueName("{uniqueName}").patch(group, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "create-if-missing");
});
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.
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.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
Description = "Group with designated owner and members",
DisplayName = "Operations group",
GroupTypes = new List<string>
{
},
MailEnabled = false,
MailNickname = "operations2019",
SecurityEnabled = true,
AdditionalData = new Dictionary<string, object>
{
{
"owners@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2",
}
},
{
"members@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
"https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.GroupsWithUniqueName("{uniqueName}").PatchAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
group.setDescription("Group with designated owner and members");
group.setDisplayName("Operations group");
LinkedList<String> groupTypes = new LinkedList<String>();
group.setGroupTypes(groupTypes);
group.setMailEnabled(false);
group.setMailNickname("operations2019");
group.setSecurityEnabled(true);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> ownersOdataBind = new LinkedList<String>();
ownersOdataBind.add("https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2");
additionalData.put("owners@odata.bind", ownersOdataBind);
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc");
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groupsWithUniqueName("{uniqueName}").patch(group);
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.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
Description = "Group assignable to a role",
DisplayName = "Role assignable group",
GroupTypes = new List<string>
{
"Unified",
},
IsAssignableToRole = true,
MailEnabled = true,
SecurityEnabled = true,
MailNickname = "contosohelpdeskadministrators",
AdditionalData = new Dictionary<string, object>
{
{
"owners@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e",
}
},
{
"members@odata.bind" , new List<string>
{
"https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
"https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
group.setDescription("Group assignable to a role");
group.setDisplayName("Role assignable group");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
group.setGroupTypes(groupTypes);
group.setIsAssignableToRole(true);
group.setMailEnabled(true);
group.setSecurityEnabled(true);
group.setMailNickname("contosohelpdeskadministrators");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> ownersOdataBind = new LinkedList<String>();
ownersOdataBind.add("https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e");
additionalData.put("owners@odata.bind", ownersOdataBind);
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0");
membersOdataBind.add("https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().post(group);
The following example shows the response. The value of the preferredDataLocation property is inherited from the group creator's preferred data location.
Tulossa pian: Vuoden 2024 aikana poistamme asteittain GitHub Issuesin käytöstä sisällön palautemekanismina ja korvaamme sen uudella palautejärjestelmällä. Lisätietoja on täällä: https://aka.ms/ContentUserFeedback.