Update the Avatar Using the User API

Learn how to update the avatar using the User API.

Employee App
Front Door Intranet

An avatar is an image to visually distinguish a user's profile. In this article, you will learn how to update the avatars for a large number of users using the User API.

An avatar image consists of three different image types. There are image specifications for each image type. You need to provide a separate image URL for each image type in order to update the avatar image.

The image types are:

  • Original image: The original image is used when the user profile image is opened in full-screen mode. For optimal results, the image needs to be wider than 2000 px.
  • Icon image: The icon image displays the user image as a small circular icon. The image must be 48 by 48 px.
  • Thumb image: The thumb image is the minimized version of the user image. The thumb image must be 200 by 200 px.

For optimal results, Staffbase recommends providing three different image URLs for the original, thumb, and icon images when uploading an avatar image via User API. If you do not provide different URLs, the original image is used for both the icon and thumb images.


  • You have already created an API token with administrative access via the Staffbase Studio. Learn more.
  • You have the images stored in your media server, and the domain of the media server is allow listed for your app.
    For example, if your app URL is yourcompany.com and the media server is cdn.mediaserver.com, then you need to allow list cdn.mediaserver.com for your app.
  • You have either the externalID or id of the users' profiles you want to update.

Get familiar with the avatar data model. Understanding the data model helps you update avatar images optimally.

Bulk update avatars

To upload a user avatar, do the following:

Step 1: Get the URL to the avatar.
Step 2: Update the avatar of the user.

Step 1: Get the URL to the avatar

You can skip this step if you already have the URL to the avatar.

  1. Create an image file for avatar type original.
  2. Make a POST request to the endpoint /media to upload the file.
1export AUTH="Basic TOKEN"
2 export FILEPATH="C:/Users/Pictures/Original.png"
4 curl "https://exampleapp.staffbase.com/api/media" \
5 -X POST \
6 -H "Authorization: $AUTH" \
7 -H "Content-Type: multipart/form-data" \
8 -F 'file=@$FILEPATH'
9 --compressed | json_pp

Learn more about our Media API.

  1. Get the URL of the uploaded file from the request response.
    You can now use this URL to update the original image.

  2. Repeat the above steps to upload thumb and icon images to the Media API.

Step 2: Update the avatar

Make a POST request to the endpoint /users/{userID}. In the request body schema, under the object avatar, you need to set the url parameter for the following nested objects:

  • original
  • icon
  • thumb
1export USERID="5db0221d0a09a219c4ce9218"
2export AUTH="Basic TOKEN"
5curl "https://exampleapp.staffbase.com/api/users/$USERID" \
6-X POST \
7-H "Authorization: $AUTH" \
8-H "Content-Type: application/json" \
9--data-raw '{
10 "avatar":{
11 "original":{
12 "url":"https://cdn.mediaserver.com/yourimage.png",
13 "width":2000,
14 "height":1500
15 },
16 "icon":{
17 "url":"https://cdn.mediaserver.com/yourimage-icon.png",
18 },
19 "thumb":{
20 "url":"https://cdn.mediaserver.com/yourimage-thumb.png",
21 }
22 }
23 }'

You have updated the avatar of a user. To bulk update user avatars, add a function to loop through all users to perform your requests.