Update the properties of a user object. Not all properties can be updated by Member or Guest users with their default permissions without Administrator roles. Compare member and guest default permissions to see properties they can manage.
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.
To update sensitive user properties, such as accountEnabled, mobilePhone, and otherMails for users with privileged administrator roles:
In delegated scenarios, the app must be assigned the Directory.AccessAsUser.All delegated permission and the calling user must have a higher privileged administrator role as indicated in Who can perform sensitive actions.
In app-only scenarios, the app must be assigned a higher privileged administrator role as indicated in Who can perform sensitive actions.
Your personal Microsoft account must be tied to a Microsoft Entra tenant to update your profile with the User.ReadWrite delegated permission on a personal Microsoft account.
Updating the identities property requires the User.ManageIdentities.All permission. Also, adding a B2C local account to an existing user object is not allowed, unless the user object already contains a local account identity.
HTTP request
PATCH /users/{id | userPrincipalName}
Request headers
Header
Value
Authorization
Bearer {token}. Required.
Content-Type
application/json
Request body
In the request body, supply the values for relevant fields that should be updated. Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance you shouldn't include existing values that haven't changed.
Property
Type
Description
aboutMe
String
A freeform text entry field for the user to describe themselves.
accountEnabled
Boolean
true if the account is enabled; otherwise, false. This property is required when a user is created. A global administrator assigned the Directory.AccessAsUser.All delegated permission can update the accountEnabled status of all administrators in the tenant.
Sets the age group of the user. Allowed values: null, Minor, NotAdult and Adult. Refer to the legal age group property definitions for further information.
birthday
DateTimeOffset
The birthday of the user. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z
businessPhones
String collection
The telephone numbers for the user. NOTE: Although this is a string collection, only one number can be set for this property.
city
String
The city in which the user is located.
companyName
String
The company name which the user is associated. This property can be useful for describing the company that an external user comes from. The maximum length is 64 characters.
Sets whether consent has been obtained for minors. Allowed values: null, Granted, Denied and NotRequired. Refer to the legal age group property definitions for further information.
country
String
The country/region in which the user is located; for example, US or UK.
An open complex type that holds the value of a custom security attribute that is assigned to a directory object.
To update this property, the calling principal must be assigned the Attribute Assignment Administrator role and must be granted the CustomSecAttributeAssignment.ReadWrite.All permission.
department
String
The name for the department in which the user works.
displayName
String
The name displayed in the address book for the user. This is usually the combination of the user's first name, middle initial and last name. This property is required when a user is created and it cannot be cleared during updates.
employeeId
String
The employee identifier assigned to the user by the organization. The maximum length is 16 characters.
employeeType
String
Captures enterprise worker type. For example, Employee, Contractor, Consultant, or Vendor. Returned only on $select.
givenName
String
The given name (first name) of the user.
employeeHireDate
DateTimeOffset
The hire date of the user. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z
employeeLeaveDateTime
DateTimeOffset
The date and time when the user left or will leave the organization. The timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z.
For delegated scenarios, the calling user must have the Global Administrator role and the calling app assigned the User.Read.All and User-LifeCycleInfo.ReadWrite.All delegated permissions.
Represents organization data (e.g. division and costCenter) associated with a user.
interests
String collection
A list for the user to describe their interests.
jobTitle
String
The user's job title.
mail
String
The SMTP address for the user, for example, jeff@contoso.onmicrosoft.com. Changes to this property will also update the user's proxyAddresses collection to include the value as a SMTP address. For Azure AD B2C accounts, this property can be updated up to only ten times with unique SMTP addresses. Cannot be updated to null.
mailNickname
String
The mail alias for the user. This property must be specified when a user is created.
mobilePhone
String
The primary cellular telephone number for the user.
mySite
String
The URL for the user's personal site.
officeLocation
String
The office location in the user's place of business.
Contains extensionAttributes 1-15 for the user. Note that the individual extension attributes are neither selectable nor filterable. For an onPremisesSyncEnabled user, the source of authority for this set of properties is the on-premises and is read-only and is read-only. These extension attributes are also known as Exchange custom attributes 1-15.
onPremisesImmutableId
String
This property is used to associate an on-premises Active Directory user account to their Microsoft Entra user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user's userPrincipalName (UPN) property. Important: The $ and _ characters cannot be used when specifying this property.
otherMails
String collection
A list of additional email addresses for the user; for example: ["bob@contoso.com", "Robert@fabrikam.com"].
passwordPolicies
String
Specifies password policies for the user. This value is an enumeration with one possible value being DisableStrongPassword, which allows weaker passwords than the default policy to be specified. DisablePasswordExpiration can also be specified. The two may be specified together; for example: DisablePasswordExpiration, DisableStrongPassword.
Specifies the password profile for the user. The profile contains the user's password. The password in the profile must satisfy minimum requirements as specified by the passwordPolicies property. By default, a strong password is required. As a best practice, always set the forceChangePasswordNextSignIn to true. This cannot be used for federated users.
In delegated access, the calling app must be assigned the Directory.AccessAsUser.All delegated permission on behalf of the signed-in user. In application-only access, the calling app must be assigned the User.ReadWrite.All application permission and at least the User AdministratorMicrosoft Entra role.
pastProjects
String collection
A list for the user to enumerate their past projects.
postalCode
String
The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code.
preferredLanguage
String
The preferred language for the user. Should follow ISO 639-1 Code; for example en-US.
responsibilities
String collection
A list for the user to enumerate their responsibilities.
schools
String collection
A list for the user to enumerate the schools they have attended.
skills
String collection
A list for the user to enumerate their skills.
state
String
The state or province in the user's address.
streetAddress
String
The street address of the user's place of business.
surname
String
The user's surname (family name or last name).
usageLocation
String
A two letter country code (ISO standard 3166). Required for users that will be assigned licenses due to legal requirement to check for availability of services in countries. Examples include: US, JP, and GB. Not nullable.
userPrincipalName
String
The user principal name (UPN) of the user. The UPN is an Internet-style login name for the user based on the Internet standard RFC 822. By convention, this should map to the user's email name. The general format is alias@domain, where domain must be present in the tenant's collection of verified domains. The verified domains for the tenant can be accessed from the verifiedDomains property of organization. NOTE: This property cannot contain accent characters. Only the following characters are allowed A - Z, a - z, 0 - 9, ' . - _ ! # ^ ~. For the complete list of allowed characters, see username policies.
userType
String
A string value that can be used to classify user types in your directory, such as Member and Guest.
Note
The following properties cannot be updated by an app with only application permissions: aboutMe, birthday, employeeHireDate, interests, mySite, pastProjects, responsibilities, schools, and skills.
To update the following properties, you must specify them in their own PATCH request, without including the other properties listed in the table above: aboutMe, birthday, interests, mySite, pastProjects, responsibilities, schools, and skills.
Manage extensions and associated data
Use this API to manage the directory, schema, and open extensions and their data for users, as follows:
Add, update and store data in the extensions for an existing user
For directory and schema extensions, remove any stored data by setting the value of the custom extension property to null. For open extensions, use the Delete open extension API.
Response
If successful, this method returns a 204 No Content response code.
Example
Example 1: Update properties of the signed-in user
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
BusinessPhones = new List<string>
{
"+1 425 555 0109",
},
OfficeLocation = "18/2111",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$requestBody->setBusinessPhones(['+1 425 555 0109', ]);
$requestBody->setOfficeLocation('18/2111');
$result = $graphServiceClient->me()->patch($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = User(
business_phones = [
"+1 425 555 0109",
],
office_location = "18/2111",
)
result = await graph_client.me.patch(request_body)
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
BusinessPhones = new List<string>
{
"+1 425 555 0109",
},
OfficeLocation = "18/2111",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$requestBody->setBusinessPhones(['+1 425 555 0109', ]);
$requestBody->setOfficeLocation('18/2111');
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = User(
business_phones = [
"+1 425 555 0109",
],
office_location = "18/2111",
)
result = await graph_client.users.by_user_id('user-id').patch(request_body)
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
PasswordProfile = new PasswordProfile
{
ForceChangePasswordNextSignIn = false,
Password = "xWwvJ]6NMw+bWH-d",
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users patch --user-id {user-id} --body '{\
"passwordProfile": {\
"forceChangePasswordNextSignIn": false,\
"password": "xWwvJ]6NMw+bWH-d"\
}\
}\
'
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$passwordProfile = new PasswordProfile();
$passwordProfile->setForceChangePasswordNextSignIn(false);
$passwordProfile->setPassword('xWwvJ]6NMw+bWH-d');
$requestBody->setPasswordProfile($passwordProfile);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = User(
password_profile = PasswordProfile(
force_change_password_next_sign_in = False,
password = "xWwvJ]6NMw+bWH-d",
),
)
result = await graph_client.users.by_user_id('user-id').patch(request_body)
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
AdditionalData = new Dictionary<string, object>
{
{
"ext55gb1l09_msLearnCourses" , new
{
CourseType = "Admin",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users patch --user-id {user-id} --body '{\
"ext55gb1l09_msLearnCourses": {\
"courseType": "Admin"\
}\
}\
'
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$additionalData = [
'ext55gb1l09_msLearnCourses' => [
'courseType' => 'Admin',
],
];
$requestBody->setAdditionalData($additionalData);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = User(
additional_data = {
"ext55gb1l09_ms_learn_courses" : {
"course_type" : "Admin",
},
}
)
result = await graph_client.users.by_user_id('user-id').patch(request_body)
To remove the value of the schema extension from the user object, set the ext55gb1l09_msLearnCourses property to null.
Response
HTTP/1.1 204 No Content
Example 5: Assign a custom security attribute with a string value to a user
The following example shows how to assign a custom security attribute with a string value to a user.
Attribute set: Engineering
Attribute: ProjectDate
Attribute data type: String
Attribute value: "2022-10-01"
To assign custom security attributes, the calling principal must be assigned the Attribute Assignment Administrator role and must be granted the CustomSecAttributeAssignment.ReadWrite.All permission.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
ProjectDate = "2022-10-01",
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'projectDate' => '2022-10-01',
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();