Update User Data, Identifier, And Roles
Developing
POST
/v1/users/update
What this endpoint does
INFO
Quick start
{
"identifier": { "type": "platform_user_id", "value": "3247779" },
"updates": {
"firstname": "Augusta",
"roles": { "operator": "add", "names": ["VIP"] }
}
}Authentication and permission
manageUser. A request containing updates.roles requires both manageUser and bulkUpdateUser. Keep the Community API key server-side.identifier.type is platform_user_id, username, email, or custom_user_identifier. It selects the existing user. updates contains only the requested changes.Complete examples
{
"identifier": { "type": "email", "value": "user@example.com" },
"updates": { "firstname": "Augusta", "phone": "15551234567" }
}{
"identifier": { "type": "platform_user_id", "value": "3247779" },
"updates": { "custom_user_identifier": "<newBrokerCustomerId>" }
}custom_user_identifier while changing that same identifier. Locate by platform ID or username. custom_user_identifier must be the only property in updates.roles.operator with add, subtract, or overwrite, and a non-empty unique roles.names array. add and subtract are idempotent by membership. overwrite replaces mutable current-community roles while retaining protected defaults and foreign-community roles.Success and readback
{
"status": "success",
"code": "USER_UPDATED",
"message": "User updated successfully",
"data": {
"id": "3247779",
"firstname": "Augusta",
"lastname": "Lovelace",
"email": "ada@example.com",
"phone": "15551234567",
"custom_user_identifier": "<brokerCustomerId>",
"roles": ["@all", "VIP"]
}
}roles is present when the request changes roles. Read back with POST /v1/users/info. After an identifier change, also inspect the narrow identifier history before issuing dependent tokens or further writes.CHECK
Errors and recovery
400 INVALID_USER_UPDATE: identifier, updates, property, or role operation is malformed.400 MIXED_IDENTIFIER_UPDATE_NOT_SUPPORTED: identifier replacement was combined with another update. Nothing is written; split the operation.400 ROLE_NOT_FOUND, ROLE_NAME_AMBIGUOUS, or PROTECTED_ROLE_CHANGE_REJECTED: fix the role request.401 AUTHENTICATION_REQUIRED / 403 API_KEY_PERMISSION_DENIED: fix authentication or required permissions.404 USER_NOT_FOUND: the selected identity is not active in this community.409 USER_EMAIL_CONFLICT or USER_IDENTIFIER_CONFLICT: reconcile the identity already owning the target value.500 USER_UPDATE_RECONCILIATION_REQUIRED: identifier history/projection cleanup is ambiguous. Stop automatic retries and read back.500 USER_UPDATE_FAILED: unexpected persistence failure; confirm current state before retrying.Retry safety
WARNING
Idempotency-Key. Role add and subtract are membership-idempotent, but a network timeout can still hide the response. Read the user back before repeating any update. Never retry an identifier replacement while reconciliation is required.Gotchas
Next steps
Request
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/users/update' \
--header 'Authorization: Bearer <apiKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"identifier": {
"type": "email",
"value": "ada@example.com"
},
"updates": {
"firstname": "Augusta",
"phone": "15551234567"
}
}'Response Response Example
200 - Success Example
{
"status": "success",
"code": "USER_UPDATED",
"message": "User updated successfully",
"data": {
"id": "3247779",
"firstname": "Augusta",
"lastname": "Lovelace",
"email": "ada@example.com",
"phone": "15551234567",
"custom_user_identifier": "<brokerCustomerId>",
"roles": [
"@all",
"VIP"
]
}
}Modified at 2026-07-27 16:00:26