Get a user

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, Directory.AccessAsUser.All
Delegated (personal Microsoft account) User.Read, User.ReadWrite
Application User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Calling the /me endpoint requires a signed-in user and therefore a delegated permission. Application permissions are not supported when using the /me endpoint.

HTTP request

For a specific user:

GET /users/{id | userPrincipalName}

Note:

  • When the userPrincipalName begins with a $ character, remove the slash (/) after /users and enclose the userPrincipalName in parentheses and single quotes. For example, /users('$AdeleVance@contoso.com'). For details, see the known issues list.
  • 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.

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
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}

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

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.ReadWrite.All permission.

Request

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

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
}

See also