Namespace: microsoft.graph
Use this API to add a member (user, group, or device) to an administrative unit. Currently it's only possible to add one member at a time to an administrative unit.
This API is available in the following national cloud deployments.
| Global service |
US Government L4 |
US Government L5 (DOD) |
China operated by 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.
Permissions to add an existing user, group, or device
| Permission type |
Permissions (from least to most privileged) |
| Delegated (work or school account) |
AdministrativeUnit.ReadWrite.All |
| Delegated (personal Microsoft account) |
Not supported. |
| Application |
AdministrativeUnit.ReadWrite.All |
Important
In delegated scenarios with work or school accounts, the signed-in user must be a member user or be assigned a supported Microsoft Entra role or a custom role with a supported role permission. Privileged Role Administrator is the least privileged role supported for this operation.
Permissions to create a new group
| Permission type |
Permissions (from least to most privileged) |
| Delegated (work or school account) |
Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All |
| Delegated (personal Microsoft account) |
Not supported. |
| Application |
Group.Create and AdministrativeUnit.Read.All, Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All |
Important
To create a new group in an administrative unit, the calling principal must be assigned at least one of the following Microsoft Entra roles at the scope of the administrative unit:
- Groups Administrator
- User Administrator
For app-only scenarios - apart from these roles, the service principal requires additional permissions to read the directory. These permissions can be granted via assignment of supported Microsoft Entra roles, such the Directory Readers role; or they can be granted via Microsoft Graph application permissions that allow reading the directory, such as Directory.Read.All.
HTTP request
The following request adds an existing user, group, or device to the administrative unit.
POST /directory/administrativeUnits/{id}/members/$ref
The following request creates a new group within the administrative unit.
POST /directory/administrativeUnits/{id}/members
Request body
Adding an existing user, group, or device
In the request body, provide the id of a user, group, device, or directoryObject to be added.
Creating a new group
The following table shows the properties of the group resource to specify when you create a group in the administrative unit.
| Property |
Type |
Description |
| displayName |
string |
The name to display in the address book for the group. Required. |
| description |
string |
A description for the group. Optional. |
| isAssignableToRole |
Boolean |
Set to true to enable the group to be assigned to a Microsoft Entra role. Privileged Role Administrator is the least privileged role to set the value of this property. Optional. |
| mailEnabled |
Boolean |
Set to true for mail-enabled groups. Required. |
| mailNickname |
string |
The mail alias for the group. These characters cannot be used in the mailNickName: @()\[]";:.<>,SPACE. Required. |
| securityEnabled |
Boolean |
Set to true for security-enabled groups, including Microsoft 365 groups. Required. |
| owners |
directoryObject collection |
This property represents the owners for the group at creation time. Optional. |
| members |
directoryObject collection |
This property represents the members for the group at creation time. Optional. |
| visibility |
String |
Specifies the visibility of a Microsoft 365 group. Possible values are: Private, Public, HiddenMembership, or empty (which is interpreted as Public). |
Response
If successful, adding an existing object (using $ref) returns 204 No Content response code. It doesn't return anything in the response body.
When creating a new group (without $ref), this method returns a 201 Created response code and a group object in the response body. The response includes only the default properties of the group. You must supply the "@odata.type" : "#microsoft.graph.group" line in the request body to explicitly identify the new member as a group. A request body without the correct @odata.type returns a 400 Bad Request error message.
Examples
Example 1: Add an existing user or group
The following request adds an existing user or group to an administrative unit.
Request
The following example shows a request.
POST https://graph.microsoft.com/v1.0/directory/administrativeUnits/{id}/members/$ref
Content-type: application/json
{
"@odata.id":"https://graph.microsoft.com/v1.0/groups/{id}"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ReferenceCreate
{
OdataId = "https://graph.microsoft.com/v1.0/groups/{id}",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Directory.AdministrativeUnits["{administrativeUnit-id}"].Members.Ref.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
mgc directory administrative-units members ref post --administrative-unit-id {administrativeUnit-id} --body '{\
"@odata.id":"https://graph.microsoft.com/v1.0/groups/{id}"\
}\
'
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewReferenceCreate()
odataId := "https://graph.microsoft.com/v1.0/groups/{id}"
requestBody.SetOdataId(&odataId)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Directory().AdministrativeUnits().ByAdministrativeUnitId("administrativeUnit-id").Members().Ref().Post(context.Background(), requestBody, nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.models.ReferenceCreate referenceCreate = new com.microsoft.graph.models.ReferenceCreate();
referenceCreate.setOdataId("https://graph.microsoft.com/v1.0/groups/{id}");
graphClient.directory().administrativeUnits().byAdministrativeUnitId("{administrativeUnit-id}").members().ref().post(referenceCreate);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
const directoryObject = {
'@odata.id':'https://graph.microsoft.com/v1.0/groups/{id}'
};
await client.api('/directory/administrativeUnits/{id}/members/$ref')
.post(directoryObject);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ReferenceCreate;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ReferenceCreate();
$requestBody->setOdataId('https://graph.microsoft.com/v1.0/groups/{id}');
$graphServiceClient->directory()->administrativeUnits()->byAdministrativeUnitId('administrativeUnit-id')->members()->ref()->post($requestBody)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Identity.DirectoryManagement
$params = @{
"@odata.id" = "https://graph.microsoft.com/v1.0/groups/{id}"
}
New-MgDirectoryAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.reference_create import ReferenceCreate
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ReferenceCreate(
odata_id = "https://graph.microsoft.com/v1.0/groups/{id}",
)
await graph_client.directory.administrative_units.by_administrative_unit_id('administrativeUnit-id').members.ref.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
In the request body, provide the id of the user or group object you want to add.
Response
The following example shows the response.
HTTP/1.1 204 No Content
Example 2: Create a new group
The following example creates a new group in the administrative unit. You must supply the "@odata.type" : "#microsoft.graph.group" line in the request body to explicitly identify the new member as a group. A request body without the correct @odata.type returns a 400 Bad Request error message.
Request
The following example shows a request.
POST https://graph.microsoft.com/v1.0/directory/administrativeUnits/{id}/members
Content-type: application/json
{
"@odata.type": "#microsoft.graph.group",
"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
{
OdataType = "#microsoft.graph.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.Directory.AdministrativeUnits["{administrativeUnit-id}"].Members.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
mgc directory administrative-units members create --administrative-unit-id {administrativeUnit-id} --body '{\
"@odata.type": "#microsoft.graph.group",\
"description": "Self help community for golf",\
"displayName": "Golf Assist",\
"groupTypes": [\
"Unified"\
],\
"mailEnabled": true,\
"mailNickname": "golfassist",\
"securityEnabled": false\
}\
'
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewDirectoryObject()
description := "Self help community for golf"
requestBody.SetDescription(&description)
displayName := "Golf Assist"
requestBody.SetDisplayName(&displayName)
groupTypes := []string {
"Unified",
}
requestBody.SetGroupTypes(groupTypes)
mailEnabled := true
requestBody.SetMailEnabled(&mailEnabled)
mailNickname := "golfassist"
requestBody.SetMailNickname(&mailNickname)
securityEnabled := false
requestBody.SetSecurityEnabled(&securityEnabled)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
members, err := graphClient.Directory().AdministrativeUnits().ByAdministrativeUnitId("administrativeUnit-id").Members().Post(context.Background(), requestBody, nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group directoryObject = new Group();
directoryObject.setOdataType("#microsoft.graph.group");
directoryObject.setDescription("Self help community for golf");
directoryObject.setDisplayName("Golf Assist");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
directoryObject.setGroupTypes(groupTypes);
directoryObject.setMailEnabled(true);
directoryObject.setMailNickname("golfassist");
directoryObject.setSecurityEnabled(false);
DirectoryObject result = graphClient.directory().administrativeUnits().byAdministrativeUnitId("{administrativeUnit-id}").members().post(directoryObject);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
const directoryObject = {
'@odata.type': '#microsoft.graph.group',
description: 'Self help community for golf',
displayName: 'Golf Assist',
groupTypes: [
'Unified'
],
mailEnabled: true,
mailNickname: 'golfassist',
securityEnabled: false
};
await client.api('/directory/administrativeUnits/{id}/members')
.post(directoryObject);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Group();
$requestBody->setOdataType('#microsoft.graph.group');
$requestBody->setDescription('Self help community for golf');
$requestBody->setDisplayName('Golf Assist');
$requestBody->setGroupTypes(['Unified', ]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('golfassist');
$requestBody->setSecurityEnabled(false);
$result = $graphServiceClient->directory()->administrativeUnits()->byAdministrativeUnitId('administrativeUnit-id')->members()->post($requestBody)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Identity.DirectoryManagement
$params = @{
"@odata.type" = "#microsoft.graph.group"
description = "Self help community for golf"
displayName = "Golf Assist"
groupTypes = @(
"Unified"
)
mailEnabled = $true
mailNickname = "golfassist"
securityEnabled = $false
}
New-MgDirectoryAdministrativeUnitMember -AdministrativeUnitId $administrativeUnitId -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Group(
odata_type = "#microsoft.graph.group",
description = "Self help community for golf",
display_name = "Golf Assist",
group_types = [
"Unified",
],
mail_enabled = True,
mail_nickname = "golfassist",
security_enabled = False,
)
result = await graph_client.directory.administrative_units.by_administrative_unit_id('administrativeUnit-id').members.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
In the request body, provide the properties of the group object you want to add.
Response
The following example shows the response.
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": "[email protected]",
"mailEnabled": true,
"mailNickname": "golfassist",
"membershipRule": null,
"membershipRuleProcessingState": null,
"onPremisesLastSyncDateTime": null,
"onPremisesSecurityIdentifier": null,
"onPremisesSyncEnabled": null,
"preferredDataLocation": "CAN",
"preferredLanguage": null,
"proxyAddresses": [
"SMTP:[email protected]"
],
"renewedDateTime": "2018-12-22T02:21:05Z",
"resourceBehaviorOptions": [],
"resourceProvisioningOptions": [],
"securityEnabled": false,
"securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
"theme": null,
"visibility": "Public",
"onPremisesProvisioningErrors": []
}