1. User Fields
Returning.AI
  • Getting Started
  • Bulk Operations
    • Bulk user updates
    • List bulk update jobs
      GET
    • Get bulk update job status
      GET
    • Get bulk update job details
      GET
    • Bulk update users from CSV
      POST
    • Bulk update premium currency from CSV
      POST
  • Chart Analysis
    • Create Analysis
      POST
    • Get Analysis
      GET
    • Update Analysis
      PATCH
    • Delete Analysis
      DELETE
    • List Analyses
      GET
    • Append Drawings
      POST
  • Rewards & Redemptions
    • Redemption lifecycle
    • Store catalog to redemptions
    • Update redemption order status or refund
      PUT
    • List redemption orders by user email
      POST
    • List redemption statuses
      POST
    • Get redemption status by ID
      POST
    • List redemption orders by community
      POST
    • Create redemption order status
      POST
    • Get redemption order status history
      POST
    • List redemption orders by custom-field identifier
      POST
  • Gamification
    • Leaderboards
      • Leaderboards
      • List leaderboards with pagination
      • Create a new leaderboard
      • Update an existing leaderboard
      • Get a single leaderboard by ID
      • Delete a leaderboard
    • Streaks & Mini Games
      • Mini-game State and History
      • List user streak logs
      • List mini-game logs by user email
      • Get current mini-game and streak state
      • Update user spin-wheel information
    • Referral
      • Referral Program Integration
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
    • Match Predictions
      • Create match prediction
      • List match predictions
      • Get match prediction
      • Patch match prediction
      • Publish match prediction
      • Settle match prediction
      • Get settlement results
      • Void match prediction
      • Bulk update match predictions
      • Get bulk job status
      • Get bulk job results
    • Loyalty Points
      • Create loyalty points export
      • Get loyalty points export status
      • Get loyalty points export download link
    • Quizzes
      • Create quiz
      • List quizzes
      • Get quiz
      • Update quiz
      • Delete quiz
      • Add quiz question
      • Update quiz question
      • Delete quiz question
    • Get tier configuration
    • Get daily user XP and coin changes
    • Search user gamification logs
    • Get user activity stats
  • Messaging
    • Agent messaging workflow
    • Get Messages
    • Send Message
    • Reply Message
    • React Message
    • Upload message images
  • Users
    • User directory and provisioning
    • Get Users with Filters
    • Create New User
    • Get User Data
    • Manage User Account
    • Get User Milestones
    • Update User Data, Identifier, And Roles
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
    • Channels
    • Leaderboard
    • Milestone
    • Socials
    • Store
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Store
    • Store journey
    • Store catalog
    • Purchase History
      • Archive or restore an order
      • Update redemption instructions or voucher details
    • Categories
      • List Store categories
      • Create Store category
      • Get Store category by ID
      • Update Store category
      • Delete Store category
    • Products
      • List products
      • Create products in bulk
      • Create product with vouchers
      • Update products in bulk
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get redemption transaction detail
    • Get Store configuration
    • Update Store configuration
  • Community
    • Community directory and appearance
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • User Fields
    • User field definitions and history
    • User Field History
      • List Community User-Field History
      • List One Field Across Users
      • List One User Across Fields
      • List One User's One Field
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Create A User Field Definition
      POST
    • Get A User Field Definition
      GET
    • Update A User Field Definition
      PUT
    • Delete A User Field Definition
      DELETE
    • List User Field Definitions
      GET
  • API Keys
    • API key lifecycle
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Register user with password
      • Verify user email
      • Log in user with password
      • Secure Auth
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Get user
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  • Community Logs
    • Retrieve and export community logs
  1. User Fields

Get A User Field Definition

GET
https://sgtr-api.returning.ai/v1/communities/{communityId}/user-fields/{fieldIdOrName}
User Fields

What this endpoint does#

Returns one user-field definition by stable key or Mongo ObjectId. Use it as the precise readback after create or update and before writing a typed value. This endpoint returns field metadata, not a particular user's current value.
INFO
Workflow
Field key -> field definition

Quick start#

The path also accepts the definition's 24-character _id.

Authentication and permission#

Use a community APIKeyModel key with userFields. The caller must belong to the target community. Authentication and community isolation complete before the definition is returned.

Complete examples#

Lookup by stable key is recommended for integrations:
Lookup by ObjectId is useful when following a response:
{
  "meta": { "status": "success", "statusCode": 200, "code": "USER_FIELD_RETRIEVED" },
  "message": "Read user field api success.",
  "data": {
    "_id": "<fieldObjectId>",
    "name": "Trading Volume",
    "field": "trading_volume",
    "type": "numerical",
    "defaultValue": 0,
    "isCustom": true
  }
}

Success and readback#

Compare data.name, data.type, and data.defaultValue with the preceding create/update request. Store data.field as the durable key. data.isCustom tells management clients whether update/delete is eligible; built-in definitions are protected.
CHECK
Readback
This response is the readback. Save the returned identifiers if another call follows.

Errors and recovery#

400 INVALID_COMMUNITY_ID or INVALID_FIELD_IDENTIFIER: correct the path parameter.
401 AUTHENTICATION_REQUIRED: use a recognized community API key.
403 API_KEY_PERMISSION_DENIED or COMMUNITY_ACCESS_DENIED: fix permission/community membership.
404 COMMUNITY_NOT_FOUND: the community is unavailable.
404 USER_FIELD_NOT_FOUND: no definition matches the key/ObjectId. Re-list fields before deciding to create.
500 USER_FIELD_OPERATION_FAILED: retry this read with bounded backoff.

Retry safety#

TIP
Retry rule
This GET is read-only and safe to retry exactly after transport or server failures. Do not automatically turn a 404 into a create unless your workflow owns the definition and has checked both stable key and intended name.

Gotchas#

Avoid this mistake

Next steps#

Update the field
Use PUT to modify an eligible custom definition, DELETE to retire it after dependency checks, or the canonical user-first history endpoint to write a supported value. List definitions again when maintaining an integration cache.

Request

Path Params

Header Params

Responses

🟢200OK
application/json
Read user field api success. 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
🔴500Server Error
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://sgtr-api.returning.ai/v1/communities/6502c9e514a3e564c5c09c0a/user-fields/trading_volume' \
--header 'Authorization: Bearer <apiKey>'
Response Response Example
200 - Success Example
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "USER_FIELD_RETRIEVED"
  },
  "message": "Read user field api success.",
  "data": {
    "_id": "66f000000000000000000010",
    "name": "Trading Volume",
    "field": "trading_volume",
    "type": "numerical",
    "defaultValue": 0,
    "isCustom": true
  }
}
Modified at 2026-07-27 14:31:29
Previous
Create A User Field Definition
Next
Update A User Field Definition
Built with