Add members

Article
02/11/2025

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

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

Name	Description
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 members@odata.bind 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.

Example

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/beta/groups/{group-id}/members/$ref
Content-type: application/json

{
  "@odata.id": "https://graph.microsoft.com/beta/directoryObjects/{id}"
}


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

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new ReferenceCreate
{
	OdataId = "https://graph.microsoft.com/beta/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);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



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

Important

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 $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewReferenceCreate()
odataId := "https://graph.microsoft.com/beta/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)

Important

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.beta.models.ReferenceCreate referenceCreate = new com.microsoft.graph.beta.models.ReferenceCreate();
referenceCreate.setOdataId("https://graph.microsoft.com/beta/directoryObjects/{id}");
graphClient.groups().byGroupId("{group-id}").members().ref().post(referenceCreate);

Important

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

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

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\ReferenceCreate;


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

$requestBody = new ReferenceCreate();
$requestBody->setOdataId('https://graph.microsoft.com/beta/directoryObjects/{id}');

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

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Groups

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

New-MgBetaGroupMemberByRef -GroupId $groupId -BodyParameter $params

Important

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_beta import GraphServiceClient
from msgraph_beta.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/beta/directoryObjects/{id}",
)

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

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

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/beta/groups/{group-id}
Content-type: application/json

{
  "members@odata.bind": [
    "https://graph.microsoft.com/beta/directoryObjects/{id}",
    "https://graph.microsoft.com/beta/directoryObjects/{id}",
    "https://graph.microsoft.com/beta/directoryObjects/{id}"
    ]
}


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

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new Group
{
	AdditionalData = new Dictionary<string, object>
	{
		{
			"members@odata.bind" , new List<string>
			{
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/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);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta groups patch --group-id {group-id} --body '{\
  "members@odata.bind": [\
    "https://graph.microsoft.com/beta/directoryObjects/{id}",\
    "https://graph.microsoft.com/beta/directoryObjects/{id}",\
    "https://graph.microsoft.com/beta/directoryObjects/{id}"\
    ]\
}\
'

Important

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 $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

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

Important

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 group = new Group();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);

Important

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 group = {
  'members@odata.bind': [
    'https://graph.microsoft.com/beta/directoryObjects/{id}',
    'https://graph.microsoft.com/beta/directoryObjects/{id}',
    'https://graph.microsoft.com/beta/directoryObjects/{id}'
    ]
};

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

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


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


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

$requestBody = new Group();
$additionalData = [
	'members@odata.bind' => [
'https://graph.microsoft.com/beta/directoryObjects/{id}', 'https://graph.microsoft.com/beta/directoryObjects/{id}', 'https://graph.microsoft.com/beta/directoryObjects/{id}', ],
];
$requestBody->setAdditionalData($additionalData);

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

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Groups

$params = @{
	"members@odata.bind" = @(
	"https://graph.microsoft.com/beta/directoryObjects/{id}"
"https://graph.microsoft.com/beta/directoryObjects/{id}"
"https://graph.microsoft.com/beta/directoryObjects/{id}"
)
}

Update-MgBetaGroup -GroupId $groupId -BodyParameter $params

Important

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_beta import GraphServiceClient
from msgraph_beta.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/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
				"https://graph.microsoft.com/beta/directoryObjects/{id}",
			],
	}
)

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

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

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

Example

Example 1: Add a member to a group

Request

Response

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

Request

Response

Feedback

Additional resources

Share via

Add members

Permissions

HTTP request

Request headers

Request body

Response

Example

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