Table of contents

Operations on contacts | Graph API reference

Jimaco Brannian|Last Updated: 8/29/2016
|
1 Contributor

Applies to: Graph API | Azure Active Directory

This topic discusses how to perform operations on organizational contacts using the Azure Active Directory (AD) Graph API. Organizational contacts typically represent users who are external to your company or organization. They are different from O365 Outlook personal contacts. With the Azure AD Graph API, you can read organizational contacts and their relationships to other directory objects, such as their manager, direct reports, and group memberships. The ability to write organizational contacts is limited to those contacts that are not currently synced from an on-premises directory (the dirSyncEnabled property is null or false). For such contacts, you can update or delete the contact itself or its manager property. You cannot create organizational contacts with the Graph API. For more information about organizational contacts, including how they are created in your tenant, see Contact.

The Graph API is a REST-based API that provides programmatic access to directory objects in Azure Active Directory, such as users, groups, organizational contacts, and applications.

Important

Azure AD Graph API functionality is also available through Microsoft Graph, a unified API that also includes APIs from other Microsoft services like Outlook, OneDrive, OneNote, Planner, and Office Graph, all accessed through a single endpoint with a single access token.

Performing REST operations on contacts

To perform operations on organizational contacts with the Graph API, you send HTTP requests with a supported method (GET, POST, PATCH, PUT, or DELETE) to an endpoint that targets the contacts resource collection, a specific contact, a navigation property of a contact, or a function or action that can be called on a contact.

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 contacts in your tenant, an individual contact, or a navigation property of a specific contact.

  • /contacts targets the contact resource collection. You can use this resource path to read all contacts or a filtered list of contacts in your tenant.
  • /contacts/{object_id} targets an individual contact in your tenant. You specify the target contact with its object ID (GUID). You can use this resource path to get the declared properties of a contact. For contacts that are not synced from an on-premises directory, you can use this resource path to modify the declared properties of a contact, or to delete a contact.
  • /contacts/{object_id}/{nav_property} targets the specified navigation property of a contact. You can use it to return the object or objects referenced by the target navigation property of the specified contact. Note: This form of addressing is only available for reads.
  • /contacts/{object_id}/$links/{nav_property} targets the specified navigation property of a contact. 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. Only the manager navigation property of contacts that are not synced from an on-premises directory can be modified. The manager is specified as a link in the request body.

For example, the following request returns a link to the specified contact's manager:

GET https://graph.windows.net/myorganization/contacts/a2fb3752-08b4-413d-af6f-1d99c4c131d9/$links/manager?api-version=1.6

Basic operations on contacts

You can perform read operations on contacts by targeting either the contact resource collection or a specific contact. You can update and delete contacts that are not synced from an on-premises directory by targeting a specific contact. The Graph API does not support creating contacts. Nor does it support updating or deleting contacts that are synced from an on-premises directory (the dirSyncEnabled property is true). The following topics show you how to perform basic operations on contacts.


Get contacts

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

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

Request

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

Parameters

ParameterTypeValueNotes
Query
api-versionstringThe 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.

Requested URL

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

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Contact",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Contact",
      "objectType": "Contact",
      "objectId": "31944231-fd52-4a7f-b32e-7902a01fddf9",
      "deletionTimestamp": null,
      "city": null,
      "companyName": null,
      "country": null,
      "department": null,
      "dirSyncEnabled": null,
      "displayName": "Marcus Breyer",
      "facsimileTelephoneNumber": null,
      "givenName": "Marcus",
      "jobTitle": null,
      "lastDirSyncTime": null,
      "mail": "Marcus@contoso.com",
      "mailNickname": "MarcusBreyer",
      "mobile": null,
      "physicalDeliveryOfficeName": null,
      "postalCode": null,
      "provisioningErrors": [],
      "proxyAddresses": [
        "SMTP:Marcus@contoso.com"
      ],
      "sipProxyAddress": null,
      "state": null,
      "streetAddress": null,
      "surname": "Breyer",
      "telephoneNumber": null
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Contact",
      "objectType": "Contact",
      "objectId": "35110b16-360c-4c4a-93b2-03f065fabd93",
      "deletionTimestamp": null,
      "city": null,
      "companyName": null,
      "country": null,
      "department": null,
      "dirSyncEnabled": null,
      "displayName": "Yossi Ran",
      "facsimileTelephoneNumber": null,
      "givenName": "Yossi",
      "jobTitle": null,
      "lastDirSyncTime": null,
      "mail": "Yossi@contoso.com",
      "mailNickname": "YossiRan",
      "mobile": null,
      "physicalDeliveryOfficeName": null,
      "postalCode": null,
      "provisioningErrors": [],
      "proxyAddresses": [
        "SMTP:Yossi@contoso.com"
      ],
      "sipProxyAddress": null,
      "state": null,
      "streetAddress": null,
      "surname": "Ran",
      "telephoneNumber": null
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Contact",
      "objectType": "Contact",
      "objectId": "7163f3b8-70c9-43d2-b9e1-4467ddaf087a",
      "deletionTimestamp": null,
      "city": null,
      "companyName": null,
      "country": null,
      "department": null,
      "dirSyncEnabled": null,
      "displayName": "Jeremy Nelson",
      "facsimileTelephoneNumber": null,
      "givenName": "Jeremy",
      "jobTitle": null,
      "lastDirSyncTime": null,
      "mail": "Jeremy@contoso.com",
      "mailNickname": "JeremyNelson",
      "mobile": null,
      "physicalDeliveryOfficeName": null,
      "postalCode": null,
      "provisioningErrors": [],
      "proxyAddresses": [
        "SMTP:Jeremy@contoso.com"
      ],
      "sipProxyAddress": null,
      "state": null,
      "streetAddress": null,
      "surname": "Nelson",
      "telephoneNumber": null
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Contact",
      "objectType": "Contact",
      "objectId": "83234b5c-3a10-4108-8f36-39b1addadfdb",
      "deletionTimestamp": null,
      "city": null,
      "companyName": null,
      "country": null,
      "department": null,
      "dirSyncEnabled": null,
      "displayName": "David Strome",
      "facsimileTelephoneNumber": null,
      "givenName": "David",
      "jobTitle": null,
      "lastDirSyncTime": null,
      "mail": "David@contoso.com",
      "mailNickname": "DavidStrome",
      "mobile": null,
      "physicalDeliveryOfficeName": null,
      "postalCode": null,
      "provisioningErrors": [],
      "proxyAddresses": [
        "SMTP:David@contoso.com"
      ],
      "sipProxyAddress": null,
      "state": null,
      "streetAddress": null,
      "surname": "Strome",
      "telephoneNumber": null
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Contact",
      "objectType": "Contact",
      "objectId": "8c1315ce-bf6f-4e26-b24f-c830606ef41c",
      "deletionTimestamp": null,
      "city": null,
      "companyName": null,
      "country": null,
      "department": null,
      "dirSyncEnabled": null,
      "displayName": "Holly Holt",
      "facsimileTelephoneNumber": null,
      "givenName": "Holly",
      "jobTitle": null,
      "lastDirSyncTime": null,
      "mail": "Holly@contoso.com",
      "mailNickname": "HollyHolt",
      "mobile": null,
      "physicalDeliveryOfficeName": null,
      "postalCode": null,
      "provisioningErrors": [],
      "proxyAddresses": [
        "SMTP:Holly@contoso.com"
      ],
      "sipProxyAddress": null,
      "state": null,
      "streetAddress": null,
      "surname": "Holt",
      "telephoneNumber": null
    }
  ]
}

Response List

Status CodeDescription
200OK. 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/contacts?" + 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/contacts?api-version=1.6&"^

// 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/contacts");
		// 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/contacts?' + $.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/contacts";
    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/contacts');
$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/contacts?%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/contacts?%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/contacts')

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 contact

Gets a specified contact. You use the object ID (GUID) to identify the target contact.

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

Request

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

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target contact.
Query
api-versionstringSpecifies 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.

Requested URL

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

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/graphdir1.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.Contact/@Element",
  "odata.type": "Microsoft.DirectoryServices.Contact",
  "objectType": "Contact",
  "objectId": "31944231-fd52-4a7f-b32e-7902a01fddf9",
  "deletionTimestamp": null,
  "city": null,
  "companyName": null,
  "country": null,
  "department": null,
  "dirSyncEnabled": null,
  "displayName": "Marcus Breyer",
  "facsimileTelephoneNumber": null,
  "givenName": "Marcus",
  "jobTitle": null,
  "lastDirSyncTime": null,
  "mail": "Marcus@contoso.com",
  "mailNickname": "MarcusBreyer",
  "mobile": null,
  "physicalDeliveryOfficeName": null,
  "postalCode": null,
  "provisioningErrors": [],
  "proxyAddresses": [
    "SMTP:Marcus@contoso.com"
  ],
  "sipProxyAddress": null,
  "state": null,
  "streetAddress": null,
  "surname": "Breyer",
  "telephoneNumber": null
}

Response List

Status CodeDescription
200OK. Indicates success. The contact 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/contacts/{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/contacts/{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/contacts/{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/contacts/{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/contacts/{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/contacts/{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/contacts/{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/contacts/{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/contacts/{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

Update a contact

Update a contact's properties. Specify any writable Contact property in the request body. Only the properties that you specify are changed. You can update only contacts that are not synced from an on-premises directory (the dirSyncEnabled property is null or false).

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.

Request

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

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target contact.
Query
api-versionstringThe 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
{
  "department": "Sales",
  "jobTitle": "Sales Rep"
}

Requested URL

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

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Delete a contact

Deletes a contact. You can delete only contacts that are not synced from an on-premises directory (the dirSyncEnabled property is null or false).

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.

Request

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

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target contact.
Query
api-versionstringSpecifies 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.

Requested URL

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

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success.

Operations on contact navigation properties

Relationships between a contact and other objects in the directory such as the contact's manager, direct group memberships, and direct reports are exposed through navigation properties. You can read and, in some cases, modify these relationships by targeting these navigation properties in your requests.

Get a contact's manager

Gets the contact's manager from the manager navigation property.

On success, returns a link to the User or Contact assigned as the contact's manager; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

Note: You can remove the "$links" segment from the URL to return the User or Contact object instead of a link.

Request

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

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target contact.
Query
api-versionstringThe 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.

Requested URL

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

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/$links/manager",
  "url": "https://graph.windows.net/myorganization/directoryObjects/35110b16-360c-4c4a-93b2-03f065fabd93/Microsoft.WindowsAzure.ActiveDirectory.Contact"
}

Response List

Status CodeDescription
200OK. Indicates success. A link to the contact's manager is returned.
404Not Found. The requested resource was not found. This can occur if the manager property is not currently set for the specified contact. It can also have other causes, for example, a bad domain. A code and associated message is returned with the error.

Code Samples


Assign a contact's manager

Assigns a contact's manager through the manager property. Either a user or a contact may be assigned. The request body contains a link to the User or Contact to assign. You can update the manager only for contacts that are not synced from an on-premises directory (the dirSyncEnabled property is null or false).

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.

Request

PUT https://graph.windows.net/myorganization/contacts/{object_id}/$links/manager?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target contact.
Query
api-versionstringThe 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/35110b16-360c-4c4a-93b2-03f065fabd93"
}

Requested URL

PUT https://graph.windows.net/myorganization/contacts/{object_id}/$links/manager?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Get a contact's direct reports

Gets the contact's direct reports from the directReports navigation property.

On success, returns a collection of links to the User's and Contact's for whom this contact is assigned as manager; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

Note: You can remove the "$links" segment from the URL to return DirectoryObjects for the users and contacts instead of links.

Request

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

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target contact.
Query
api-versionstringThe 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.

Requested URL

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

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/$links/directReports",
  "value": [
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/8c1315ce-bf6f-4e26-b24f-c830606ef41c/Microsoft.DirectoryServices.Contact"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. One or more direct reports are returned.

Code Samples


Get a contact's group memberships

Gets the contact's group memberships from the memberOf navigation property.

This property returns only groups that the contact is a direct member of. To get all of the groups that the contact has direct or transitive membership in, call the getMemberGroups function.

On success, returns a collection of links to the Groups that this contact is a member of; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

Note: You can remove the "$links" segment from the URL to return the DirectoryObjects for the groups instead of links.

Request

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

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object ID (GUID) of the target contact.
Query
api-versionstringThe 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.

Requested URL

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

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/$links/memberOf",
  "value": [
    {
      "url": "https://graph.windows.net/myorganization/directoryObjects/12345678-b942-47c9-a10e-a4bee353ce60/Microsoft.DirectoryServices.Group"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. One or more groups and/or directory roles are returned.

Code Samples


Functions and actions on contacts

You can call any of the following functions on a contact.

Check membership in a specific group (transitive)

You can call the isMemberOf function to check 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 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 the contact is a member of. The check is transitive, unlike reading the memberOf navigation property, which returns only the groups that the contact is a direct member of.


Additional Resources

  • Learn more about Graph API supported features, capabilities, and preview features in Graph API concepts
© 2017 Microsoft