title | description | author | ms.localizationpriority | ms.subservice | doc_type |
---|---|---|---|---|---|
Create administrativeUnit |
Use this API to create a new administrativeUnit. |
DougKirschner |
medium |
entra-directory-management |
apiPageType |
Namespace: microsoft.graph
[!INCLUDE beta-disclaimer]
Use this API to create a new administrativeUnit.
[!INCLUDE national-cloud-support]
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.
[!INCLUDE permissions-table]
In delegated scenarios, the signed-in user must also be assigned a supported Microsoft Entra role or a custom role with the microsoft.directory/administrativeUnits/allProperties/allTasks
role permission. Privileged Role Administrator is the least privileged role for this operation.
POST /administrativeUnits
POST /directory/administrativeUnits
Name | Description |
---|---|
Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
Content-type | application/json. Required. |
In the request body, supply a JSON representation of an administrativeUnit object.
You can specify the following properties when creating an administrativeUnit.
Property | Type | Description |
---|---|---|
description | String | Description for the administrative unit. Optional. |
displayName | String | Display name for the administrative unit. Required. |
isMemberManagementRestricted | Boolean | true if members of this administrative unit should be treated as sensitive, which requires specific permissions to manage. Default value is false . Use this property to define administrative units whose roles don't inherit from tenant-level administrators, and management of individual member objects is limited to administrators scoped to a restricted management administrative unit. Immutable, so can't be changed later. Optional. |
membershipRule | String | Dynamic membership rule for the administrative unit. For more about the rules that you can use for dynamic administrative units and dynamic groups, see Using attributes to create advanced rules. Optional. |
membershipRuleProcessingState | String | Used to control whether the dynamic membership rule is actively processed. Set to On when you want the dynamic membership rule to be active and Paused if you want to stop updating membership dynamically. Optional. |
membershipType | String | Membership type for the administrative unit. Can be dynamic or assigned . Optional. |
visibility | String | Visibility for the administrative unit. If not set, then the default is public . Can be set to HiddenMembership , which hides the membership from non-members. Optional. |
Because the administrativeUnit resource supports extensions, you can use the POST
operation and add custom properties with your own data to the administrative unit while creating it.
If successful, this method returns a 201 Created
response code and an administrativeUnit object in the response body.
The following example creates a new administrative unit with a dynamic membership rule to include all users whose country is United States.
POST https://graph.microsoft.com/beta/administrativeUnits
Content-type: application/json
{
"displayName": "Seattle District Technical Schools",
"description": "Seattle district technical schools administration",
"membershipType": "Dynamic",
"membershipRule": "(user.country -eq \"United States\")",
"membershipRuleProcessingState": "On"
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
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/beta/$metadata#administrativeUnits/$entity",
"id": "49eb93f2-a5a2-4567-ad66-76a3ebd01d84",
"deletedDateTime": null,
"displayName": "Seattle District Technical Schools",
"description": "Seattle district technical schools administration",
"membershipRule": "(user.country -eq \"United States\")",
"membershipType": "Dynamic",
"membershipRuleProcessingState": "On"
}
The following example creates a new restricted management administrative unit. The isMemberManagementRestricted
property is immutable, so can't be changed later.
POST https://graph.microsoft.com/beta/administrativeUnits
Content-type: application/json
{
"displayName": "Executive Division",
"description": "Executive division administration",
"isMemberManagementRestricted": true
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
In the request body, supply a JSON representation of an administrativeUnit object.
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/beta/$metadata#administrativeUnits/$entity",
"id": "2sd35b05-ae71-48ab-9e7d-4r41a28te37d",
"deletedDateTime": null,
"displayName": "Executive Division",
"description": "Executive division administration",
"isMemberManagementRestricted": true
}