Box Developer Documentation
Log in
Latest version

Update user

put
https://api.box.com/2.0
/users/:user_id

Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.

Request

bearer [ACCESS_TOKEN]
application/json

Path Parameters

stringin pathrequired
12345

The ID of the user.

Query Parameters

string arrayin queryoptional
id,type,name

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

Request Body

stringin bodyoptional
"900 Jefferson Ave, Redwood City, CA 94063"
255

The user’s address

booleanin bodyoptional
true

Whether the user can see other enterprise users in their contact list

stringin bodyoptional

Set this to null to roll the user out of the enterprise and make them a free user

stringin bodyoptional
"my-user-1234"

An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users.

Note: In order to update this field, you need to request a token using the application that created the app user.

booleanin bodyoptional
true

Whether to exempt the user from enterprise device limits

booleanin bodyoptional
true

Whether the user must use two-factor authentication

booleanin bodyoptional
true

Whether the user is allowed to collaborate with users outside their enterprise

booleanin bodyoptional
true

Whether the user is required to reset their password

booleanin bodyoptional
true

Whether the user can use Box Sync

stringin bodyoptional
"CEO"
100

The user’s job title

stringin bodyoptional
"en"

The language of the user, formatted in modified version of the ISO 639-1 format.

stringin bodyoptional
"somename@box.com"

The email address the user uses to log in

Note: If the target user's email is not confirmed, then the primary login address cannot be changed.

stringin bodyoptional
"Aaron Levie"
50

The name of the user

objectin body

An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address.

Set this value to null to remove the notification email.

stringin bodyoptional
"notifications@example.com"

The email address to send the notifications to.

booleanin bodyoptional
true

Whether the user should receive an email when they are rolled out of an enterprise

stringin bodyoptional
"6509241374"
100

The user’s phone number

stringin bodyoptional
"user"

The user’s enterprise role

Value is one of coadmin,user

integer (int64)in bodyoptional
11345156112

The user’s total available space in bytes. Set this to -1 to indicate unlimited storage.

stringin bodyoptional
"active"

The user's account status

Value is one of active,inactive,cannot_delete_edit,cannot_delete_edit_upload

string (timezone)in bodyoptional
"Africa/Bujumbura"

The user's timezone

object arrayin bodyoptional

Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used.

stringin bodyoptional
"tracking_code"

tracking_code

Value is always tracking_code

stringin bodyoptional
"department"

The name of the tracking code, which must be preconfigured in the Admin Console

stringin bodyoptional
"Sales"

The value of the tracking code

Response

application/jsonUser (Full)

Returns the updated user object.

application/jsonClient error

Returns an error if some of the parameters are missing or not valid.

  • invalid_parameter when a parameter is formatted incorrectly, for example when the notification_email has an incorrectly formatted email address.
application/jsonClient error

Returns an error if the user is not allowed to make the changes.

  • access_denied_insufficient_permissions when the user does not have the right permissions, for example when updating the notification email is turned off for the enterprise.
  • denied_by_policy when the user does not have the right permissions due to the information barrier restrictions.
application/jsonClient error

An unexpected client error.

put
Update user
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X PUT "https://api.box.com/2.0/users/12345" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "name": "Aaron Levie"
     }'
TypeScript Gen
await client.users.updateUserById(user.id, {
  requestBody: { name: updatedUserName } satisfies UpdateUserByIdRequestBody,
} satisfies UpdateUserByIdOptionalsInput);
Python Gen
client.users.update_user_by_id(user.id, notification_email=create_null())
.NET Gen
await client.Users.UpdateUserByIdAsync(userId: user.Id, requestBody: new UpdateUserByIdRequestBody() { NotificationEmail = null });
Java
BoxUser user = new BoxUser(api, "0");
BoxUser.Info info = user.new Info();
info.setName(name);
user.updateInfo(info);
Python
user_id = '33333'
user = client.user(user_id)
updated_user = user.update_info(data={'name': 'Smart User'})
.NET
var updates = new BoxUserRequest()
{
    Id = "44444",
    Role = "coadmin",
    CanSeeManagedUsers = true
};
BoxUser updatedUser = await client.UsersManager.UpdateUserInformationAsync(updates);
Node
client.users.update('33333', {name: 'New Name', job_title: 'New Title', phone: '555-1111'})
    .then(user => {
        /* user -> {
            type: 'user',
            id: '33333',
            name: 'New Name',
            login: 'user@example.com',
            created_at: '2012-03-26T15:43:07-07:00',
            modified_at: '2012-12-12T11:34:29-08:00',
            language: 'en',
            space_amount: 5368709120,
            space_used: 2377016,
            max_upload_size: 262144000,
            status: 'active',
            job_title: 'New Title',
            phone: '555-1111',
            address: '555 Office Drive',
            avatar_url: 'https://app.box.com/api/avatar/deprecated' }
        */
    });
iOS
// Restrict the user from collaborating content externally
client.users.update(userId: "33333", isExternalCollabRestricted: true) { (result: Result<User, BoxSDKError>) in
    guard case let .success(user) = result else {
        print("Error updating user")
        return
    }

    print("Updated user \(user.name), with login \(user.login)")
}

Response Example

{
  "id": "11446498",
  "type": "user",
  "address": "900 Jefferson Ave, Redwood City, CA 94063",
  "avatar_url": "https://www.box.com/api/avatar/large/181216415",
  "can_see_managed_users": true,
  "created_at": "2012-12-12T10:53:43-08:00",
  "enterprise": {
    "id": "11446498",
    "type": "enterprise",
    "name": "Acme Inc."
  },
  "external_app_user_id": "my-user-1234",
  "hostname": "https://example.app.box.com/",
  "is_exempt_from_device_limits": true,
  "is_exempt_from_login_verification": true,
  "is_external_collab_restricted": true,
  "is_platform_access_only": true,
  "is_sync_enabled": true,
  "job_title": "CEO",
  "language": "en",
  "login": "ceo@example.com",
  "max_upload_size": 2147483648,
  "modified_at": "2012-12-12T10:53:43-08:00",
  "my_tags": [
    "important"
  ],
  "name": "Aaron Levie",
  "notification_email": {
    "email": "notifications@example.com",
    "is_confirmed": true
  },
  "phone": "6509241374",
  "role": "admin",
  "space_amount": 11345156112,
  "space_used": 1237009912,
  "status": "active",
  "timezone": "Africa/Bujumbura",
  "tracking_codes": [
    {
      "type": "tracking_code",
      "name": "department",
      "value": "Sales"
    }
  ]
}