Box Developer Documentation
Log in
Latest version

Add or update user avatar

post
https://api.box.com/2.0
/users/:user_id/avatar

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

Adds or updates a user avatar.

Request

bearer [ACCESS_TOKEN]
multipart/form-data

Path Parameters

stringin pathrequired
12345

The ID of the user.

Request Body

string (binary)in bodyrequired

The image file to be uploaded to Box. Accepted file extensions are .jpg or .png. The maximum file size is 1MB.

Response

application/jsonUser avatar
  • ok: Returns the pic_urls object with URLs to existing user avatars that were updated.
application/jsonUser avatar
  • created: Returns the pic_urls object with URLS to user avatars uploaded to Box with the request.
application/jsonClient error
  • bad_request: Returns an error when:
    • An image is not included in the request
    • The uploaded file is empty
    • The image size exceeds 1024 * 1024 pixels or 1MB
    • The file extension is other than .jpg or .png.
application/jsonClient error
  • forbidden: Returns an error if the user does not have permissions necessary to upload an avatar or is not activated.
application/jsonClient error
  • not_found: Returns an error if the user does not exist or cannot be found.
application/jsonClient error

An unexpected client error.

post
Add or update user avatar
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X -L POST "https://api.box.net/2.0/users/12345/avatar" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     --form 'pic=@"path/to/file/file.jpeg"'
TypeScript Gen
await client.avatars.createUserAvatar(user.id, {
  pic: decodeBase64ByteStream(
    'iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==',
  ),
  picContentType: 'image/png',
  picFileName: 'avatar.png',
} satisfies CreateUserAvatarRequestBody);
Python Gen
client.avatars.create_user_avatar(
    user.id,
    decode_base_64_byte_stream(
        "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg=="
    ),
    pic_file_name="avatar.png",
    pic_content_type="image/png",
)
.NET Gen
await client.Avatars.CreateUserAvatarAsync(userId: user.Id, requestBody: new CreateUserAvatarRequestBody(pic: Utils.DecodeBase64ByteStream(data: "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==")) { PicContentType = "image/png", PicFileName = "avatar.png" });
Swift Gen (Beta)
try await client.avatars.createUserAvatar(userId: user.id, requestBody: CreateUserAvatarRequestBody(pic: Utils.decodeBase64ByteStream(data: "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg=="), picContentType: "image/png", picFileName: "avatar.png"))
Java
String userID = "33333";
BoxUser user = new BoxUser(api, userID);
AvatarUploadResponse response = user.uploadAvatar(new File("path_to_avatar_file"));
Python
avatar_urls = client.user('33333').upload_avatar(image_path='path/to/the/image.png')
.NET
using (FileStream fileStream = new FileStream(filePath, FileMode.Open))
{
    BoxUploadAvatarResponse response = await client.UsersManager.AddOrUpdateUserAvatarAsync(userId, fileStream);
}
Node
const fs = require('fs');
var readStream = fs.createReadStream('image.jpg');
client.users.setAvatar('22222', readStream).then(result => {
    // read avatar urls
});
iOS
let image: UIImage = <YOUR_IMAGE_HERE> // Initialize image here e.g. from UIImagePickerController
let data = image.jpegData(compressionQuality: 1)!

client.users.uploadAvatar(userId: "33333", data: data, name: "avatar.jpeg") { result in
    guard case let .success(uploadAvatar) = result else {
        print("Error uploading user avatar")
        return
    }

    print("User avatar uploaded successfully!")
}

Response Example

{
  "pic_urls": {
    "large": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks\npac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw\njtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc\ngSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC\nao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r",
    "preview": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks!\npac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW\nk-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ\n04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl\nsSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc\n9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g",
    "small": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw\n"
  }
}