Update A User Field Value

POST

/v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories

Write a field value and create its audit history. overwrite is valid for supported scalar fields; increase and decrease are numerical only.

Preserved values

The API intentionally preserves JSON false, numerical 0, empty valid multi-line text "", and ordinary strings through validation, history creation, current-value projection, and the response.

Select boundary

Select definitions are supported, but select-value mutation is not. Do not send select values until that separate feature is released.

Retry safety

Use an Idempotency-Key. Exact retries replay the first 201. A key reused with different identifiers, value, or action returns 409 IDEMPOTENCY_KEY_CONFLICT. If reconciliation is required, read this user's narrow field history before doing anything else.

Request

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

User field value updated successfully. Branch on the HTTP status and meta.code; do not branch on the human-readable message.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠409

🔴500Server Error

Request Example

Shell

JavaScript

Java

Swift

cURL

booleanFalsenumericalZeroemptyMultilineincrease

curl --location 'https://sgtr-api.returning.ai/v1/communities//users//user-fields//histories' \
--header 'Authorization;' \
--header 'Idempotency-Key;' \
--header 'Content-Type: application/json' \
--data '{
    "value": false,
    "action": "overwrite"
}'

Response Example

201 - Success Example

{
    "meta": {
        "status": "success",
        "statusCode": 201,
        "code": "USER_FIELD_VALUE_UPDATED",
        "idempotentReplay": false
    },
    "message": "Update user field value api success.",
    "data": {
        "value": 0,
        "action": "overwrite",
        "storedValue": 0,
        "updatedValue": 0,
        "fieldID": "trading_volume",
        "userID": "3247779"
    }
}

Modified at 2026-07-20 18:50:42

List One User's One Field

Deprecated Field-First History Write

Update A User Field Value

Preserved values#

Select boundary#

Retry safety#

Request

Responses

Preserved values

Select boundary

Retry safety