Update A User Field Definition
PUT
/v1/communities/{communityId}/user-fields/{fieldIdOrName}
What this endpoint does
field key cannot be changed.INFO
Quick start
{ "name": "Lifetime Trading Volume", "type": "numerical", "defaultValue": 0 }Authentication and permission
userFields. The caller must be an owner or administrator. The path accepts stable key or ObjectId. The body must contain at least one supported change.Complete examples
{ "name": "Lifetime Trading Volume" }{ "defaultValue": null }{ "type": "boolean", "defaultValue": false }field; it is immutable. If a type change would make an existing/default value invalid, choose a compatible value or clear the default deliberately.Success and readback
{
"meta": { "status": "success", "statusCode": 200, "code": "USER_FIELD_UPDATED" },
"message": "Update user field api success.",
"data": {
"_id": "<fieldObjectId>",
"name": "Lifetime Trading Volume",
"field": "trading_volume",
"type": "numerical",
"defaultValue": 0,
"isCustom": true
}
}CHECK
Errors and recovery
400 INVALID_FIELD_DEFINITION: body, type, or default is invalid.400 INVALID_FIELD_DEFINITION: also returned when the body attempts to change the immutable field key; remove that property.401 AUTHENTICATION_REQUIRED / 403 API_KEY_PERMISSION_DENIED: fix key or owner/admin access.404 USER_FIELD_NOT_FOUND: PUT does not upsert; create separately if appropriate.409 USER_FIELD_UPDATE_FORBIDDEN: built-in or otherwise protected field.409 USER_FIELD_NAME_CONFLICT: choose a unique display name.500 USER_FIELD_OPERATION_FAILED: state may be unclear; read before retrying.Retry safety
WARNING
Idempotency-Key. After a timeout or 5xx, GET the definition by stable key and compare every requested property before deciding whether to repeat the update.Gotchas
Next steps
Request
Path Params
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request PUT 'https://api.returning.ai/v1/communities/6502c9e514a3e564c5c09c0a/user-fields/trading_volume' \
--header 'Authorization: Bearer <apiKey>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Lifetime Trading Volume"
}'Response Response Example
200 - Success Example
{
"meta": {
"status": "success",
"statusCode": 200,
"code": "USER_FIELD_UPDATED"
},
"message": "Update user field api success.",
"data": {
"_id": "66f000000000000000000010",
"name": "Lifetime Trading Volume",
"field": "trading_volume",
"type": "numerical",
"defaultValue": 0,
"isCustom": true
}
}Modified at 2026-07-27 16:00:54