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": 0,
    "coins": 0,
    "roles": ["@all"],
    "highestRole": "@all",
    "customFields": {
      "customerid": "<brokerCustomerId>"
    }
  }
}

Additional profile, tier, language, streak, and activity fields may be present. 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

🟠400Error

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠409Record Not Found

🔴500Server Error

🔴503Error

curl --location 'https://api.returning.ai/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": 0, "coins": 0, "roles": [ "@all" ], "highestRole": "@all", "customFields": { "customerid": "<brokerCustomerId>" } } }

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