Update A User Field Value
POST
/v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories
What this endpoint does
overwrite for supported scalar fields and increase or decrease for numerical fields. The user-first route shown here is the only supported write route.INFO
Quick start
{ "value": 10, "action": "increase" }Authentication and permission
userFields. The principal must be a community owner or administrator. {userId} accepts email, Mongo ObjectId, numeric platform ID, or username. {fieldIdOrName} accepts the stable field key or field ObjectId. URL-encode email addresses.Complete examples
{ "value": false, "action": "overwrite" }{ "value": 0, "action": "overwrite" }{ "value": "", "action": "overwrite" }increase and decrease require a JSON number. Omitting action defaults to overwrite when supported. Select definitions may be created, but select-value writes are not supported by this endpoint.Success and readback
{
"meta": {
"status": "success",
"statusCode": 201,
"code": "USER_FIELD_VALUE_UPDATED"
},
"message": "Update user field value api success.",
"data": {
"value": 10,
"action": "increase",
"storedValue": 110,
"updatedValue": 110,
"fieldID": "<fieldObjectId>",
"fieldName": "trading_volume",
"fieldType": "numerical",
"userID": "<mongoUserId>",
"userNumericID": 3247779,
"updated": true
}
}idempotentReplay. An exact replay of a completed keyed request adds "idempotentReplay": true. If the write committed but saving the replay record degraded, the response may instead add "idempotencyPersistence": "degraded"; perform readback before retrying.value and action echo the caller's magnitude and operation. storedValue/updatedValue represent the resulting projection when available. Read back with the narrow user-and-field history route and the approved current-value read.CHECK
Errors and recovery
400 INVALID_FIELD_VALUE or INVALID_FIELD_ACTION: fix type/action without coercing meaningful falsy values. Select definitions currently reach INVALID_FIELD_VALUE because this endpoint does not support select-value mutation.400 INVALID_IDEMPOTENCY_KEY: use 1 to 200 visible ASCII characters.400 USER_IDENTIFIER_UPDATE_REJECTED: use Update User Data for an intentional active-identifier change.401 AUTHENTICATION_REQUIRED / 403 API_KEY_PERMISSION_DENIED: use a recognized community key and owner/admin access.403 USER_NOT_IN_COMMUNITY: the user exists but is not a member of this key's community.404 USER_NOT_FOUND or USER_FIELD_NOT_FOUND: resolve the user and field inside the same community.409 IDEMPOTENCY_KEY_CONFLICT or IDEMPOTENCY_REQUEST_IN_PROGRESS: the key belongs to a different request or the original request is still running.409 USER_IDENTIFIER_CONFLICT: the requested active identifier belongs to another user.409 USER_FIELD_MUTATION_IN_PROGRESS: another numerical mutation still owns the resource lock; no mutation started.500 USER_FIELD_VALUE_PROJECTION_FAILED: projection failed and rollback was confirmed; read back before retrying.500 USER_FIELD_HISTORY_RECONCILIATION_REQUIRED: cleanup could not be proven; outcome is ambiguous.500 USER_FIELD_HISTORY_INTERNAL_ERROR: an unexpected controller failure occurred.503 IDEMPOTENCY_STORE_UNAVAILABLE or USER_FIELD_MUTATION_LOCK_UNAVAILABLE: safe coordination was unavailable and the mutation did not start.Retry safety
WARNING
Idempotency-Key only with the exact same user identifier, field identifier, value, and action. Different equivalent identifiers still conflict because the public request identity changed. After lock contention, retry the exact keyed request with bounded backoff. After an in-progress/ambiguous result, perform narrow readback and never create a new key to bypass ownership.Gotchas
Next steps
Request
Path Params
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/communities/6502c9e514a3e564c5c09c0a/users/user@example.com/user-fields/trading_volume/histories' \
--header 'Authorization: Bearer <apiKey>' \
--header 'Idempotency-Key: usrfld-20260720-0001' \
--header 'Content-Type: application/json' \
--data '{
"value": false,
"action": "overwrite"
}'Response Response Example
201 - Success Example
{
"meta": {
"status": "success",
"statusCode": 201,
"code": "USER_FIELD_VALUE_UPDATED",
"sum": 110,
"updated": true
},
"message": "Update user field value api success.",
"data": {
"_id": "66f000000000000000000020",
"communityID": "6502c9e514a3e564c5c09c0a",
"userID": "66f000000000000000000021",
"userNumericID": 3247779,
"fieldID": "66f000000000000000000010",
"fieldName": "trading_volume",
"fieldType": "numerical",
"value": 10,
"action": "increase",
"storedValue": 110,
"updatedValue": 110,
"createdAt": "2026-07-21T00:00:00.000Z",
"updatedAt": "2026-07-21T00:00:00.000Z",
"updated": true
}
}Modified at 2026-07-27 16:01:08