Returning.AIDevelopers
v1

API reference / User Fields

.md

Get a user field definition

Read one user field's definition by its key or ID, to check its name, type and default before you write values.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/communities/{communityId}/user-fields/{fieldIdOrName}
Permission
userFields
Retries
Read-only; exact retries are safe

When to use this

  • Before you write a trader's value, confirm the field's type so the value suits it.
  • After you create or update a field, read it back to check what was saved.
  • Your integration stores field keys and you want to check that one still exists.

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. The key only reads its own community: communityId must be the ID of the community that owns the key.

Behaviour#

This returns the field's definition, not any trader's value. It works for built-in fields, such as email or total_xp, as well as your own. Look the field up by its key or by its _id; the display name is not accepted.

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 field key, or the definition's _id. Not the display name. Capitals and spaces are cleaned up as on create, so KYCStatus finds kycstatus.

RuleField key or 24-character ID

Eg"kycstatus"

Headers#

Authorization#stringREQUIRED
Community API key with userFields.

RuleBearer <API_KEY>

curl --request GET \
  --url https://api.returning.ai/v1/communities/66f000000000000000000010/user-fields/kycstatus \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the definition in data. Branch on the HTTP status and meta.code, never on message. Check type before you write a value, and isCustom before you try to update the field: built-in fields can't be changed.

meta#objectALWAYS

Eg{ ... }

status#stringALWAYS

Rulesuccess

statusCode#integerALWAYS

Rule200

code#stringALWAYS
Machine-readable result code.

RuleUSER_FIELD_RETRIEVED

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

Eg"Read user field api success."

data#objectALWAYS
The field's definition.

Eg{ ... }

_id#stringALWAYS
The definition's ID. Accepted wherever a field key is.

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

Eg"66f000000000000000000510"

name#stringALWAYS
Display name shown in the dashboard. It can be renamed, so do not build on it.

Eg"KYC status"

field#stringALWAYS
The field key. Use it in every value write and history read. It never changes.

Rulea-z, 0-9, _, -; up to 120 chars

Eg"kycstatus"

type#stringALWAYS
The field type. It decides which values you can write.

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 default, in the field's type. null or left out when there is none.
isCustom#booleanALWAYS
true for fields your community created, false for built-in fields. Only custom fields can be updated.
createdAt#string
When the definition was created.
updatedAt#string
When the definition last changed.
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "USER_FIELD_RETRIEVED"
  },
  "message": "Read user field api success.",
  "data": {
    "_id": "66f000000000000000000510",
    "name": "KYC status",
    "field": "kycstatus",
    "type": "single-line-text",
    "isCustom": true,
    "createdAt": "2026-09-26T08:30:00.000Z",
    "updatedAt": "2026-09-26T08:30:00.000Z"
  }
}

Errors#

Every error carries its code in meta.code, except a fieldIdOrName that isn't a valid key or ID: that returns 400 with a detail object and no code. A 404 means the key doesn't exist in your community.

Fix the request04

400Fix the request
fieldIdOrName isn't a valid key or ID: after cleanup it must be 1-120 characters of a-z, 0-9, _ and -. detail names the problem. This error has no code.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. 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 data02

404USER_FIELD_NOT_FOUNDFix the data
No field in your community has this key or ID. Check the key with List user field definitions before you create a field with it.
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
The field could not be read. Retry the same request with exponential backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Read user field api validation error.",
  "detail": {
    "fieldIdOrName": "field must use ASCII letters, numbers, \"_\", or \"-\" after normalization."
  },
  "solution": "Check your params in request and try again"
}

Next step#

Update a user field valuePOST/v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/historiesWrite a trader's value that suits the field's type.