Add a member
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.
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 |
To add a user, group, or device to an administrative unit, the calling principal must be assigned one of the following Azure AD roles:
- Privileged Role Administrator
- Global Administrator
Permissions to create a new group
Permission type | Permissions (from least to most privileged) |
---|---|
Delegated (work or school account) | Group.ReadWrite.All, Directory.ReadWrite.All, Directory.AccessAsUser.All |
Delegated (personal Microsoft account) | Not supported. |
Application | Group.Create, Group.ReadWrite.All, Directory.ReadWrite.All |
To create a new group in an administrative unit, the calling principal must be assigned one of the following Azure AD roles:
- Privileged Role Administrator
- Global Administrator
- Groups Administrator
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 headers
Name | Description |
---|---|
Authorization | Bearer {token}. Required. |
Content-type | application/json. Required. |
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 an Azure AD role. Only Privileged Role Administrator and Global Administrator can 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 does not 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 is an example of the 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}"
}
In the request body, provide the id
of the user or group object you want to add.
Response
The following is an example of 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 is an example of the 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
}
In the request body, provide the properties of the group object you want to add.
Response
The following is an example of 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": "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",
"onPremisesProvisioningErrors": []
}
Feedback
Submit and view feedback for