List User Field Definitions

What this endpoint does

Lists every user-field definition readable in one community. Use it to discover stable field keys, types, defaults, and legacy/built-in definitions before creating integrations or writing values. This endpoint returns definitions, not user values or history rows.

INFO

Workflow

List fields -> choose stable field key

Quick start

Replace {communityId} with the community's 24-character Mongo ObjectId.

Authentication and permission

Use a server-side community APIKeyModel key with userFields. The authenticated principal must belong to the community. Application-service user-field routes do not accept personal message API keys. A missing or unrecognized key returns 401 AUTHENTICATION_REQUIRED before field data is read.

Complete examples

Populated collection:

{
  "meta": { "status": "success", "statusCode": 200, "code": "USER_FIELDS_LISTED" },
  "message": "Read user fields api success.",
  "data": [
    {
      "_id": "<fieldObjectId>",
      "name": "Trading Volume",
      "field": "trading_volume",
      "type": "numerical",
      "defaultValue": 0,
      "isCustom": true
    }
  ]
}

An empty community is still a successful read:

{
  "meta": { "status": "success", "statusCode": 200, "code": "USER_FIELDS_LISTED" },
  "message": "Read user fields api success.",
  "data": []
}

This endpoint is not paginated. One response contains the complete readable definition collection for the community.

Success and readback

Use data[].field as the durable integration key. name is display text and can change. _id is accepted by item endpoints but is less portable in configuration. Before a value write, confirm the definition's type and whether isCustom permits management operations.

CHECK

Readback

This response is the readback. Save the returned identifiers if another call follows.

Errors and recovery

400 INVALID_COMMUNITY_ID: fix the path value; it must be a 24-character ObjectId.

401 AUTHENTICATION_REQUIRED: supply a recognized community API key.

403 API_KEY_PERMISSION_DENIED or COMMUNITY_ACCESS_DENIED: the key/principal cannot read this community.

500 USER_FIELD_OPERATION_FAILED: retry the read with bounded backoff and preserve the request time for support.

Retry safety

TIP

Retry rule

This GET is read-only and safe to retry exactly after transport or 5xx failures. Cache definitions only when you have an invalidation strategy; a display name, type, or default may change while the stable field key does not.

Gotchas

Avoid this mistake

Next steps

Read one field

Use GET /v1/communities/{communityId}/user-fields/{fieldIdOrName} for one definition. Create missing custom definitions with POST. Use the canonical user-first history endpoint to write or audit a value after confirming the field type.

application/json

Read user fields api success. Branch on the HTTP status and meta.code; do not branch on the human-readable message.

Bodyapplication/json

{ "meta": { "status": "success", "statusCode": 200, "code": "USER_FIELDS_LISTED", "total": 1 }, "message": "Read user fields api success.", "data": [ { "_id": "66f000000000000000000010", "name": "Trading Volume", "field": "trading_volume", "type": "numerical", "defaultValue": 0, "isCustom": true } ] }

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

List User Field Definitions

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps