Update user

Important: APIs under the /beta version in Microsoft Graph are in preview and are subject to change. Use of these APIs in production applications is not supported.

Update the properties of a user object.

Prerequisites

One of the following scopes is required to execute this API: User.ReadWrite; User.ReadWrite.All; Directory.ReadWrite.All

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. Supports $filter.
assignedLicenses assignedLicense collection The licenses that are assigned to the user. Not nullable.
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 would look like this: '2014-01-01T00:00:00Z'
city String The city in which the user is located. Supports $filter.
country String The country/region in which the user is located; for example, “US” or “UK”. Supports $filter.
department String The name for the department in which the user works. Supports $filter.
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. Supports $filter and $orderby.
givenName String The given name (first name) of the user. Supports $filter.
hireDate 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 would look like this: '2014-01-01T00:00:00Z'
interests String collection A list for the user to describe their interests.
jobTitle String The user’s job title. Supports $filter.
mailNickname String The mail alias for the user. This property must be specified when a user is created. Supports $filter.
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.
onPremisesImmutableId String This property is used to associate an on-premises Active Directory user account to their Azure AD 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. Supports $filter.
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".
passwordProfile PasswordProfile Specifies the password profile for the user. The profile contains the user’s password. This property is required when a user is created. The password in the profile must satisfy minimum requirements as specified by the passwordPolicies property. By default, a strong password is required.
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".
preferredName String The preferred name for the user.
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. Supports $filter.
streetAddress String The street address of the user's place of business.
surname String The user's surname (family name or last name). Supports $filter.
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. Supports $filter.
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. This property is required when a user is created. The verified domains for the tenant can be accessed from the verifiedDomains property of organization. Supports $filter and $orderby.
userType String A string value that can be used to classify user types in your directory, such as “Member” and “Guest”. Supports $filter.

Since the user resource supports extensions, you can use the PATCH operation to add, update, or delete your own app-specific data in custom properties of an extension in an existing user instance.

Response

If successful, this method returns a 204 No Content response code.

Example

Request

Here is an example of the request.

PATCH https://graph.microsoft.com/beta/me
Content-type: application/json
Content-length: 491

{
  "accountEnabled": true,
  "assignedLicenses": [
    {
      "disabledPlans": [ "bea13e0c-3828-4daa-a392-28af7ff61a0f" ],
      "skuId": "skuId-value"
    }
  ],
  "assignedPlans": [
    {
      "assignedDateTime": "2016-10-19T10:37:00Z",
      "capabilityStatus": "capabilityStatus-value",
      "service": "service-value",
      "servicePlanId": "bea13e0c-3828-4daa-a392-28af7ff61a0f"
    }
  ],
  "businessPhones": [
    "businessPhones-value"
  ],
  "city": "city-value",
  "companyName": "companyName-value"
}
Response

Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 204 No Content

See also