Get a user

Article
08/05/2022
17 minutes to read

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 the properties and relationships of user object.

This operation returns by default only a subset of the more commonly used properties for each user. These default properties are noted in the Properties section. To get properties that are not returned by default, do a GET operation for the user and specify the properties in a $select OData query option. Because the user resource supports extensions, you can also use the GET operation to get custom properties and extension data in a user instance.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account)	User.Read, User.ReadWrite
Application	User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Tip

Calling the /me endpoint requires a signed-in user and therefore a delegated permission. Application permissions are not supported when using the /me endpoint.
The User.Read permission allows the app to read the profile, and discover relationships such as the group membership, reports and manager of the signed-in user only.

HTTP request

For a specific user:

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

Tip

When the userPrincipalName begins with a $ character, the GET request URL syntax /users/$x@y.com fails with a 400 Bad Request error code. This is because this request URL violates the OData URL convention, which expects only system query options to be prefixed with a $ character. Remove the slash (/) after /users and enclose the userPrincipalName in parentheses and single quotes, as follows: /users('$x@y.com'). For example, /users('$AdeleVance@contoso.com').
To query a B2B user using the userPrincipalName, encode the hash (#) character. That is, replace the # symbol with %23. For example, /users/AdeleVance_adatum.com%23EXT%23@contoso.com.

For the signed-in user:

GET /me

Optional query parameters

This method supports the $select OData query parameter to retrieve specific user properties, including those that are not returned by default. Extension properties also support query parameters as follows:

Extension type	Comments
onPremisesExtensionAttributes 1-15	Returned only with `$select`.
Schema extensions	Returned only with `$select`.
Open extensions	Returned only through the Get open extension operation.
Directory extensions	Returned only with `$select`.

Request headers

Header	Value
Authorization	Bearer {token}. Required.
Content-Type	application/json

Request body

Do not supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and user object in the response body. It returns the default properties unless you use $select to specify specific properties.

This method returns 202 Accepted when the request has been processed successfully but the server requires more time to complete related background operations.

Example

Example 1: Get the properties of the signed-in user

Request

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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Me
	.Request()
	.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.


const options = {
	authProvider,
};

const client = Client.init(options);

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

Important

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.me()
	.buildRequest()
	.get();

Important

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)


result, err := graphClient.Me().Get()

Important

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


Import-Module Microsoft.Graph.Users

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

Important

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$requestResult = $graphServiceClient->me()->get();

Important

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

Response

Here is an example of the response. Note: The response object shown here might be shortened for readability.

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

{
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.onmicrosoft.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

Example 2: Get the properties of the specified user

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/users/{id}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Users["{user-id}"]
	.Request()
	.GetAsync();

Important

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


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/{id}')
	.version('beta')
	.get();

Important

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.users("{id}")
	.buildRequest()
	.get();

Important

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)


result, err := graphClient.UsersById("user-id").Get()

Important

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


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId

Important

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$requestResult = $graphServiceClient->usersById('user-id')->get();

Important

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.

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

{
      "displayName": "Adele Vance",
      "givenName": "Adele",
      "jobTitle": "Retail Manager",
      "mail": "AdeleV@contoso.onmicrosoft.com",
      "mobilePhone": "+1 425 555 0109",
      "officeLocation": "18/2111",
      "preferredLanguage": "en-US",
      "surname": "Vance",
      "userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

Example 3: Use $select to retrieve specific properties of a user

To retrieve specific properties, use the OData $select query parameter. For example, to return displayName, givenName, postalCode, and identities, you would use the add the following to your query $select=displayName,givenName,postalCode,identities

Request

GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}?$select=displayName,givenName,postalCode,identities


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Users["{user-id}"]
	.Request()
	.Select("displayName,givenName,postalCode,identities")
	.GetAsync();

Important

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


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/{id | userPrincipalName}')
	.select('displayName,givenName,postalCode,identities')
	.get();

Important

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.users("{id | userPrincipalName}")
	.buildRequest()
	.select("displayName,givenName,postalCode,identities")
	.get();

Important

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &graphconfig.UserRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","givenName","postalCode","identities"},
}
configuration := &graphconfig.UserRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.UsersById("user-id").GetWithRequestConfigurationAndResponseHandler(configuration, nil)

Important

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


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "displayName,givenName,postalCode,identities"

Important

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UserRequestBuilderGetRequestConfiguration();

$queryParameters = new UserRequestBuilderGetQueryParameters();
$queryParameters->select = ["displayName","givenName","postalCode","identities"];

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->usersById('user-id')->get($requestConfiguration);

Important

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

Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(displayName,givenName,postalCode,identities)/$entity",
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "postalCode": "98004",
    "identities": [
        {
            "signInType": "userPrincipalName",
            "issuer": "contoso.com",
            "issuerAssignedId": "AdeleV@contoso.com"
        }
    ]
}

Example 4: Get the custom security attribute assignments of the specified user

The following example gets the custom security attributes of the specified user.

Attribute #1

Attribute set: Engineering
Attribute: Project
Attribute data type: Collection of Strings
Attribute value: ["Baker","Cascade"]

Attribute #2

Attribute set: Engineering
Attribute: CostCenter
Attribute data type: Collection of Integers
Attribute value: [1001]

Attribute #3

Attribute set: Engineering
Attribute: Certification
Attribute data type: Boolean
Attribute value: true

Attribute #4

Attribute set: Marketing
Attribute: Level
Attribute data type: String
Attribute value: "Public"

To get custom security attribute assignments, the calling principal must be assigned the Attribute Assignment Reader or Attribute Assignment Administrator role and must be granted the CustomSecAttributeAssignment.Read.All or CustomSecAttributeAssignment.ReadWrite.All permission.

Request

GET https://graph.microsoft.com/beta/users/{id}?$select=customSecurityAttributes


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Users["{user-id}"]
	.Request()
	.Select("customSecurityAttributes")
	.GetAsync();

Important

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


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/{id}')
	.version('beta')
	.select('customSecurityAttributes')
	.get();

Important

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.users("{id}")
	.buildRequest()
	.select("customSecurityAttributes")
	.get();

Important

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &graphconfig.UserRequestBuilderGetQueryParameters{
	Select: [] string {"customSecurityAttributes"},
}
configuration := &graphconfig.UserRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.UsersById("user-id").GetWithRequestConfigurationAndResponseHandler(configuration, nil)

Important

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


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "customSecurityAttributes"

Important

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UserRequestBuilderGetRequestConfiguration();

$queryParameters = new UserRequestBuilderGetQueryParameters();
$queryParameters->select = ["customSecurityAttributes"];

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->usersById('user-id')->get($requestConfiguration);

Important

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

Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        },
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Level": "Public"
        }
    }
}

If there are no custom security attributes assigned to the user or if the calling principal does not have access, the following will be the response:

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}

Example 5: Get the value of a schema extension for a user

In this example, the ID of the schema extension is ext55gb1l09_msLearnCourses.

Request

GET https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Users["{user-id}"]
	.Request()
	.Select("ext55gb1l09_msLearnCourses")
	.GetAsync();

Important

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


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e')
	.version('beta')
	.select('ext55gb1l09_msLearnCourses')
	.get();

Important

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


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.users("4562bcc8-c436-4f95-b7c0-4f8ce89dca5e")
	.buildRequest()
	.select("ext55gb1l09_msLearnCourses")
	.get();

Important

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &graphconfig.UserRequestBuilderGetQueryParameters{
	Select: [] string {"ext55gb1l09_msLearnCourses"},
}
configuration := &graphconfig.UserRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

result, err := graphClient.UsersById("user-id").GetWithRequestConfigurationAndResponseHandler(configuration, nil)

Important

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


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "ext55gb1l09_msLearnCourses"

Important

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


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestConfiguration = new UserRequestBuilderGetRequestConfiguration();

$queryParameters = new UserRequestBuilderGetQueryParameters();
$queryParameters->select = ["ext55gb1l09_msLearnCourses"];

$requestConfiguration->queryParameters = $queryParameters;


$requestResult = $graphServiceClient->usersById('user-id')->get($requestConfiguration);

Important

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

Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
    "ext55gb1l09_msLearnCourses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseType": "Developer",
        "courseName": "Introduction to Microsoft Graph",
        "courseId": 1
    }
}

Get a user

Permissions

HTTP request

Optional query parameters

Request headers

Request body

Response

Example

Example 1: Get the properties of the signed-in user

Request

Response

Example 2: Get the properties of the specified user

Request

Response

Example 3: Use $select to retrieve specific properties of a user

Request

Response

Example 4: Get the custom security attribute assignments of the specified user

Request

Response

Example 5: Get the value of a schema extension for a user

Request

Response

See also

Feedback