Clerk API (unofficial showcase)
POST/users/{user_id}/profile_image

Set a user profile image

Sets or replaces a user's profile image. Send the image in the file field as multipart form data, and use user_id to identify the account to update. A 200 response returns the updated user object.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 1 body field
user_idstringrequired
The unique identifier of the user whose profile image you want to set.

Multipart form data for the user's profile image upload.

filestringoptional
The binary image file to use as the user's profile image.

4 status codes
200Returns the updated user object, including its identifier, image URL, and image-presence flag.
idstringrequired
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:user
external_idstringrequired
primary_email_address_idstringrequired
primary_phone_number_idstringrequired
primary_web3_wallet_idstringrequired
usernamestringrequired
first_namestringrequired
last_namestringrequired
localestringoptional
timezonestringoptional
profile_image_urlstringdeprecatedoptional
image_urlstringoptional
has_imagebooleanrequired
public_metadataobjectrequired
private_metadataobjectoptional
unsafe_metadataobjectoptional
email_addressesarray<object>required
phone_numbersarray<object>required
web3_walletsarray<object>required
passkeysarray<object>required
password_enabledbooleanrequired
two_factor_enabledbooleanrequired
totp_enabledbooleanrequired
backup_code_enabledbooleanrequired
mfa_enabled_atintegerrequired
Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled.
mfa_disabled_atintegerrequired
Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again.
password_last_updated_atintegeroptional
Unix timestamp of when the user's password was last updated.
external_accountsarray<object>required
saml_accountsarray<object>required
enterprise_accountsarray<object>required
organization_membershipsarray<object>optional
last_sign_in_atintegerrequired
Unix timestamp of last sign-in.
bannedbooleanrequired
Flag to denote whether user is banned or not.
lockedbooleanrequired
Flag to denote whether user is currently locked, i.e. restricted from signing in or not.
deprovisionedbooleanoptional
Flag to denote whether user has been deprovisioned and is restricted from signing in.
lockout_expires_in_secondsintegerrequired
The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.
verification_attempts_remainingintegerrequired
The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.
updated_atintegerrequired
Unix timestamp of last update.
created_atintegerrequired
Unix timestamp of creation.
delete_self_enabledbooleanrequired
If enabled, user can delete themselves via FAPI.
create_organization_enabledbooleanrequired
If enabled, user can create organizations via FAPI.
create_organizations_limitintegeroptional
The maximum number of organizations the user can create. 0 means unlimited.
last_active_atintegerrequired
Unix timestamp of the latest session activity, with day precision.
legal_accepted_atintegerrequired
Unix timestamp of when the user accepted the legal requirements.
bypass_client_trustbooleanoptional
When set to `true`, the user will bypass Device Trust checks during sign-in.
Default:false
directoriesarray<object>optional
All loaded directory links. Omitted when links were not loaded; an empty array means the user has no directory links.
directoryobjectdeprecatedoptional
The most recently updated directory link. Use directories for all links.
scimobjectdeprecatedoptional
Alias of directory. Use directories for all links.
400Returned when the upload request is invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Returned when the request is not authorized.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Returned when the specified user cannot be found.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned when the upload request is invalid. A 401 is returned when the request is not authorized, and a 404 is returned when the user cannot be found. The user_id path parameter must identify the user whose profile image you want to set.