Create A User Field Definition

POST

/v1/communities/{communityId}/user-fields

Create a typed field definition. The stable field key is immutable and recommended for integrations.

All nine definition types are supported. Select definitions can be created, but writing select values through the history mutation API is not supported yet. Typed defaults are strict: numerical values must be JSON numbers, booleans must be JSON booleans, and an empty string is valid only for multi-line text.

Exact replays with the same community-scoped Idempotency-Key return the original 201. A different payload with that key returns 409 IDEMPOTENCY_KEY_CONFLICT.

Request

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

User field created successfully. Branch on the HTTP status and meta.code; do not branch on the human-readable message.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠409

🔴500Server Error

Request Example

Shell

JavaScript

Java

Swift

cURL

numericalZerobooleanFalseemptyMultiline

curl --location 'https://sgtr-api.returning.ai/v1/communities//user-fields' \
--header 'Authorization;' \
--header 'Idempotency-Key;' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Trading Volume",
    "field": "trading_volume",
    "type": "numerical",
    "defaultValue": 0
}'

Response Example

201 - Success Example

{
    "meta": {
        "status": "success",
        "statusCode": 201,
        "code": "USER_FIELD_CREATED",
        "compatibilityEvent": "attempted"
    },
    "message": "User field created successfully.",
    "data": {
        "_id": "66f000000000000000000010",
        "communityID": "6502c9e514a3e564c5c09c0a",
        "name": "Trading Volume",
        "field": "trading_volume",
        "type": "numerical",
        "defaultValue": 0
    }
}

Modified at 2026-07-20 19:36:15

Deprecated Field-First History Read

Get Specific User Field