Create A User Field Definition

What this endpoint does

Creates one typed custom user-field definition. Use definitions to model broker identifiers, trading metrics, statuses, dates, flags, and internal notes before writing values. The lowercase field key is immutable and should be stored in integration configuration.

INFO

Workflow

Create field -> read field

Quick start

{
  "name": "Trading Volume",
  "field": "trading_volume",
  "type": "numerical",
  "defaultValue": 0
}

Authentication and permission

Use a community API key with userFields. The caller must be a community owner or administrator. Personal message API keys are not recognized by this application-service route.

Complete examples

Supported type values are single-line-text, multi-line-text, numerical, date, time, date-time, boolean, single-select-dropdown, and multi-select-dropdown.

Copyable examples for every type:

{ "name": "Account Tier", "field": "account_tier", "type": "single-line-text", "defaultValue": "standard" }

{ "name": "Internal Notes", "field": "internal_notes", "type": "multi-line-text", "defaultValue": "" }

{ "name": "Trading Volume", "field": "trading_volume", "type": "numerical", "defaultValue": 0 }

{ "name": "KYC Date", "field": "kyc_date", "type": "date", "defaultValue": "2026-07-21" }

{ "name": "Market Open", "field": "market_open", "type": "time", "defaultValue": "08:30:00" }

{ "name": "Last Sync", "field": "last_sync", "type": "date-time", "defaultValue": "2026-07-21T08:30:00Z" }

{ "name": "KYC Complete", "field": "kyc_complete", "type": "boolean", "defaultValue": false }

{ "name": "Segment", "field": "segment", "type": "single-select-dropdown", "defaultValue": "gold" }

{ "name": "Eligible Plans", "field": "eligible_plans", "type": "multi-select-dropdown", "defaultValue": ["gold", 2] }

Omitting defaultValue and sending null both mean no default. Non-null defaults must match the exact field type. Numerical defaults are JSON numbers, booleans are JSON booleans, date uses YYYY-MM-DD, time uses HH:mm:ss, and date-time uses an ISO-like timestamp. Select defaults may use finite numbers as well as strings; multi-select defaults are arrays of those scalar values.

Success and readback

{
  "meta": {
    "status": "success",
    "statusCode": 201,
    "code": "USER_FIELD_CREATED",
    "compatibilityEvent": "attempted"
  },
  "message": "Create user field api success.",
  "data": {
    "_id": "<fieldObjectId>",
    "name": "Trading Volume",
    "field": "trading_volume",
    "type": "numerical",
    "defaultValue": 0,
    "isCustom": true,
    "createdAt": "2026-07-21T00:00:00.000Z",
    "updatedAt": "2026-07-21T00:00:00.000Z"
  }
}

Read back by data.field or data._id. compatibilityEvent: "failed" means the downstream compatibility event failed after the definition committed. idempotencyPersistence: "degraded" is a separate warning that the completed replay record could not be persisted.

CHECK

Readback

Run the follow-up read named above. Compare the returned identifiers and final stored values.

Errors and recovery

400 INVALID_FIELD_DEFINITION: fix name, key, type, or typed default.

400 INVALID_IDEMPOTENCY_KEY: supply 1 to 200 visible ASCII characters with no spaces or control characters.

401 AUTHENTICATION_REQUIRED / 403 API_KEY_PERMISSION_DENIED: use a recognized community key and authorized owner/admin.

404 COMMUNITY_NOT_FOUND: fix community scope.

409 USER_FIELD_NAME_CONFLICT or USER_FIELD_KEY_CONFLICT: read the existing definition and reconcile.

409 IDEMPOTENCY_KEY_CONFLICT: the same key was reused with a different normalized definition.

409 IDEMPOTENCY_REQUEST_IN_PROGRESS: read by stable key before deciding whether another logical operation is needed.

503 IDEMPOTENCY_STORE_UNAVAILABLE: creation did not start because safe deduplication was unavailable.

Retry safety

WARNING

Retry rule

Use one community-scoped Idempotency-Key for one logical definition. Exact normalized replays return the original 201, including omitted versus explicit-null default. A different definition under the key conflicts. Keep the key for 24 hours and read back after any ambiguous result.

Gotchas

Avoid this mistake

Next steps

Read the field

Read the definition by stable key. Then use POST /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories for supported scalar values. Use list endpoints to audit field history.

application/json

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

Bodyapplication/json

curl --location 'https://api.returning.ai/v1/communities/6502c9e514a3e564c5c09c0a/user-fields' \ --header 'Authorization: Bearer <apiKey>' \ --header 'Idempotency-Key: usrfld-20260720-0001' \ --header 'Content-Type: application/json' \ --data '{ "name": "Account Tier", "field": "account_tier", "type": "single-line-text", "defaultValue": "standard" }'

{ "meta": { "status": "success", "statusCode": 201, "code": "USER_FIELD_CREATED", "compatibilityEvent": "attempted" }, "message": "Create user field api success.", "data": { "_id": "66f000000000000000000010", "communityID": "6502c9e514a3e564c5c09c0a", "name": "Trading Volume", "field": "trading_volume", "type": "numerical", "defaultValue": 0, "isCustom": true, "createdAt": "2026-07-21T00:00:00.000Z", "updatedAt": "2026-07-21T00:00:00.000Z" } }

Create A User Field Definition

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

Create A User Field Definition

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