title	Add members
description	Add a member to a Microsoft 365 or security group through the members navigation property.
ms.localizationpriority	high
author	yuhko-msft
ms.reviewer	mbhargav, khotzteam, aadgroupssg
ms.subservice	entra-groups
doc_type	apiPageType
ms.date	09/09/2025

Add members

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.

[!INCLUDE groups-allowed-member-types]

[!INCLUDE national-cloud-support]

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.Read.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}

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} 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.

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.

HTTP

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}"
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE 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.

HTTP

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

{
  "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}"
    ]
}