Working with users in Microsoft Graph

You can use Microsoft Graph to build compelling app experiences based on users, their relationships with other users and groups, and their mail, calendar, and files.

You can access users through Microsoft Graph in two ways:

  • By their ID, /users/{id | userPrincipalName}
  • By using the /me alias for the signed-in user, which is the same as /users/{signed-in user's id}


One of the following permissions is required to access user operations. The first three permissions can be granted to an app by a user. The rest can only be granted to an app by the administrator.

  • User.ReadBasic.All
  • User.Read
  • User.ReadWrite
  • User.Read.All
  • User.ReadWrite.All
  • Directory.Read.All
  • Directory.ReadWrite.All
  • Directory.AccessAsUser.All

Common properties

The following represent the default set of properties that are returned when getting a user or listing users. These are a subset of all available properties. To get more user properties, use the $select query parameter.

Property Description
id The unique identifier for the user.
businessPhones The user's phone numbers.
displayName The name displayed in the address book for the user.
givenName The first name of the user.
jobTitle The user's job title.
mail The user's email address.
mobilePhone The user's cellphone number.
officeLocation The user's physical office location.
preferredLanguage The user's language of preference.
surname The last name of the user.
userPrincipalName The user's principal name.

For details and a list of all the properties, see the user object.

Common operations

Note: Some of these operations require additional permissions.

Path Description
/users Lists users in the organization.
/users/{id} Gets a specific user by id.
/users/{id}/photo/$value Gets the user's profile photo.
/users/{id}/manager Gets the user's manager.
/users/{id}/messages Lists the user's email messages in their primary inbox.
/users/{id}/events Lists the user's upcoming events in their calendar.
/users/{id}/drive Gets the user's OneDrive file store.
/users/{id}/memberOf Lists the groups that the user is a member of.

What's new

Find out about the latest new features and updates for this API set.