Get User Data

What this endpoint does

Returns one active user from the API key's community. Use it after Create User or Update User Data, before user-field writes, and when support or a broker sync needs the current profile, roles, balances, and selected custom fields. Missing, inactive, and out-of-community identities intentionally share the same privacy-safe 404 USER_NOT_FOUND response.

INFO

Workflow

User identifier -> current user data

Quick start

{
  "idOrEmail": "user@example.com",
  "customFields": ["customerid", "trading_volume"]
}

Authentication and permission

Use a server-side Community API key with getUserData. The key limits the lookup to its own community. Do not broaden the search after a privacy-safe 404 or expose whether the same identity exists elsewhere.

Complete examples

Lookup by email:

{ "idOrEmail": "user@example.com" }

Lookup by numeric Returning.AI platform ID:

{ "idOrEmail": "3247779" }

Legacy structured platform-ID lookup:

{ "identifier": { "key": "id", "value": "3247779" } }

Configured custom identifier lookup:

{ "identifier": { "key": "customerid", "value": "<brokerCustomerId>" } }

customFields is an optional allowlist of field keys to return. Prefer email or numeric platform ID for the most portable lookup. A custom identifier works only when that identifier is active and its projection is ready.

Success and readback

{
  "status": "success",
  "code": "USER_DATA_RETRIEVED",
  "message": "User data retrieved successfully",
  "data": {
    "_id": "<mongoUserId>",
    "userId": "3247779",
    "username": "ada_lovelace_123",
    "xp": 1250,
    "coins": 340,
    "roles": [
      "@all"
    ],
    "highestRole": "@all",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "xpEarnedToday": 25,
    "coinsEarnedToday": 10,
    "language": "English",
    "totalMessages": 42,
    "totalReactions": 17,
    "visitCount": 63,
    "replySent": 8,
    "timeSpent": 312.5,
    "loginStreak": 12,
    "tags": [
      "VIP"
    ],
    "current_tier": "Gold",
    "current_level": 3,
    "to_next_level": 150,
    "customFields": {
      "customerid": "<brokerCustomerId>"
    }
  }
}

Response fields

Field	Type	Meaning
`_id`	string	Internal platform user ID.
`userId`	string	Numeric platform user ID. Treat it as an opaque decimal string.
`username`	string	Display username.
`xp`, `coins`	number	Current XP total and coin balance in this community.
`roles`, `highestRole`	string[], string	Role names; `highestRole` is the highest-ranked role other than `@all`.
`firstName`, `lastName`	string	Masked as `********` when the member's GDPR consent does not allow sharing.
`language`	string	Selected language display name; `English` when none is set.
`xpEarnedToday`, `coinsEarnedToday`	number	Net XP and coin change for the current UTC day, including deductions.
`totalMessages`, `totalReactions`, `replySent`	integer	Lifetime messages, reactions, and replies in this community.
`visitCount`	integer	Lifetime recorded visits to this community (daily visits, not sessions).
`timeSpent`	number	Total active time in minutes, measured on the platform account rather than per community.
`loginStreak`	integer	Longest run of consecutive UTC days with a visit. This is the best-ever streak, not the current one.
`tags`	string[]	Tag names assigned to the member in this community.
`current_tier`	string	Tier calculated now from current XP and the tier configuration. Absent when no tiers are configured.
`current_level`	integer \| null	Level within the tier for level-based progression; `null` for value-range progression.
`to_next_level`	number	XP needed for the next level; level-based progression only, omitted at the top level.
`customFields`	object	Values for the requested `customFields` keys.

Tier is calculated at request time, so the response has no tier start date or tier history. For current wheel and streak counters, use Get current mini-game and streak state.

Treat data.userId as an opaque decimal string. For post-write verification, compare the returned identifier, roles, profile values, and requested custom fields with the preceding mutation.

CHECK

Readback

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

Errors and recovery

400 CUSTOM_FIELD_IDENTIFIER_NOT_FOUND: the supplied structured key is not an active custom identifier. Correct the key or use email/platform ID.

401 AUTHENTICATION_REQUIRED: the key is missing, malformed, invalid, or expired.

403 API_KEY_PERMISSION_DENIED: the key is valid but lacks getUserData.

404 USER_NOT_FOUND: no active user is visible to this community. Do not probe other communities or leak existence.

503 CUSTOM_FIELD_IDENTIFIER_NOT_READY: the configured custom-field lookup projection is unavailable. Use email/platform ID when possible or retry later with bounded backoff.

500 USER_DATA_RETRIEVAL_FAILED: preserve the request identifiers and correlation time for support; the request is read-only.

Retry safety

TIP

Retry rule

This endpoint is read-only, so an exact retry is safe after a transient transport error or 5xx. Use bounded exponential backoff. Do not change identifiers between retries because that turns one read into a broader identity probe.

Gotchas

Avoid this mistake

Next steps

Update the user

Use the returned userId or email with POST /v1/users/update. For one field's audit trail, call GET /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories. For current profile or balances, this response is the authoritative readback.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Responses

🟢200OK

application/json

User data retrieved successfully Branch on the HTTP status and top-level code; do not branch on the human-readable message.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠409Server Error

🔴500Server Error

🔴503Error

curl --location 'https://sgtr-integration.returning.ai/apis/v1/users/info' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "idOrEmail": "user@example.com", "customFields": [ "customerid" ] }'

{ "status": "success", "code": "USER_DATA_RETRIEVED", "message": "User data retrieved successfully", "data": { "_id": "<mongoUserId>", "userId": "3247779", "username": "ada_lovelace_123", "xp": 1250, "coins": 340, "roles": [ "@all" ], "highestRole": "@all", "firstName": "Ada", "lastName": "Lovelace", "xpEarnedToday": 25, "coinsEarnedToday": 10, "language": "English", "totalMessages": 42, "totalReactions": 17, "visitCount": 63, "replySent": 8, "timeSpent": 312.5, "loginStreak": 12, "tags": [ "VIP" ], "current_tier": "Gold", "current_level": 3, "to_next_level": 150, "customFields": { "customerid": "<brokerCustomerId>" } } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Response fields#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Response fields

Errors and recovery

Retry safety

Gotchas

Next steps