Operations on groups | Graph API reference

Article
02/26/2016

Applies to: Graph API | Azure Active Directory

This topic discusses how to perform operations on groups using the Azure Active Directory (AD) Graph API. With the Azure AD Graph API, you can create, read, update, and delete groups. You can also query members of a group, add and delete members from a group, check a group's membership in other groups, assign app roles to a group, and much more. Some group operations are transitive and others are scoped only to direct members of the group. Support for some operations varies between security groups, mail distribution groups, and mail-enabled security groups. Groups may have users, contacts, and other groups as members.

The Graph API is an OData 3.0 compliant REST API that provides programmatic access to directory objects in Azure Active Directory, such as users, groups, organizational contacts, and applications.

This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see Working with groups in Microsoft Graph.

Caution

Azure Active Directory (Azure AD) Graph is deprecated and is currently in its retirement path. We recommend that you migrate your apps to Microsoft Graph.

To start migrating your apps, see Migrate your apps from Azure AD Graph to Microsoft Graph.
For the latest announcement, see Important: Azure AD Graph Retirement.

Performing REST operations on groups

To perform operations on groups with the Graph API, you send HTTP requests with a supported method (GET, POST, PATCH, PUT, or DELETE) to an endpoint that targets the groups resource collection, a specific group, a navigation property of a group or a function or action that can be called on a group. The following sections discuss how to target and compose operations on groups.

Graph API requests use the following basic URL:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}[odata_query_parameters]

Important

Requests sent to the Graph API must be well-formed, target a valid endpoint and version of the Graph API, and carry a valid access token obtained from Azure AD in their Authorization header. For more detailed information about creating requests and receiving responses with the Graph API, see Operations Overview.

You specify the {resource_path} differently depending on whether you are targeting the collection of all groups in your tenant, an individual group, or a navigation property of a specific group.

/groups targets the group resource collection. You can use this resource path to read all groups in your tenant or to create new security groups in your tenant.
/groups/{object_id} targets an individual group in your tenant. You specify the target group with its object ID (GUID). You can use this resource path to get the declared properties of a group, to modify the declared properties of a group, or to delete a security group.
/group/{object_id}/{nav_property} targets the specified navigation property of a group. You can use it to return the object or objects referenced by the target navigation property of the specified group; for example, the group's members. Note: This form of addressing is only available for reads.
/groups/{object_id}/$links/{nav_property} targets the specified navigation property of a group. You can use this form of addressing to both read and modify a navigation property. On reads, the objects referenced by the property are returned as one or more links in the response body. On writes, the objects are specified as one or more links in the request body.

For example, the following request returns a a collection of links to the members of the specified group :

GET https://graph.windows.net/myorganization/groups/ffffffff-ffff-ffff-ffff-ffffffffffff/$links/members?api-version=1.6

Basic operations on groups

You can perform basic create, read, update, and delete (CRUD) operations on groups and their declared properties by targeting either the group resource collection or a specific group. The following topics show you how.

The Graph API supports operations on groups as follows:

Create (POST): security groups only.
Read (GET): all groups.
Update (PATCH): security groups and mail-enabled security groups. Not all properties are supported.
Delete (DELETE): security groups only.

Get groups

Gets a collection of groups. You can add OData query parameters to the request to sort, and page the response. For more information, see Supported Queries, Filters, and Paging Options.

On success, returns a collection of Group objects; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

GET https://graph.windows.net/myorganization/groups?api-version

Parameters

Parameter	Type	Value	Notes
Query
api-version	string	1.6	The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Group",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "c57cdc98-0dcd-4f90-a82f-c911b288bab9",
      "deletionTimestamp": null,
      "description": "Marketing Group",
      "dirSyncEnabled": null,
      "displayName": "Marketing",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "cdf76b17-0734-41bc-9c24-9a7af93f3502",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "cc9869f0-6ac0-4d00-bc24-621a2d949d35",
      "deletionTimestamp": null,
      "description": "Engineering Group",
      "dirSyncEnabled": null,
      "displayName": "Engineering",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "ef3b8cc1-721b-4452-9e30-9867d1de80ea",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "fc15e7ef-993f-4865-bf37-317d9b8017b8",
      "deletionTimestamp": null,
      "description": "Test Group",
      "dirSyncEnabled": null,
      "displayName": "Test",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "fec6273a-20af-49ba-8129-3cbde45a0a16",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    }
  ]
}

Response List

Status Code	Description
200	OK. Indicates success. The results are returned in the response body.

Code Samples

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
	    static void Main()
        {
            MakeRequest();

            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }

        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            /* OAuth2 is required to access this API. For more information visit:
               https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */



		   // Specify values for the following required parameters
			queryString["api-version"] = "1.6";
            // Specify values for path parameters (shown as {...})
            var uri = "https://graph.windows.net/myorganization/groups?" + queryString;


            var response = await client.GetAsync(uri);

            if (response.Content != null)
            {
                var responseString = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseString);
            }
        }
    }
}

@ECHO OFF

REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/groups?api-version=1.6&amp;"^

// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample {

  public static void main(String[] args) {
	HttpClient httpclient = HttpClients.createDefault();

	try
	{
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		// Specify values for path parameters (shown as {...})
		URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/groups");
		// Specify values for the following required parameters
		builder.setParameter("api-version", "1.6");
		URI uri = builder.build();
		HttpGet request = new HttpGet(uri);
		HttpResponse response = httpclient.execute(request);
		HttpEntity entity = response.getEntity();
		if (entity != null) {
			System.out.println(EntityUtils.toString(entity));
		}
	}
	catch (Exception e)
	{
		System.out.println(e.getMessage());
	}
  }
}

<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
	$(function() {
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		var params = {
			// Specify values for the following required parameters
			'api-version': "1.6",
		};
		
		$.ajax({
			// Specify values for path parameters (shown as {...})
			url: 'https://graph.windows.net/myorganization/groups?' + $.param(params),
			type: 'GET',
		})
		.done(function(data) {
			alert("success");
		})
		.fail(function() {
			alert("error");
		});
	});
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
	// OAuth2 is required to access this API. For more information visit:
	// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

	// Specify values for path parameters (shown as {...})
    NSString* path = @"https://graph.windows.net/myorganization/groups";
    NSArray* array = @[
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];
    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
    if(nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if(nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];
    return 0;
}

<?php

// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);

$query_params = array(
	// Specify values for the following required parameters
	'api-version' => '1.6',
);

$request = new Http_Request2('https://graph.windows.net/myorganization/groups');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);

// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

$url = $request->getUrl();
$url->setQueryVariables($query_params);

try
{
	$response = $request->send();
	
	echo $response->getBody();
}
catch (HttpException $ex)
{
	echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = httplib.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.parse.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = http.client.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

require 'net/http'

uri = URI('https://graph.windows.net/myorganization/groups')

uri.query = URI.encode_www_form({
	# Specify values for the following required parameters
	'api-version' => '1.6',
})

request = Net::HTTP::Get.new(uri.request_uri)

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks



response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body

Get a group

Gets a specified group. Specify the group by its object ID (GUID).

On success, returns the Group object for the specified group; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

GET https://graph.windows.net/myorganization/groups/{object_id}?api-version

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	f795caea-121d-49c7-8ae6-a95623add8aa	The object ID (GUID) of the target group.
Query
api-version	string	1.6	The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

GET https://graph.windows.net/myorganization/groups/f795caea-121d-49c7-8ae6-a95623add8aa?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Group/@Element",
  "odata.type": "Microsoft.DirectoryServices.Group",
  "objectType": "Group",
  "objectId": "b4bda672-1fba-4711-8fb1-5383c40b2c14",
  "deletionTimestamp": null,
  "description": "Marketing Department",
  "dirSyncEnabled": null,
  "displayName": "Marketing",
  "lastDirSyncTime": null,
  "mail": null,
  "mailNickname": "BposMailNickName",
  "mailEnabled": false,
  "onPremisesSecurityIdentifier": null,
  "provisioningErrors": [],
  "proxyAddresses": [],
  "securityEnabled": true
}

Response List

Status Code	Description
200	OK. Indicates success. The group is returned in the response body.

Code Samples

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
	    static void Main()
        {
            MakeRequest();

            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }

        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            /* OAuth2 is required to access this API. For more information visit:
               https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */



		   // Specify values for the following required parameters
			queryString["api-version"] = "1.6";
            // Specify values for path parameters (shown as {...})
            var uri = "https://graph.windows.net/myorganization/groups/{object_id}?" + queryString;


            var response = await client.GetAsync(uri);

            if (response.Content != null)
            {
                var responseString = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseString);
            }
        }
    }
}

@ECHO OFF

REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/groups/{object_id}?api-version=1.6&amp;"^

// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample {

  public static void main(String[] args) {
	HttpClient httpclient = HttpClients.createDefault();

	try
	{
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		// Specify values for path parameters (shown as {...})
		URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/groups/{object_id}");
		// Specify values for the following required parameters
		builder.setParameter("api-version", "1.6");
		URI uri = builder.build();
		HttpGet request = new HttpGet(uri);
		HttpResponse response = httpclient.execute(request);
		HttpEntity entity = response.getEntity();
		if (entity != null) {
			System.out.println(EntityUtils.toString(entity));
		}
	}
	catch (Exception e)
	{
		System.out.println(e.getMessage());
	}
  }
}

<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
	$(function() {
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		var params = {
			// Specify values for the following required parameters
			'api-version': "1.6",
		};
		
		$.ajax({
			// Specify values for path parameters (shown as {...})
			url: 'https://graph.windows.net/myorganization/groups/{object_id}?' + $.param(params),
			type: 'GET',
		})
		.done(function(data) {
			alert("success");
		})
		.fail(function() {
			alert("error");
		});
	});
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
	// OAuth2 is required to access this API. For more information visit:
	// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

	// Specify values for path parameters (shown as {...})
    NSString* path = @"https://graph.windows.net/myorganization/groups/{object_id}";
    NSArray* array = @[
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];
    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
    if(nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if(nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];
    return 0;
}

<?php

// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);

$query_params = array(
	// Specify values for the following required parameters
	'api-version' => '1.6',
);

$request = new Http_Request2('https://graph.windows.net/myorganization/groups/{object_id}');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);

// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

$url = $request->getUrl();
$url->setQueryVariables($query_params);

try
{
	$response = $request->send();
	
	echo $response->getBody();
}
catch (HttpException $ex)
{
	echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = httplib.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups/{object_id}?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.parse.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = http.client.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups/{object_id}?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

require 'net/http'

uri = URI('https://graph.windows.net/myorganization/groups/{object_id}')

uri.query = URI.encode_www_form({
	# Specify values for the following required parameters
	'api-version' => '1.6',
})

request = Net::HTTP::Get.new(uri.request_uri)

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks



response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body

Create a group

Adds a security group to the tenant. The request body contains the properties of the group to be created. You must specify the required properties for the group. You can optionally specify any other writable properties.

Important: You can only create security groups with the Graph API. You cannot create mail-enabled security groups or mail distribution groups.

The following table shows the properties that are required when you create a group.

Required parameter	Type	Description
displayName	string	The name to display in the address book for the group.
mailEnabled	boolean	Must be false. This is because only pure security groups can be created using the Graph API.
mailNickname	string	The mail alias for the group.
securityEnabled	boolean	Must be true. This is because only pure security groups can be created using the Graph API.

On success, returns the newly created Group; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

POST https://graph.windows.net/myorganization/groups?api-version

Parameters

Parameter	Type	Value	Notes
Query
api-version	string	1.6	The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body
Content-Type: application/json

{
  "displayName": "Example Group",
  "mailNickname": "ExampleGroup",
  "mailEnabled": false,
  "securityEnabled": true
}

Response

Status Code:201

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Group/@Element",
  "odata.type": "Microsoft.DirectoryServices.Group",
  "objectType": "Group",
  "objectId": "c7ebe5ed-b1d2-4990-88f7-892e4db2e5f3",
  "deletionTimestamp": null,
  "description": null,
  "dirSyncEnabled": null,
  "displayName": "Example Group",
  "lastDirSyncTime": null,
  "mail": null,
  "mailNickname": "ExampleGroup",
  "mailEnabled": false,
  "onPremisesSecurityIdentifier": null,
  "provisioningErrors": [],
  "proxyAddresses": [],
  "securityEnabled": true
}

Response List

Status Code	Description
201	Created. Indicates success. The new group is returned in the response body.

Update a group

Update a group's properties. Specify any writable Group property in the request body. Only the properties that you specify are changed.

Important:

Only security groups and mail-enabled security groups can be updated.
A security group cannot be updated to a mail-enabled security group or to a mail distribution group.

On success, no response body is returned; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

PATCH https://graph.windows.net/myorganization/groups/{object_id}?api-version

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	c7ebe5ed-b1d2-4990-88f7-892e4db2e5f3	The object ID (GUID) of the target group.
Query
api-version	string	1.6	The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body
Content-Type: application/json

{
  "description": "Example Security Group"
}

PATCH https://graph.windows.net/myorganization/groups/c7ebe5ed-b1d2-4990-88f7-892e4db2e5f3?api-version=1.6

Response

Status Code:204

Content-Type: application/json

none

Response List

Status Code	Description
204	No Content. Indicates success. No response body is returned.

Delete a group

Deletes a group. Deleted groups are not recoverable.

Important: You can only delete security groups with the Graph API. You cannot delete mail-enabled security groups or mail distribution groups.

On success, no response body is returned; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

DELETE https://graph.windows.net/myorganization/groups/{object_id}[?api-version]

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	c7ebe5ed-b1d2-4990-88f7-892e4db2e5f3	The object ID (GUID) of the target group.
Query
api-version	string	1.6	Specifies the version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

DELETE https://graph.windows.net/myorganization/groups/c7ebe5ed-b1d2-4990-88f7-892e4db2e5f3?api-version=1.6

Response

Status Code:204

Content-Type: application/json

Response List

none

Status Code	Description
204	No Content. Indicates success.

Relationships between a group and other objects in the directory such as the users, contacts, and other groups that may be its members are exposed through navigation properties. You can read and, in some cases, modify these relationships by targeting these navigation properties in your requests.

Operations are supported as follows:

Read (GET): all groups.
Update (POST): security groups and mail-enabled security groups (members and owners only).
Delete (DELETE): security groups only (members and owners only).

Get a group's direct members

Gets the group's direct members from the members navigation property.

On success, returns a collection of links to the Users, Contacts, ServicePrincipals, and other Groups that are direct members of this group; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

GET https://graph.windows.net/myorganization/groups/{object_id}/$links/members?api-version

Parameters

Parameter	Type	Value	Notes
URL
user_id	string	f795caea-121d-49c7-8ae6-a95623add8aa	The object ID (GUID) of the target group.
Query
api-version	string	1.6	The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

GET https://graph.windows.net/myorganization/groups/f795caea-121d-49c7-8ae6-a95623add8aa/$links/members?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/$links/members",
  "value": [
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/06adda87-a819-4c2e-ab30-127f308468b5/Microsoft.DirectoryServices.User"
    },
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/225711c4-501c-4e38-b10c-654a4f62ad67/Microsoft.DirectoryServices.User"
    },
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/2355eace-6b1d-4560-a481-eddabb529537/Microsoft.DirectoryServices.User"
    },
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/2b0a2e75-f6f5-498a-9f5c-3543e171a5a6/Microsoft.DirectoryServices.User"
    }
  ]
}

Response List

Status Code	Description
200	OK. Indicates success. A collection of links to the group members is returned.

Code Samples

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
	    static void Main()
        {
            MakeRequest();

            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }

        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            /* OAuth2 is required to access this API. For more information visit:
               https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */



		   // Specify values for the following required parameters
			queryString["api-version"] = "1.6";
            // Specify values for path parameters (shown as {...})
            var uri = "https://graph.windows.net/myorganization/groups/{object_id}/$links/members?" + queryString;


            var response = await client.GetAsync(uri);

            if (response.Content != null)
            {
                var responseString = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseString);
            }
        }
    }
}

@ECHO OFF

REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/groups/{object_id}/$links/members?api-version=1.6&amp;"^

// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample {

  public static void main(String[] args) {
	HttpClient httpclient = HttpClients.createDefault();

	try
	{
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		// Specify values for path parameters (shown as {...})
		URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/groups/{object_id}/$links/members");
		// Specify values for the following required parameters
		builder.setParameter("api-version", "1.6");
		URI uri = builder.build();
		HttpGet request = new HttpGet(uri);
		HttpResponse response = httpclient.execute(request);
		HttpEntity entity = response.getEntity();
		if (entity != null) {
			System.out.println(EntityUtils.toString(entity));
		}
	}
	catch (Exception e)
	{
		System.out.println(e.getMessage());
	}
  }
}

<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
	$(function() {
		// OAuth2 is required to access this API. For more information visit:
		// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

		var params = {
			// Specify values for the following required parameters
			'api-version': "1.6",
		};
		
		$.ajax({
			// Specify values for path parameters (shown as {...})
			url: 'https://graph.windows.net/myorganization/groups/{object_id}/$links/members?' + $.param(params),
			type: 'GET',
		})
		.done(function(data) {
			alert("success");
		})
		.fail(function() {
			alert("error");
		});
	});
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
	// OAuth2 is required to access this API. For more information visit:
	// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

	// Specify values for path parameters (shown as {...})
    NSString* path = @"https://graph.windows.net/myorganization/groups/{object_id}/$links/members";
    NSArray* array = @[
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];
    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
    if(nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if(nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];
    return 0;
}

<?php

// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);

$query_params = array(
	// Specify values for the following required parameters
	'api-version' => '1.6',
);

$request = new Http_Request2('https://graph.windows.net/myorganization/groups/{object_id}/$links/members');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);

// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

$url = $request->getUrl();
$url->setQueryVariables($query_params);

try
{
	$response = $request->send();
	
	echo $response->getBody();
}
catch (HttpException $ex)
{
	echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = httplib.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups/{object_id}/$links/members?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks

headers = {
}

params = urllib.parse.urlencode({
	# Specify values for the following required parameters
	'api-version': '1.6',
})

try:
	conn = http.client.HTTPSConnection('graph.windows.net')
	# Specify values for path parameters (shown as {...}) and request body if needed
	conn.request("GET", "/myorganization/groups/{object_id}/$links/members?%s" % params, "", headers)
	response = conn.getresponse()
	data = response.read()
	print(data)
	conn.close()
except Exception as e:
	print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

require 'net/http'

uri = URI('https://graph.windows.net/myorganization/groups/{object_id}/$links/members')

uri.query = URI.encode_www_form({
	# Specify values for the following required parameters
	'api-version' => '1.6',
})

request = Net::HTTP::Get.new(uri.request_uri)

# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks



response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body

Add group members

Adds a member to a security group or a mail-enabled security group through the members navigation property. You can add users, contacts, service principals, or other groups. The request body contains a single link to the User, Contact, ServicePrincipal, or Group to add.

Important: You can only add members to security groups and mail-enabled security groups.

On success, no response body is returned; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

POST https://graph.windows.net/myorganization/groups/{object_id}/$links/members?api-version

Parameters

Parameter	Type	Value	Notes
URL
user_id	string b4bda672-1fba-4711-8fb1-5383c40b2c14	The object ID (GUID) of the target group.
Query
api-version	string	1.6	The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body
Content-Type: application/json

{
  "url": "https://graph.windows.net/myorganization/directoryObjects/3eb6055a-baeb-44d4-a1ea-2fee86d8891b"
}

POST https://graph.windows.net/myorganization/groups/b4bda672-1fba-4711-8fb1-5383c40b2c14/$links/members?api-version=1.6

Response

Status Code:204

Content-Type: application/json

none

Response List

Status Code	Description
204	No Content. Indicates success. No response body is returned.

Delete a group member

Deletes a specified group member from a security group through the members navigation property. Specify the object ID of the User, Contact, ServicePrincipal, or Group to delete in the terminal URL segment.

Important: You can only delete members from pure security groups.

On success, no response body is returned; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

DELETE https://graph.windows.net/myorganization/groups/{object_id}/$links/members/{member_id}?api-version

Parameters

Parameter	Type	Value	Notes
URL
user_id	string	b4bda672-1fba-4711-8fb1-5383c40b2c14	The object ID (GUID) of the target group.
member_id	string	3eb6055a-baeb-44d4-a1ea-2fee86d8891b	The object ID (GUID) of the member to be removed. Can be a user, a contact, or a group.
Query
api-version	string	1.6	The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.

DELETE https://graph.windows.net/myorganization/groups/b4bda672-1fba-4711-8fb1-5383c40b2c14/$links/members/3eb6055a-baeb-44d4-a1ea-2fee86d8891b?api-version=1.6

Response

Status Code:204

Content-Type: application/json

none

Response List

Status Code	Description
204	No Content. Indicates success. No response body is returned.

By using the same patterns shown above, you can target other navigation properties exposed by groups. Some properties are read-only and others may be modified. For more information about group navigation properties, see the documentation for Group.

Functions and actions on groups

You can call any of the following functions or actions on a group.

Check membership in a specific group (transitive)

You can call the isMemberOf function to check a user, contact, service principal, or another group for membership in a specific group. The check is transitive.

Check membership in a list of groups (transitive)

You can call the checkMemberGroups function to check a user, contact, service principal, or group for membership in a list of groups. The check is transitive.

Get all group memberships (transitive)

You can call the getMemberGroups function to return all the groups that a user, contact, service principal, or group is a member of. The check is transitive.

Get all group and directory role memberships (transitive)

You can call the getMemberObjects function to return all of the groups and directory roles that a user, contact, group, or service principal is a member of. The check is transitive.

Additional Resources

Learn more about Graph API supported features, capabilities, and preview features in Graph API concepts

Share via

Operations on groups | Graph API reference

Performing REST operations on groups

Basic operations on groups

Get groups

Get a group

Create a group

Update a group

Delete a group

Operations on group navigation properties

Get a group's direct members

Add group members

Delete a group member

Other navigation properties

Functions and actions on groups

Check membership in a specific group (transitive)

Check membership in a list of groups (transitive)

Get all group memberships (transitive)

Get all group and directory role memberships (transitive)

Additional Resources

Additional resources