List people

Namespace: microsoft.graph

Important

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

Retrieve a list of person objects ordered by their relevance to the user, which is determined by the user's communication and collaboration patterns, and business relationships.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type	Least privileged permissions	Higher privileged permissions
Delegated (work or school account)	People.Read	People.Read.All
Delegated (personal Microsoft account)	People.Read	Not available.
Application	People.Read.All	Not available.

HTTP request

GET /me/people
GET /users/{id | userPrincipalName}/people

Optional query parameters

This method supports the following OData query parameters to help customize the response.

Name	Value	Description
$filter	string	Limits the response to only those people whose record contains the specified criteria.
$orderby	string	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.
$search	string	Search for people by name or alias. Supports Fuzzy matching. Parameter only works for searching the signed-in user's relevant people, not for searching people relevant to other users. Also supports the topic keyword to find people based on topics extracted from e-mail conversations with that person. For information and examples, see the Perform a fuzzy search section at Use the People API to get information about the people most relevant to you.
$select	string	Comma-separated list of properties to include in the response. For optimal performance, only select the subset of properties needed.
$skip	int	Skip the first n results, useful for paging. Skipping is not supported when using $search.
$top	int	The maximum number of results to be returned on a results page. For more information, see top parameter.

Request headers

Name	Description
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.
Accept	application/json

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and a collection of person objects in the response body.

Examples

Browse

The requests in this section get the people most relevant to the signed-in user (/me), based on communication, collaboration, and business relationships.

By default, each response returns 10 records, but you can change this using the $top parameter. These requests require the People.Read permission.

Request

The following is an example of the default request.

HTTP

GET https://graph.microsoft.com/beta/me/people

C#

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.People.GetAsync();

Important

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

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users people list --user-id {user-id}

Important

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

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

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



people, err := graphClient.Me().People().Get(context.Background(), nil)

Important

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

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

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

PersonCollectionResponse result = graphClient.me().people().get();

Important

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

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let people = await client.api('/me/people')
	.version('beta')
	.get();

Important

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

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

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


$result = $graphServiceClient->me()->people()->get()->wait();

Important

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

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

PowerShell

Import-Module Microsoft.Graph.Beta.People

# A UPN can also be used as -UserId.
Get-MgBetaUserPerson -UserId $userId

Important

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

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

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.me.people.get()

Important

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

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

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "33b43a5b-87d6-41ec-91f8-a2610048105f",
            "displayName": "Marketing",
            "givenName": null,
            "surname": null,
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "mailboxType": "GroupMailbox",
            "personType": "ModernGroup",
            "userPrincipalName": "",
            "emailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "rank": 30
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "mailboxType": "Mailbox",
            "personType": "Person",
            "userPrincipalName": "IsaiahL@contoso.com",
            "emailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

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 more pages of information. If the previous request has additional information, the following request gets the next page of people from the server.

GET https://graph.microsoft.com/beta/me/people/?$top=10&$skip=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.

GET https://graph.microsoft.com/beta/me/people/?$orderby=DisplayName

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 people most relevant to /me. The request also limits the amount of data sent back from the server by requesting only the display name of the person.

GET https://graph.microsoft.com/beta/me/people/?$top=1000&$select=DisplayName

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.

GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses

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 "Directory."

GET https://graph.microsoft.com/beta/me/people/?$filter=Sources/Any (source: source/Type  eq 'Directory')

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.

+GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$filter=DisplayName eq 'Nestor Kellum'

Search people

The requests in this section also get the people most relevant to the signed-in user (/me). Search requests require the People.Read permission.

Using search to select people

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

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

GET https://graph.microsoft.com/beta/me/people/?$search=j

Using search to specify a relevant topic

The following request returns people relevant to /me whose name contains "ma" and who have an association with "feature planning."

GET https://graph.microsoft.com/beta/me/people/?$search="ma topic: feature planning"

Performing a fuzzy search

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

GET https://graph.microsoft.com/beta/me/people/?$search="hermaini hall"

Related people

The following request gets the people most relevant to another person in the user's organization. This request requires the User.ReadBasic.All for People.Read.All permission. In this example, Nestor Kellum's relevant people are displayed.

GET https://graph.microsoft.com/beta/users('nestork@contoso.com')/people/