Returning.AIDevelopers
v1

API reference / User Fields

.md

Update a user field definition

Rename one of your custom user fields, change its type, or set or clear its default, keeping the same key.

Last updated 26 Sep 2026API v1

Method
PUT
Path
https://api.returning.ai/v1/communities/{communityId}/user-fields/{fieldIdOrName}
Permission
userFields
Retries
Same body, same result; retry after reading back

When to use this

  • A field's display name in the dashboard should change, such as KYC status becoming KYC verification.
  • You picked the wrong type when you created a field and need to correct it.
  • You want new traders to start with a default value, or want to remove one.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
userFieldsShown in the dashboard as “User Fields”

Use a Community API key with the userFields permission, and keep it on your server. communityId must be the ID of the community that owns the key.

Behaviour#

Only the properties you send change; the rest keep their current values. The key in field never changes, so value writes and history reads that use it keep working after a rename.

Built-in fields, such as email, total_xp and total_coins, can't be updated. Nor can a field marked as a user identifier, such as your broker identifier field.

Changing the type or default doesn't touch traders' existing values or their history: nothing is converted or checked. New value writes must suit the new type. History reads show the field's current type, even on entries written under the old one.

A field changed to single-select-dropdown or multi-select-dropdown can't have values written yet.

Request#

Path parameters#

communityId#stringREQUIRED
Your community's ID. It must be the community that owns your API key.

Rule24 hex characters

Eg"66f000000000000000000010"

fieldIdOrName#stringREQUIRED
The key of the field to change, or its _id. Not the display name.

RuleField key or 24-character ID

Eg"kycstatus"

Headers#

Authorization#stringREQUIRED
Community API key with userFields.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send at least one of name, type and defaultValue. Any other property, including field, is rejected.

  • name is trimmed. It must be unique in your community, ignoring case, and use only ASCII letters, numbers, spaces, - and _. Changing only the capitals of the current name is allowed.
  • type can be any of the nine field types.
  • defaultValue must match the field's type after this update exactly, with the same rules as Create a user field definition: for example a JSON number for numerical and true or false for boolean, never a string such as "0" or "false". null removes the default.

If you change type and the current default doesn't suit the new type, the update is rejected with 400 INVALID_FIELD_DEFINITION and detail.defaultValue. Send a new defaultValue, or null, in the same request.

name#stringOPTIONAL
Optional. The new display name. Unique in your community, ignoring case.

RuleASCII letters, numbers, spaces, - and _

Eg"KYC verification"

type#stringOPTIONAL
Optional. The new field type. Any of the nine types is allowed.

Rulesingle-line-text, multi-line-text, numerical, date, time, date-time, boolean, single-select-dropdown, multi-select-dropdown

Eg"single-line-text"

defaultValue#anyOPTIONAL
Optional. The new default, in the field's type after this update. Send null to remove the default.

RuleMatches the type; see Request body

Eg"pending"

curl --request PUT \
  --url https://api.returning.ai/v1/communities/66f000000000000000000010/user-fields/kycstatus \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "KYC verification",
    "defaultValue": "pending"
  }'

Response#

A 200 returns the whole definition after the update. Branch on the HTTP status and meta.code, never on message.

meta#objectALWAYS

Eg{ ... }

status#stringALWAYS

Rulesuccess

statusCode#integerALWAYS

Rule200

code#stringALWAYS
Machine-readable result code.

RuleUSER_FIELD_UPDATED

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Update user field api success."

data#objectALWAYS
The definition after the update.

Eg{ ... }

_id#stringALWAYS
The definition's ID. It doesn't change.

Rule^[0-9a-fA-F]{24}$

Eg"66f000000000000000000510"

name#stringALWAYS
The stored display name, trimmed.

Eg"KYC verification"

field#stringALWAYS
The field key. It never changes.

Rulea-z, 0-9, _, -

Eg"kycstatus"

type#stringALWAYS
The field type.

Rulesingle-line-text, multi-line-text, numerical, date, time, date-time, boolean, single-select-dropdown, multi-select-dropdown

Eg"single-line-text"

defaultValue#any
The stored default. null when you removed it, and left out when the field never had one.

Eg"pending"

isCustom#booleanALWAYS
Always true. Only custom fields can be updated.
createdAt#stringALWAYS
When the definition was created.
updatedAt#stringALWAYS
When the definition last changed, which is the time of this update.
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "USER_FIELD_UPDATED"
  },
  "message": "Update user field api success.",
  "data": {
    "_id": "66f000000000000000000510",
    "name": "KYC verification",
    "field": "kycstatus",
    "type": "single-line-text",
    "defaultValue": "pending",
    "isCustom": true,
    "createdAt": "2026-09-26T08:30:00.000Z",
    "updatedAt": "2026-09-27T09:00:00.000Z"
  }
}

Errors#

Every JSON error carries its code in meta.code. The exception is a request with no Authorization header and a JSON body: it returns 400 with a non-JSON body instead of 401. A 400, 404 or 409 changes nothing. An empty body, an extra property, an unknown type or an empty name is rejected first. Then the field must exist, be custom and not be an identifier field, and only then are the new name and default checked.

Fix the request05

400Fix the request
No Authorization header was sent. With a JSON body this returns 400 with a non-JSON body (Request body must encrypted), not 401. Send Authorization: Bearer <API_KEY>.
400INVALID_FIELD_DEFINITIONFix the request
The body is empty, has a property other than name, type or defaultValue (such as field, which can't change), or breaks a rule. detail names the property when it can; it is {} for an empty body or an extra property. Nothing was changed.
401AUTHENTICATION_REQUIREDFix the request
The key is invalid or expired, or no key was sent with an empty body. Send Authorization: Bearer <API_KEY> with a current Community API key.
403API_KEY_PERMISSION_DENIEDFix the request
The key lacks userFields. Add the permission in Settings > Integration > API Keys.
403API_KEY_COMMUNITY_MISMATCHFix the request
communityId is not the community that owns your key. Use your own community's ID.

Fix the data05

404USER_FIELD_NOT_FOUNDFix the data
No field in your community has this key or ID. This endpoint never creates a field; check the key with List user field definitions, or create the field.
409USER_FIELD_UPDATE_FORBIDDENFix the data
The field is built in, such as email or total_xp. Only fields your community created can be changed.
409USER_FIELD_UPDATE_IDENTIFIER_LOCKEDFix the data
The field is marked as a user identifier, such as your broker identifier field, and can't be changed through the API.
409USER_FIELD_NAME_CONFLICTFix the data
Another field already has this name, ignoring case. Choose another name.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff01

500USER_FIELD_OPERATION_FAILEDRetry with backoff
At 409, the field changed while your update ran and nothing was saved. At 500, the outcome is unclear. Read the field with Get a user field definition, then send the same body again if it still differs.
{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "INVALID_FIELD_DEFINITION"
  },
  "message": "Update user field api error.",
  "detail": {
    "name": [
      "name may contain only ASCII letters, numbers, spaces, hyphens, and underscores."
    ]
  },
  "solution": "Read error detail and try again."
}

Next step#

Get a user field definitionGET/v1/communities/{communityId}/user-fields/{fieldIdOrName}Read the field back and confirm its name, type and default.