Skip to content

How-to work with profile images

This page explains how to read, upload/replace, and delete the profile image for a user in our platform. It is written for developers maintaining or integrating with the Profile Service.

Summary

  • Get current user's profile image (Base64): GET {{ profileService }}/me/profileimage
  • Delete current user's profile image: DELETE {{ profileService }}/me/profileimage
  • Presence indicator: On the Person entity, the profileImage property is present when a profile image exists, and missing or empty when none exists. This property is also included in Profile Notification messages.
  • Upload/replace via Media endpoints: Profile images are ordinary media objects uploaded through the Media endpoints with AdditionalType=ProfileImage. A user can have only one profile image. Posting another profile image replaces the current one as the active profile image. The old image remains in the user's media list.
  • Media endpoints reference: See Profile service endpoints description

Retrieve the current user's profile image (Base64)

Use this endpoint to fetch the profile image for the authorized (current) user.

Endpoint
GET {{ profileService }}/me/profileimage

Returns
- The image encoded as Base64.

Example (cURL)

curl -X GET "{{ profileService }}/me/profileimage"   -H "Authorization: Bearer <token>"

Delete the current user's profile image

Remove the active profile image for the authorized user.

Endpoint
DELETE {{ profileService }}/me/profileimage

Example (cURL)

curl -X DELETE "{{ profileService }}/me/profileimage"   -H "Authorization: Bearer <token>"

After deletion, the Person.profileImage property will be missing or empty until a new profile image is set.

Presence on the Person entity & notifications

  • The Person entity exposes a profileImage property only when a profile image exists. If the user does not have a profile image, this property is missing or empty.
  • The same profileImage property is included in Profile Notification messages, allowing subscribers to react to profile image creation, replacement, or removal.

Upload or replace the profile image (Media endpoints)

Profile images are normal media objects managed via the Media endpoints. To set the (single) profile image for a user, upload an image with AdditionalType=ProfileImage.

  • Only one active profile image per user. If a profile image already exists, posting another with AdditionalType=ProfileImage replaces the current active one for the profile.
  • The previously active image remains as a media item in the user's profile (it is not deleted automatically).
  • You may manage other media independently (e.g., scans, documents, password images, etc.).

API reference: Profile service endpoints description

Endpoint
POST {{ profileService }}/media?AdditionalType=ProfileImage

Body
- form-data with a single file field containing the image binary.

Example (cURL)

curl -X POST "{{ profileService }}/media?AdditionalType=ProfileImage"   -H "Authorization: Bearer <token>"   -H "Accept: application/json"   -F "file=@/path/to/profile.jpg"

Notes - Use the exact AdditionalType value: ProfileImage. - The newly uploaded media becomes the active profile image; the old one remains listed under the user's media. - To remove the active profile image from the profile, use DELETE {{ profileService }}/me/profileimage

Troubleshooting checklist

  • profileImage property missing: No active profile image is set—upload one via Media with AdditionalType=ProfileImage.
  • Client needs binary instead of Base64: Decode on the client or gateway, or fetch via an endpoint that returns binary.
  • Unexpected replacement: Remember that a new ProfileImage replaces the current active one.
  • Permissions: Ensure the caller is authorized; these endpoints operate on the current authorized user.