Get a user
Namespace: microsoft.graph
Retrieve the properties and relationships of user object.
Note: Getting a user returns a default set of properties only (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName). Use
$select
to get the other properties and relationships for the user object.
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}
For the signed-in user:
GET /me
Optional query parameters
This method supports the OData Query Parameters to help customize the response.
By default, only a limited set of properties are returned ( businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName ).
To return an alternative property set, you must specify the desired set of user properties using the OData $select
query parameter. For example, to return displayName, givenName, and postalCode, you would use the add the following to your query $select=displayName,givenName,postalCode
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.
This method returns 202 Accepted
when the request has been processed successfully but the server requires more time to complete related background operations.
Examples
Example 1: Standard users request
By default, only a limited set of properties are returned ( businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName ). This example illustrates the default request and response.
GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}
Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 491
{
"businessPhones": [
"+1 425 555 0109"
],
"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: Signed-in user request
You can get the user information for the signed-in user by replacing /users/{id | userPrincipalName}
with /me
.
Request
GET https://graph.microsoft.com/v1.0/me
Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 491
{
"businessPhones": [
"+1 425 555 0109"
],
"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: Users request using $select
If you need a different property set, you can use the OData $select
query parameter. For example, to return displayName, givenName, and postalCode, you would use the add the following to your query $select=displayName,givenName,postalCode
Request
GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}?$select=displayName,givenName,postalCode
Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 491
{
"displayName": "Adele Vance",
"givenName": "Adele",
"postalCode": "98004"
}