[DEPRECATED] Outlook People REST API reference

Article
10/21/2021

This topic is redirecting to Use the People API in Microsoft Graph to get information about the people most relevant to you.

Note

This documentation covers the People API. Preview features are subject to change prior to finalization, and may break code that uses them. Because of this, in general you should use only a production version of an API in your production code. If available, v2.0 is currently the preferred version.

The Outlook People API helps you get information about the people that are important to you from across mail, contacts, and social networks. You can combine information about a person from many sources in a single request to a single endpoint. You can use the API to access information secured by Azure Active Directory in Office 365. It also provides acces to Microsoft accounts in these domains: office.com, hotmail.com, live.com and office365.com.

Note

This article applies to all supported domains in the same way. For simplicity, the rest of this article uses Outlook.office.com to refer to accounts in all domains.

All People API operations

The People API returns relevent person entities with each request. A person aggregates information from across mail, contacts and social networks. The results are ordered by their relevance, which is determined by the criteria specified in the request and ranked based on multiple communication, collaboration and business relationships.

Browse a list of people | Get a list of people using search

Use the People REST API

Authentication

Like other Outlook REST API, for every request to the People API, you include a valid access token. You must register and identify your app and obtain the appropriate authorization to get an access token.

You can find out more about some streamlined registration and authorization options for you.

Supported REST actions and endpoints

To interact with the People REST API, you send HTTP GET requests to a supported endpoint.

The path URL resource names and query parameters are case insensitive; however, values you assign, entity IDs, and base64-encoded values are case sensitive.

All People REST API requests use the following root URL format.

https://outlook.office.com/api/{version}/{user context}

Version of the API

{version} represents the version of the REST API in the specified root URL. The only version that you can specify is beta.

beta: This version is in preview and should not be used in production code. An example URL is https://outlook.office.com/api/beta/me/people. This version includes the latest APIs in GA, as well as additional API sets that are in preview and that may change prior to finalization.

Target user

{user_context} is the currently signed-in user; the People API performs all requests on behalf of the current user. You can specify the user context in REST requests in the following way.

With the me shortcut: /api/{version}/me. The root URL becomes https://outlook.office.com/api/{version}/me.

In server responses, the user context is identified in this format: users/{AAD_userId@AAD_tenantId}.

Browse people

Paging a response
Sorting a response
Setting the number of people in a response
Selecting the fields returned
Filtering the response
Filtering and selecting the fields returned

Required scope

https://outlook.office.com/people.read

The following request gets the people most relevant to the user, based on communication, collaboration, and business relationships. By default, each response returns 10 records, but you can change this using the $top parameter.

https://outlook.office.com/api/beta/me/people/

The response to the request is the following.

	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMPSuxK9KrREk1tt36xsca8=')",
		  "Id": "AAUQAMPSuxK9KrREk1tt36xsca8=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Stuart Bui",
		  "GivenName": "Stuart",
		  "Surname": "Bui",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "sbui@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMLasTGasi1NmGqss0adMLI=')",
		  "Id": "AAUQAMLasTGasi1NmGqss0adMLI=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Phillip Wooley",
		  "GivenName": "Phillip",
		  "Surname": "Wooley",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "phillipw@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACfUjORcHM1Juw-lAPzHFIk=')",
		  "Id": "AAUQACfUjORcHM1Juw-lAPzHFIk=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Nestor Kellum",
		  "GivenName": "Nestor",
		  "Surname": "Kellum",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "nestork@contoso.com"
			},
			 {
			  "Address": "nestork@hotmail.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQADSJ952xczZGkD0tsvxPomg=')",
		  "Id": "AAUQADSJ952xczZGkD0tsvxPomg=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Lacey Burns",
		  "GivenName": "Lacey",
		  "Surname": "Burns",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "laceyb@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMJuQ5gE3IdFl1lpkykoJeY=')",
		  "Id": "AAUQAMJuQ5gE3IdFl1lpkykoJeY=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Ralph Foret",
		  "GivenName": "Ralph",
		  "Surname": "Foret",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "ralphf@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMrt5YwDXhJIlWoRZX9ebnw=')",
		  "Id": "AAUQAMrt5YwDXhJIlWoRZX9ebnw=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Emery Hixson",
		  "GivenName": "Emery",
		  "Surname": "Hixson",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "emeryh@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAOFizzhIt3ZCh4pW33s_iOQ=')",
		  "Id": "AAUQAOFizzhIt3ZCh4pW33s_iOQ=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Stephanie Ray",
		  "GivenName": "Stephanie",
		  "Surname": "Ray",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "stephanier@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 12"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKirlq5lgdFHuhZ8O9FI8XA=')",
		  "Id": "AAUQAKirlq5lgdFHuhZ8O9FI8XA=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Natalie Roach",
		  "GivenName": "Natalie",
		  "Surname": "Roach",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "natalier@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKAXFd--O4lGr6RNJzbBXwE=')",
		  "Id": "AAUQAKAXFd--O4lGr6RNJzbBXwE=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Ignacio Slayton",
		  "GivenName": "Ignacio",
		  "Surname": "Slayton",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "ignacios@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 3"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAAxHEg0Rus9CmXr0FE4muco=')",
		  "Id": "AAUQAAxHEg0Rus9CmXr0FE4muco=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Clayton Flanigan",
		  "GivenName": "Clayton",
		  "Surname": "Flanigan",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "claytonf@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		}
	  ],
	  "@odata.nextLink": "https://outlook.office.com/api/beta/me/people/?%24top=10&%24skip=10"
	}

Requesting a subsequent page of people

If the first response does not contain the complete list of relevant people, you can make a second request using $top and $skip to request additional pages of information. If the previous request has additional information, the following request gets the next page of people from the server.

https://outlook.office.com/api/beta/me/people/?$top=10&$skip=10

The following is the response from the server.

	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQADrqbKGdhxdNkjXAVQHEvMQ=')",
		  "Id": "AAUQADrqbKGdhxdNkjXAVQHEvMQ=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Monte Lafferty",
		  "GivenName": "Monte",
		  "Surname": "Lafferty",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "montel@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAHiSySeJLAtAo6t0FuPmns0=')",
		  "Id": "AAUQAHiSySeJLAtAo6t0FuPmns0=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Madelyn Cooley",
		  "GivenName": "Madelyn",
		  "Surname": "Cooley",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "madelync@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 11"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACQ-gdlH_4hPvR5o7cUkm7A=')",
		  "Id": "AAUQACQ-gdlH_4hPvR5o7cUkm7A=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Leo Scholl",
		  "GivenName": "Leo",
		  "Surname": "Scholl",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "leos@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAHc2322QSPBJtxkeVUcXPGs=')",
		  "Id": "AAUQAHc2322QSPBJtxkeVUcXPGs=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Lucinda Burke",
		  "GivenName": "Lucinda",
		  "Surname": "Burke",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "shoebm@exchange.contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAEld1zm_6W9Covp5NAGvszw=')",
		  "Id": "AAUQAEld1zm_6W9Covp5NAGvszw=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Ernesto Fellows",
		  "GivenName": "Ernesto",
		  "Surname": "Fellows",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "ernestof@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACgDLi02r8RDmtK-40rUPXE=')",
		  "Id": "AAUQACgDLi02r8RDmtK-40rUPXE=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Margret Nash",
		  "GivenName": "Margret",
		  "Surname": "Nash",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "margretn@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKXZsceAVjRDiUASCswoQxY=')",
		  "Id": "AAUQAKXZsceAVjRDiUASCswoQxY=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Wendy Monroe",
		  "GivenName": "Wendy",
		  "Surname": "Monroe",
		  "Title": "ARCHITECT",
		  "EmailAddresses": [
			{
			  "Address": "wendym@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAO-ckLra2wFBjbgc1-F5yyQ=')",
		  "Id": "AAUQAO-ckLra2wFBjbgc1-F5yyQ=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Alberta Johns",
		  "GivenName": "Alberta",
		  "Surname": "Johns",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "albertaj@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAO-Giffc5HxMibij3YNPuvU=')",
		  "Id": "AAUQAO-Giffc5HxMibij3YNPuvU=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Leticia Bullock",
		  "GivenName": "Leticia",
		  "Surname": "Bullock",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "leticiab@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAE6BF792ae9KoMQeDZbxDK0=')",
		  "Id": "AAUQAE6BF792ae9KoMQeDZbxDK0=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Angelita Dillard",
		  "GivenName": "Angelita",
		  "Surname": "Dillard",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "angelitad@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 3"
		}
	  ],
	  "@odata.nextLink": "https://outlook.office.com/api/beta/me/people/?%24skip=20&%24top=10"
	}

Sort the response

By default the people in the response are sorted by their relevance to your query. You can change the order of the people in the response using the $orderby parameter. This query selects the people most relevant to you, sorts them by their display name, and then returns the first 10 people on the sorted list.

https://outlook.office.com/api/beta/me/people/?$orderby=DisplayName

The following is the response from the server.

	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People",
	  "value": [
       	{
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAO46ZoZRt65Ajfvu2d8atiw=')",
		  "Id": "AAUQAO46ZoZRt65Ajfvu2d8atiw=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Angelina Blackwell",
		  "GivenName": "Angelina",
		  "Surname": "Blackwell",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "angelinab@exchange.contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 5"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAGaI4BZyQURDtuk0nNvBYGk=')",
		  "Id": "AAUQAGaI4BZyQURDtuk0nNvBYGk=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Benita Wilkerson",
		  "GivenName": "Benita",
		  "Surname": "Wilkerson",
		  "Title": "RESEARCHER",
		  "EmailAddresses": [
			{
			  "Address": "benitaw@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building C"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKOPqJuLWk9NtmwOx29rbew=')",
		  "Id": "AAUQAKOPqJuLWk9NtmwOx29rbew=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Callie Sweet",
		  "GivenName": "Callie",
		  "Surname": "Sweet",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "callies@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 2"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxMjF2cmVxdWVzdC5zdXBwb3J0QG9lLjIxdmlhbmV0LmNvbQ==')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxMjF2cmVxdWVzdC5zdXBwb3J0QG9lLjIxdmlhbmV0LmNvbQ==",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "contoso.support",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "contoso.support@outlook.office.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACtCaoUN6WdNgpyCSeKSP6E=')",
		  "Id": "AAUQACtCaoUN6WdNgpyCSeKSP6E=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Dianne Frederick",
		  "GivenName": "Dianne",
		  "Surname": "Frederick",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "diannef@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 3"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKNvearlKU1PsHmDb-xmDrQ=')",
		  "Id": "AAUQAKNvearlKU1PsHmDb-xmDrQ=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Jenifer Dotson",
		  "GivenName": "Jenifer",
		  "Surname": "Dotson",
		  "Title": "SENENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "jeniferd@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAAVBb0xn3ctFiZreqwDwZf0=')",
		  "Id": "AAUQAAVBb0xn3ctFiZreqwDwZf0=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Nancy Washington",
		  "GivenName": "Nancy",
		  "Surname": "Washington",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "nancyw@exchange.contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 3"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKirlq5lgdFHuhZ8O9FI8XA=')",
		  "Id": "AAUQAKirlq5lgdFHuhZ8O9FI8XA=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Natalie Roach",
		  "GivenName": "Natalie",
		  "Surname": "Roach",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "natalier@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKVYmyKcnQ9Njw5bvInrWYI=')",
		  "Id": "AAUQAKVYmyKcnQ9Njw5bvInrWYI=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Natalie Roach's Team",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "ntteam@contoso.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAFcMhzA6m4pBlHmc3Qa_PpA=')",
		  "Id": "AAUQAFcMhzA6m4pBlHmc3Qa_PpA=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Queen Duncan",
		  "GivenName": "Queen",
		  "Surname": "Duncan",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "queend@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 3"
		}
	  ],
	  "@odata.nextLink": "https://outlook.office.com/api/beta/me/people/?%24orderby=DisplayName&%24top=10&%24skip=10"
	}

Changing the number of people returned and the fields returned

You can change the number of people returned in the response by setting the $top parameter.

The following example requests the 1,000 most relevant people. The request also limits the amount of data sent back from the server by requesting only the display name of the person.

https://outlook.office.com/api/beta/me/people/?$top=1000&$Select=DisplayName

The following is the response from the server.

	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People(DisplayName)",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMPSuxK9KrREk1tt36xsca8=')",
		  "Id": "AAUQAMPSuxK9KrREk1tt36xsca8=",
		  "DisplayName": "Brian Remick"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMLasTGasi1NmGqss0adMLI=')",
		  "Id": "AAUQAMLasTGasi1NmGqss0adMLI=",
		  "DisplayName": "Phillip Wooley"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACfUjORcHM1Juw-lAPzHFIk=')",
		  "Id": "AAUQACfUjORcHM1Juw-lAPzHFIk=",
		  "DisplayName": "Nestor Kellum"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQADSJ952xczZGkD0tsvxPomg=')",
		  "Id": "AAUQADSJ952xczZGkD0tsvxPomg=",
		  "DisplayName": "Lacey Burns"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMJuQ5gE3IdFl1lpkykoJeY=')",
		  "Id": "AAUQAMJuQ5gE3IdFl1lpkykoJeY=",
		  "DisplayName": "Ralph Foret"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMrt5YwDXhJIlWoRZX9ebnw=')",
		  "Id": "AAUQAMrt5YwDXhJIlWoRZX9ebnw=",
		  "DisplayName": "Emery Hixson"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAOFizzhIt3ZCh4pW33s_iOQ=')",
		  "Id": "AAUQAOFizzhIt3ZCh4pW33s_iOQ=",
		  "DisplayName": "Stephanie Ray"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKirlq5lgdFHuhZ8O9FI8XA=')",
		  "Id": "AAUQAKirlq5lgdFHuhZ8O9FI8XA=",
		  "DisplayName": "Natalie Roach"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKAXFd--O4lGr6RNJzbBXwE=')",
		  "Id": "AAUQAKAXFd--O4lGr6RNJzbBXwE=",
		  "DisplayName": "Ignacio Slayton"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAAxHEg0Rus9CmXr0FE4muco=')",
		  "Id": "AAUQAAxHEg0Rus9CmXr0FE4muco=",
		  "DisplayName": "Clayton Flanigan"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQADrqbKGdhxdNkjXAVQHEvMQ=')",
		  "Id": "AAUQADrqbKGdhxdNkjXAVQHEvMQ=",
		  "DisplayName": "Monte Lafferty"
		},
		... etc

Selecting the fields to return

You can limit the amount of data returned from the server by using the $select parameter to choose one or more fields. The @odata.id field is always returned.

The following example limits the response to the DisplayName and EmailAddress of the 10 most relevant people.

https://outlook.office.com/api/beta/me/people/?$select=DisplayName,EmailAddresses

The following is the response from the server.

	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People(DisplayName,EmailAddresses)",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMPSuxK9KrREk1tt36xsca8=')",
		  "Id": "AAUQAMPSuxK9KrREk1tt36xsca8=",
		  "DisplayName": "Brian Remick",
		  "EmailAddresses": [
			{
			  "Address": "bremick@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMLasTGasi1NmGqss0adMLI=')",
		  "Id": "AAUQAMLasTGasi1NmGqss0adMLI=",
		  "DisplayName": "Phillip Wooley",
		  "EmailAddresses": [
			{
			  "Address": "phillipw@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACfUjORcHM1Juw-lAPzHFIk=')",
		  "Id": "AAUQACfUjORcHM1Juw-lAPzHFIk=",
		  "DisplayName": "Nestor Kellum",
		  "EmailAddresses": [
			{
			  "Address": "nestork@contoso.com"
			},
			 {
			  "Address": "nestork@outlook.office.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQADSJ952xczZGkD0tsvxPomg=')",
		  "Id": "AAUQADSJ952xczZGkD0tsvxPomg=",
		  "DisplayName": "Lacey Burns",
		  "EmailAddresses": [
			{
			  "Address": "laceyb@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMJuQ5gE3IdFl1lpkykoJeY=')",
		  "Id": "AAUQAMJuQ5gE3IdFl1lpkykoJeY=",
		  "DisplayName": "Ralph Foret",
		  "EmailAddresses": [
			{
			  "Address": "ralphf@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMrt5YwDXhJIlWoRZX9ebnw=')",
		  "Id": "AAUQAMrt5YwDXhJIlWoRZX9ebnw=",
		  "DisplayName": "Emery Hixson",
		  "EmailAddresses": [
			{
			  "Address": "emeryh@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAOFizzhIt3ZCh4pW33s_iOQ=')",
		  "Id": "AAUQAOFizzhIt3ZCh4pW33s_iOQ=",
		  "DisplayName": "Stephanie Ray",
		  "EmailAddresses": [
			{
			  "Address": "stephanier@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKirlq5lgdFHuhZ8O9FI8XA=')",
		  "Id": "AAUQAKirlq5lgdFHuhZ8O9FI8XA=",
		  "DisplayName": "Natalie Roach",
		  "EmailAddresses": [
			{
			  "Address": "natalier@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAKAXFd--O4lGr6RNJzbBXwE=')",
		  "Id": "AAUQAKAXFd--O4lGr6RNJzbBXwE=",
		  "DisplayName": "Ignacio Slayton",
		  "EmailAddresses": [
			{
			  "Address": "ignacios@contoso.com"
			}
		  ]
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAAxHEg0Rus9CmXr0FE4muco=')",
		  "Id": "AAUQAAxHEg0Rus9CmXr0FE4muco=",
		  "DisplayName": "Clayton Flanigan",
		  "EmailAddresses": [
			{
			  "Address": "claytonf@contoso.com"
			}
		  ]
		}
	  ],
	  "@odata.nextLink": "https://outlook.office.com/api/beta/me/people/?%24select=DisplayName%2cEmailAddresses&%24top=10&%24skip=10"
	}

Using a filter to limit the response

You can use the $filter parameter to limit the response to only those people whose record contains the specified criteria.

The following query limits the response to people with the source "Communications History."

https://outlook.office.com/api/beta/me/people/?$Filter=Sources/Any (source: source/Type  eq 'Communications History')

	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxcGVvcGxlcmVsZXZhbmNlQHNlcnZpY2UuZXhjaGFuZ2UubWljcm9zb2Z0LmNvbQ==')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxcGVvcGxlcmVsZXZhbmNlQHNlcnZpY2UuZXhjaGFuZ2UubWljcm9zb2Z0LmNvbQ==",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "People Relevance",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "peoplerelevance@service.exchange.contoso.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxcmNoaUByY2hpbGF3LmNvbQ==')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxcmNoaUByY2hpbGF3LmNvbQ==",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "Edna Dickson",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "ednad@outlook.office.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxMjF2cmVxdWVzdC5zdXBwb3J0QG9lLjIxdmlhbmV0LmNvbQ==')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxMjF2cmVxdWVzdC5zdXBwb3J0QG9lLjIxdmlhbmV0LmNvbQ==",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "contoso.support",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "contoso.support@contoso.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxUGVvcGxlOTExMUBzZXJ2aWNlLmV4Y2hhbmdlLm1pY3Jvc29mdC5jb20=')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxUGVvcGxlOTExMUBzZXJ2aWNlLmV4Y2hhbmdlLm1pY3Jvc29mdC5jb20=",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "gethelp@contoso.com",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "gethelp@contoso.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxc21hcnRhbGVydHNAbWljcm9zb2Z0LmNvbQ==')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxc21hcnRhbGVydHNAbWljcm9zb2Z0LmNvbQ==",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "smartalerts@contoso.com",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "smartalerts@contoso.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxam9lQG9saXZlYW5kZ29vc2UuY29t')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxam9lQG9saXZlYW5kZ29vc2UuY29t",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "Emily Burnett",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "emilyb@contoso.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxYS1jYW1hbm5AbWljcm9zb2Z0LmNvbQ==')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxYS1jYW1hbm5AbWljcm9zb2Z0LmNvbQ==",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "Bridgett Baxter",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "bridgettb@contoso.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxc3RlZmFuLmJ1cmFrQGluc2lkZXZpZXcuY29t')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxc3RlZmFuLmJ1cmFrQGluc2lkZXZpZXcuY29t",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "Charlotte Stark",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "charlottes@insideview.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxbWFyaWFuYXN0ZXBwQG91dGxvb2suY29t')",
		  "Id": "MkU4MDBGNDUtMEY3OS00MzM4LTg3RUUtNENFOTFBRURCODcxbWFyaWFuYXN0ZXBwQG91dGxvb2suY29t",
		  "Sources": [
			{
			  "Type": "Communication History"
			}
		  ],
		  "DisplayName": "herminiah@outlook.office.com",
		  "GivenName": null,
		  "Surname": null,
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "herminiah@outlook.office.com"
			}
		  ],
		  "CompanyName": null,
		  "OfficeLocation": null
		}
	  ],
	  "@odata.nextLink": "https://outlook.office.com/api/beta/me/people/?%24Filter=Sources%2fAny+(source%3a+source%2fType++eq+%27Communication+History%27)&%24top=10&%24skip=10"
	}

Selecting the fields to return in a filtered response

You can combine the $select and $filter parameters to create a custom list of people relevant to the user and get only the fields that your application needs.

The following example gets the DisplayName and EmailAddress of people whose display name equals the specified name. In this example, only people whose display name equals "Nestor Kellum" are returned.

https://outlook.office.com/api/beta/me/people/?$select=DisplayName,EmailAddresses&$Filter=DisplayName eq 'Nestor Kellum'

The following is the response from the server.

	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People(DisplayName,EmailAddresses)",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACfUjORcHM1Juw-lAPzHFIk=')",
		  "Id": "AAUQACfUjORcHM1Juw-lAPzHFIk=",
		  "DisplayName": "Nestor Kellum",
		  "EmailAddresses": [
			{
			  "Address": "nestork@contoso.com"
			},
			 {
			  "Address": "nestork@outlook.office.com"
			}
		  ]
		}
	  ]
	}

Required scope

https://outlook.office.com/people.read

Using search to select people

Use the $search parameter to select people who meet a particular set of criteria.

The following search query returns relevant people whose GivenName or Surname begins with the letter "j".

https://outlook.office.com/api/beta/me/people/?$search=j

The following is the response from the server.

		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAC4PuXFfR6pAin18WlyOqxI=')",
		  "Id": "AAUQAC4PuXFfR6pAin18WlyOqxI=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Jacquelyn Cox",
		  "GivenName": "Jacquelyn",
		  "Surname": "Cox",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "jacquelync@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building S"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAFE5-QvXOi1KhbNrQQaV-dk=')",
		  "Id": "AAUQAFE5-QvXOi1KhbNrQQaV-dk=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Julie Yates",
		  "GivenName": "Julie",
		  "Surname": "Yates",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "juliey@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 2"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAChuH75CMB5NsGP0QBDcX2g=')",
		  "Id": "AAUQAChuH75CMB5NsGP0QBDcX2g=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Juliette Mitchell",
		  "GivenName": "Juliette",
		  "Surname": "Mitchell",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "juliettem@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAMsDacKpHNpFj7ViBXFiRZI=')",
		  "Id": "AAUQAMsDacKpHNpFj7ViBXFiRZI=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Katheryn Johns",
		  "GivenName": "Katheryn",
		  "Surname": "Johns",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "katherynj@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building T"
		}
	  ],
	  "@odata.nextLink": "https://outlook.office.com/api/beta/me/people/?%24search=d&%24top=10&%24skip=10"
	}

Using search to specify a relevant topic

The following request returns relevant people whose name contains "ma" and who have shown an interest in the comedian "Aziz Ansari."

 https://outlook.office.com/api/beta/me/people/?$search="ma topic: Aziz Ansari"

The following is the response from the server.

 	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQACgDLi02r8RDmtK-40rUPXE=')",
		  "Id": "AAUQACgDLi02r8RDmtK-40rUPXE=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Margret Nash",
		  "GivenName": "Margret",
		  "Surname": "Nash",
		  "Title": "ENGINEER",
		  "EmailAddresses": [
			{
			  "Address": "margretn@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAHiSySeJLAtAo6t0FuPmns0=')",
		  "Id": "AAUQAHiSySeJLAtAo6t0FuPmns0=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Madelyn Cooley",
		  "GivenName": "Madelyn",
		  "Surname": "Cooley",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "madelync@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 11"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAAebvnx4LnNKsFWppdcopJw=')",
		  "Id": "AAUQAAebvnx4LnNKsFWppdcopJw=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Albert Raley",
		  "GivenName": "Albert",
		  "Surname": "Raley",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "albertr@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Bulding T"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAPqWcitEhEFNuvaSLteeN9M=')",
		  "Id": "AAUQAPqWcitEhEFNuvaSLteeN9M=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Emanuel Grider",
		  "GivenName": "Emanuel",
		  "Surname": "Grider",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "edh@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAIqrTSzA3N1BglLTWFzgql4=')",
		  "Id": "AAUQAIqrTSzA3N1BglLTWFzgql4=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Frederick Magnuson",
		  "GivenName": "Frederick",
		  "Surname": "Magnuson",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "fredrickm@service.exchange.contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 3"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAId9cw-r_cZDtd5mU6QVvR4=')",
		  "Id": "AAUQAId9cw-r_cZDtd5mU6QVvR4=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Beryl Maddox",
		  "GivenName": "Beryl",
		  "Surname": "Maddox",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "berylm@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 3"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAPbEMn4Y_EhPoPJIAfe9-v4=')",
		  "Id": "AAUQAPbEMn4Y_EhPoPJIAfe9-v4=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Vilma Young",
		  "GivenName": "Vilma",
		  "Surname": "Young",
		  "Title": "LEAD",
		  "EmailAddresses": [
			{
			  "Address": "vilmay@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building T"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQANxLXO4NLchEiyteaLb_HNM=')",
		  "Id": "AAUQANxLXO4NLchEiyteaLb_HNM=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Edna Foreman",
		  "GivenName": "Edna",
		  "Surname": "Foreman",
		  "Title": null,
		  "EmailAddresses": [
			{
			  "Address": "ednaf@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building L"
		},
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAQkADA5OWM3MmE5LTNmYmItNDk1NS1hZDY0LTAwYjBhZjc4MTg3YwAQABMxxzYk20pLinJq19EtuKc=')",
		  "Id": "AAQkADA5OWM3MmE5LTNmYmItNDk1NS1hZDY0LTAwYjBhZjc4MTg3YwAQABMxxzYk20pLinJq19EtuKc=",
		  "Sources": [
			{
			  "Type": "Outlook Contacts"
			}
		  ],
		  "DisplayName": "Tammi Pickett",
		  "GivenName": "Tammi",
		  "Surname": "Pickett",
		  "Title": "Engineer",
		  "EmailAddresses": [
			{
			  "Address": "tammip@contoso.com"
			}
		  ],
		  "CompanyName": "Contoso",
		  "OfficeLocation": null
		},
	  "@odata.nextLink": "https://outlook.office.com/api/beta/me/people/?%24search=%22ed+topic%3a+Aziz+ansari%22&
%24top=10&%24skip=10"
	}

Performing a fuzzy search

The following request does a search for a person named "Hermaini Hall." Because there is a relevant person named "Herminia Hull," the information for "Herminia Hull" is returned.

 https://outlook.office.com/api/beta/me/people/?$search="hermaini hall"

The following is the response from the server.

 	{
	  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/People",
	  "value": [
		{
		  "@odata.id": "https://outlook.office.com/api/beta/users/4579DA25-3624-44CD-AE44-9777EEB9D292@F56380F1-06A5-4239-B31E-C8B44DF1F05A/People('AAUQAL5wQK1L1MNNsL4qzoFWZiQ=')",
		  "Id": "AAUQAL5wQK1L1MNNsL4qzoFWZiQ=",
		  "Sources": [
			{
			  "Type": "Directory"
			}
		  ],
		  "DisplayName": "Herminia Hull",
		  "GivenName": "Herminia",
		  "Surname": "Hull",
		  "Title": "MANAGER",
		  "EmailAddresses": [
			{
			  "Address": "herminiah@contoso.com"
			}
		  ],
		  "CompanyName": "CONTOSO",
		  "OfficeLocation": "Building 4"
		}
	  ]
	}

-->

[DEPRECATED] Outlook People REST API reference

All People API operations

Use the People REST API

Authentication

Supported REST actions and endpoints

Version of the API

Target user

Browse people

Required scope

Requesting a subsequent page of people

Sort the response

Changing the number of people returned and the fields returned

Selecting the fields to return

Using a filter to limit the response

Selecting the fields to return in a filtered response

Search people

Required scope

Using search to select people

Using search to specify a relevant topic

Performing a fuzzy search

Additional resources