Returning.AIDevelopers
v1

API reference / User Fields

.md

List user field definitions

List every user field in your community, built-in and custom, with the key, type and default you need before you write values.

Last updated 26 Sep 2026API v1

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

When to use this

  • You are setting up an integration and need the exact key and type of each field, such as kycstatus.
  • Before you create a field, check that its key or name is not already taken.
  • You want to confirm a field's type before you write a trader's value.

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#

Every community has built-in fields, such as email, total_xp and total_coins, next to the fields you create. They come first in data, with isCustom: false; your own fields follow, newest first. The whole list comes back in one response.

Request#

Path parameters#

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

Rule24 hex characters

Eg"66f000000000000000000010"

Query parameters#

isCustom#booleanOPTIONAL
true returns only your custom fields. Omit it, or send false, to include built-in fields too.

Ruletrue, false, 1 or 0; default false

Headers#

Authorization#stringREQUIRED
Community API key with userFields.

RuleBearer <API_KEY>

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

Response#

A 200 returns the definitions in data. Branch on the HTTP status and meta.code, never on message. Save each field's field key: it is what value writes and history reads take, and it never changes, while name can be renamed.

meta#objectALWAYS

Eg{ ... }

status#stringALWAYS

Rulesuccess

statusCode#integerALWAYS

Rule200

code#stringALWAYS
Machine-readable result code.

RuleUSER_FIELDS_LISTED

total#integerALWAYS
Number of definitions in data.
message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Read user fields api success."

data#object[]ALWAYS
Every definition, built-in fields first, then custom fields newest first. Not paginated.

Eg[ ... ]

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

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

Eg"66f000000000000000000513"

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

Eg"Email"

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#boolean
true for fields your community created, false for built-in fields.
createdAt#string
When the definition was created.
updatedAt#string
When the definition last changed.
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "USER_FIELDS_LISTED",
    "total": 2
  },
  "message": "Read user fields api success.",
  "data": [
    {
      "_id": "66f000000000000000000513",
      "name": "Email",
      "field": "email",
      "type": "single-line-text",
      "isCustom": false,
      "createdAt": "2026-09-01T08:30:00.000Z",
      "updatedAt": "2026-09-01T08:30:00.000Z"
    },
    {
      "_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. An isCustom value other than true, false, 1 or 0 returns 400 with a detail object and no code.

Fix the request03

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 data01

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 list could not be read. Retry the same request with exponential backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 401,
    "code": "AUTHENTICATION_REQUIRED"
  },
  "message": "API request rejected error.",
  "detail": "A valid bearer token or API key is required for this endpoint.",
  "solution": "Read error detail and try again."
}

Next step#

Create a user field definitionPOST/v1/communities/{communityId}/user-fieldsMissing a field? Create it, then store the key it returns.