Add members

Article
2025-02-05

Namespace: microsoft.graph

Add a member to a security or Microsoft 365 group. When using the API to add multiple members in one request, you can add up to only 20 members.

The following table shows the types of members that can be added to either security groups or Microsoft 365 groups.

Object type	Member of security group	Member of Microsoft 365 group
User
Security group
Microsoft 365 group
Device
Service principal
Organizational contact

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

The following table shows the least privileged permission that's required by each resource type when calling this API. To learn more, including how to choose permissions, see Permissions.

Supported resource	Delegated (work or school account)	Delegated (personal Microsoft account)	Application
device	GroupMember.ReadWrite.All and Device.ReadWrite.All	Not supported.	GroupMember.ReadWrite.All and Device.ReadWrite.All
group	GroupMember.ReadWrite.All	Not supported.	GroupMember.ReadWrite.All
orgContact	GroupMember.ReadWrite.All and OrgContact.Read.All	Not supported.	GroupMember.ReadWrite.All and OrgContact.Read.All
servicePrincipal	GroupMember.ReadWrite.All and Application.ReadWrite.All	Not supported.	GroupMember.ReadWrite.All and Application.ReadWrite.All
user	GroupMember.ReadWrite.All	Not supported.	GroupMember.ReadWrite.All

Important

In delegated scenarios, the signed-in user must also be assigned a supported Microsoft Entra role or a custom role with the microsoft.directory/groups/members/update role permission. The following roles are the least privileged roles that are supported for this operation, except for role-assignable groups:

Group owners
Directory Writers
Groups Administrator
Identity Governance Administrator
User Administrator
Exchange Administrator - only for Microsoft 365 groups
SharePoint Administrator - only for Microsoft 365 groups
Teams Administrator - only for Microsoft 365 groups
Yammer Administrator - only for Microsoft 365 groups
Intune Administrator - only for security groups

To add members to a role-assignable group, the app must also be assigned the RoleManagement.ReadWrite.Directory permission and the calling user must be assigned a supported Microsoft Entra role. Privileged Role Administrator is the least privileged role that is supported for this operation.

HTTP request

POST /groups/{group-id}/members/$ref
PATCH /groups/{group-id}/members

Request headers

Header	Value
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.
Content-type	application/json. Required.

Request body

When using the POST /groups/{group-id}/members/$ref syntax, supply a JSON object that contains an @odata.id property with a reference by ID to a supported group member object type.

When using the PATCH /groups/{group-id}/members syntax, supply a JSON object that contains a [email protected] property with one or more references by IDs to a supported group member object type. That is:

For Microsoft 365 groups, only https://graph.microsoft.com/v1.0/directoryObjects/{id} and https://graph.microsoft.com/v1.0/groups/{id} is allowed where {id} must be a user because only users can members of Microsoft 365 groups.
For security groups, the following ID references are allowed:
- https://graph.microsoft.com/v1.0/directoryObjects/{id} where {id} must belong to a user, security group, device, service principal, or organizational contact.
- https://graph.microsoft.com/v1.0/groups/{id} where {id} must belong to another security group. Microsoft 365 groups can't be members of security groups.
- https://graph.microsoft.com/v1.0/devices/{id} where {id} belongs to a device.
- https://graph.microsoft.com/v1.0/servicePrincipal/{id} where {id} belongs to a service principal.
- https://graph.microsoft.com/v1.0/orgContact/{id} where {id} belongs to an organizational contact.

Response

If successful, this method returns a 204 No Content response code. It returns a 400 Bad Request response code when the object is already a member of the group or is unsupported as a group member. It returns a 404 Not Found response code when the object being added doesn't exist. It returns 403 Unauthorized in one of the following scenarios:

You're attempting to add a member to a group that can't be managed through Microsoft Graph. This API supports only security and Microsoft 365 groups.
You're attempting to add a member you don't have permissions to add. Refer to the preceding Permissions section for the permissions required to add different member types.
You're attempting to add a member to a role-assignable group and you don't have the required permissions.

Examples

Example 1: Add a member to a group

Request

The following example shows a request that uses the directoryObjects reference to add a member to a group.

POST https://graph.microsoft.com/v1.0/groups/{group-id}/members/$ref
Content-type: application/json

{
  "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{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/directoryObjects/{id}",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Groups["{group-id}"].Members.Ref.PostAsync(requestBody);



mgc groups members ref post --group-id {group-id} --body '{\
  "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{id}"\
}\
'



// 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/directoryObjects/{id}"
requestBody.SetOdataId(&odataId) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Groups().ByGroupId("group-id").Members().Ref().Post(context.Background(), requestBody, nil)


// 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/directoryObjects/{id}");
graphClient.groups().byGroupId("{group-id}").members().ref().post(referenceCreate);


const options = {
	authProvider,
};

const client = Client.init(options);

const directoryObject = {
  '@odata.id': 'https://graph.microsoft.com/v1.0/directoryObjects/{id}'
};

await client.api('/groups/{group-id}/members/$ref')
	.post(directoryObject);


<?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/directoryObjects/{id}');

$graphServiceClient->groups()->byGroupId('group-id')->members()->ref()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Groups

$params = @{
	"@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
}

New-MgGroupMemberByRef -GroupId $groupId -BodyParameter $params


# 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/directoryObjects/{id}",
)

await graph_client.groups.by_group_id('group-id').members.ref.post(request_body)

Response

The following example shows the response.

HTTP/1.1 204 No Content

Example 2: Add multiple members to a group in a single request

This example shows how to add multiple members to a group with OData bind support in a PATCH operation. Up to 20 members can be added in a single request. If an error condition exists in the request body, no members are added and the appropriate response code is returned.

Request

The following example shows a request.

PATCH https://graph.microsoft.com/v1.0/groups/{group-id}
Content-type: application/json

{
  "[email protected]": [
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}"
    ]
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	AdditionalData = new Dictionary<string, object>
	{
		{
			"[email protected]" , new List<string>
			{
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
			}
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);



mgc groups patch --group-id {group-id} --body '{\
  "[email protected]": [\
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",\
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}",\
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}"\
    ]\
}\
'



// 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.NewGroup()
additionalData := map[string]interface{}{
	odataBind := []string {
		"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
		"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
		"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
	}
}
requestBody.SetAdditionalData(additionalData)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().ByGroupId("group-id").Patch(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Group group = new Group();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/v1.0/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/v1.0/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/v1.0/directoryObjects/{id}");
additionalData.put("[email protected]", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);


const options = {
	authProvider,
};

const client = Client.init(options);

const group = {
  '[email protected]': [
    'https://graph.microsoft.com/v1.0/directoryObjects/{id}',
    'https://graph.microsoft.com/v1.0/directoryObjects/{id}',
    'https://graph.microsoft.com/v1.0/directoryObjects/{id}'
    ]
};

await client.api('/groups/{group-id}')
	.update(group);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Group();
$additionalData = [
	'[email protected]' => [
'https://graph.microsoft.com/v1.0/directoryObjects/{id}', 'https://graph.microsoft.com/v1.0/directoryObjects/{id}', 'https://graph.microsoft.com/v1.0/directoryObjects/{id}', ],
];
$requestBody->setAdditionalData($additionalData);

$result = $graphServiceClient->groups()->byGroupId('group-id')->patch($requestBody)->wait();


Import-Module Microsoft.Graph.Groups

$params = @{
	"[email protected]" = @(
	"https://graph.microsoft.com/v1.0/directoryObjects/{id}"
"https://graph.microsoft.com/v1.0/directoryObjects/{id}"
"https://graph.microsoft.com/v1.0/directoryObjects/{id}"
)
}

Update-MgGroup -GroupId $groupId -BodyParameter $params


# 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(
	additional_data = {
			"members@odata_bind" : [
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
				"https://graph.microsoft.com/v1.0/directoryObjects/{id}",
			],
	}
)

result = await graph_client.groups.by_group_id('group-id').patch(request_body)

In the request body, supply a JSON representation of the id of the directoryObject, user, or group object you want to add.

Response

The following example shows the response.

HTTP/1.1 204 No Content

Share via

Add members

Permissions

HTTP request

Request headers

Request body

Response

Examples

Example 1: Add a member to a group

Request

Response

Example 2: Add multiple members to a group in a single request

Request

Response

Related content

Feedback

Additional resources