Namespace: microsoft.graph
Validate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display name or mail nickname is valid before trying to update a Microsoft 365 group. To validate the properties before creating a group, use the directoryobject:validateProperties function.
The following policy validations are performed for the display name and mail nickname properties:
- Validate the prefix and suffix naming policy
- Validate the custom banned words policy
This API only returns the first validation failure that is encountered. If the properties fail multiple validations, only the first validation failure is returned. However, you can validate both the mail nickname and the display name and receive a collection of validation errors if you are only validating the prefix and suffix naming policy. To learn more about configuring naming policies, see Configure naming policy.
This API is available in the following national cloud deployments.
| Global service |
US Government L4 |
US Government L5 (DOD) |
China operated by 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
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.Read.All |
Group.ReadWrite.All |
| Delegated (personal Microsoft account) |
Not supported. |
Not supported. |
| Application |
Group.Read.All |
Group.ReadWrite.All |
HTTP request
POST /groups/{id}/validateProperties
Request body
In the request body, provide a JSON object with the following parameters.
| Parameter |
Type |
Description |
| displayName |
String |
The display name of the group to validate. The property is not individually required. However, at least one property (displayName or mailNickname) is required. |
| mailNickname |
String |
The mail nickname of the group to validate. The property is not individually required. However, at least one property (displayName or mailNickname) is required. |
| onBehalfOfUserId |
Guid |
The ID of the user to impersonate when calling the API. The validation results are for the onBehalfOfUserId's attributes and roles. |
Response
If successful and there are no validation errors, the method returns 204 No Content response code. It doesn't return anything in the response body.
If the request is invalid, the method returns 400 Bad Request response code. An error message with details about the invalid request is returned in the response body.
If there is a validation error. The method returns 422 Unprocessable Entity response code. An error message and a collection of error details is returned in the response body.
Examples
Example 1: Successful validation request
This is an example of a successful validation request.
Request
POST https://graph.microsoft.com/v1.0/groups/{id}/validateProperties
Content-type: application/json
{
"displayName": "Myprefix_test_mysuffix",
"mailNickname": "Myprefix_test_mysuffix",
"onBehalfOfUserId": "onBehalfOfUserId-value"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Groups.Item.ValidateProperties;
var requestBody = new ValidatePropertiesPostRequestBody
{
DisplayName = "Myprefix_test_mysuffix",
MailNickname = "Myprefix_test_mysuffix",
OnBehalfOfUserId = Guid.Parse("onBehalfOfUserId-value"),
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Groups["{group-id}"].ValidateProperties.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
mgc groups validate-properties-by-id post --group-id {group-id} --body '{\
"displayName": "Myprefix_test_mysuffix",\
"mailNickname": "Myprefix_test_mysuffix",\
"onBehalfOfUserId": "onBehalfOfUserId-value"\
}\
'
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"
"github.com/google/uuid"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
//other-imports
)
requestBody := graphgroups.NewValidatePropertiesPostRequestBody()
displayName := "Myprefix_test_mysuffix"
requestBody.SetDisplayName(&displayName)
mailNickname := "Myprefix_test_mysuffix"
requestBody.SetMailNickname(&mailNickname)
onBehalfOfUserId := uuid.MustParse("onBehalfOfUserId-value")
requestBody.SetOnBehalfOfUserId(&onBehalfOfUserId)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Groups().ByGroupId("group-id").ValidateProperties().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.groups.item.validateproperties.ValidatePropertiesPostRequestBody validatePropertiesPostRequestBody = new com.microsoft.graph.groups.item.validateproperties.ValidatePropertiesPostRequestBody();
validatePropertiesPostRequestBody.setDisplayName("Myprefix_test_mysuffix");
validatePropertiesPostRequestBody.setMailNickname("Myprefix_test_mysuffix");
validatePropertiesPostRequestBody.setOnBehalfOfUserId(UUID.fromString("onBehalfOfUserId-value"));
graphClient.groups().byGroupId("{group-id}").validateProperties().post(validatePropertiesPostRequestBody);
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 validateProperties = {
displayName: 'Myprefix_test_mysuffix',
mailNickname: 'Myprefix_test_mysuffix',
onBehalfOfUserId: 'onBehalfOfUserId-value'
};
await client.api('/groups/{id}/validateProperties')
.post(validateProperties);
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\Groups\Item\ValidateProperties\ValidatePropertiesPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ValidatePropertiesPostRequestBody();
$requestBody->setDisplayName('Myprefix_test_mysuffix');
$requestBody->setMailNickname('Myprefix_test_mysuffix');
$requestBody->setOnBehalfOfUserId('onBehalfOfUserId-value');
$graphServiceClient->groups()->byGroupId('group-id')->validateProperties()->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.Groups
$params = @{
displayName = "Myprefix_test_mysuffix"
mailNickname = "Myprefix_test_mysuffix"
onBehalfOfUserId = "onBehalfOfUserId-value"
}
Test-MgGroupProperty -GroupId $groupId -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.groups.item.validate_properties.validate_properties_post_request_body import ValidatePropertiesPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ValidatePropertiesPostRequestBody(
display_name = "Myprefix_test_mysuffix",
mail_nickname = "Myprefix_test_mysuffix",
on_behalf_of_user_id = UUID("onBehalfOfUserId-value"),
)
await graph_client.groups.by_group_id('group-id').validate_properties.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
HTTP/1.1 204 No Content
Example 2: Request with validation errors
This is an example of a request with validation errors.
Request
POST https://graph.microsoft.com/v1.0/groups/{id}/validateProperties
Content-type: application/json
{
"displayName": "MyPrefix_test_mysuffix",
"mailNickname": "MyPrefix_test_mysuffix"
}
Response
HTTP/1.1 422
Content-type: application/json
{
"error": {
"code": "Request_UnprocessableEntity",
"message": "The values provided contain one or more validation errors.",
"innerError": {
"request-id": "id-value",
"date": "date-value"
},
"details": [
{
"target": "mailNickname",
"code": "PropertyConflict",
"message": "Another object with the same value for property mailNickname already exists."
}
]
}
}