Returning.AIDevelopers
v1

API reference / Users

.md

Get User Data

Look up one trader in your community by email or platform user ID, and get back their profile, roles, coins, XP and the custom fields you ask for.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/users/info
Permission
getUserData
Retries
Read-only; exact retries are safe

When to use this

  • Confirm a trader exists after Create User or a registration webhook, and save their userId.
  • Read a trader's current coins, XP and roles before support changes anything.
  • Fetch a broker identifier such as customerid before you write user-field values.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
getUserDataShown in the dashboard as “Get User Data”

Use a Community API key from Settings > Integration > API Keys and keep it on your server. The key limits every lookup to its own community, so a trader in another community returns 404 USER_NOT_FOUND.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with getUserData.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send exactly one of idOrEmail or identifier. Sending neither or both returns 400.

idOrEmail#stringONE OF
The trader's email address or numeric platform user ID.

RuleEmail, or decimal digits. Send exactly one of idOrEmail or identifier.

Eg"trader@example.com"

customFields#string[]OPTIONAL
Custom field keys to return in data.customFields. Ask only for the fields you need.

RuleKeys configured in your community

Eg["customerid"]

identifier#objectONE OF
Structured lookup. Send instead of idOrEmail.

RuleSend exactly one of idOrEmail or identifier

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

key#stringREQUIRED
id for the platform user ID, or the key of a custom single-line text or numerical user field, usually your broker identifier such as customerid.

Ruleid, or a custom text or number field key

Eg"customerid"

value#stringREQUIRED
The identifier value to match.

Eg"<brokerCustomerId>"

curl --request POST \
  --url https://api.returning.ai/v1/users/info \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idOrEmail": "trader@example.com",
    "customFields": ["customerid"]
  }'

Response#

A 200 returns the trader in the data object. Branch on the HTTP status and code, never on message. Save data.userId for the next call.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code.

RuleUSER_DATA_RETRIEVED

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"User data retrieved successfully"

data#objectALWAYS
The trader.

Eg{ ... }

_id#stringALWAYS
Internal record ID.

Eg"<userObjectId>"

userId#stringALWAYS
Platform user ID. Store it as a string and never do arithmetic on it.

RuleDecimal digits

Eg"3247779"

username#stringALWAYS
The trader's username.

Eg"sample_trader"

xp#numberALWAYS
Current XP balance.

Eg0

coins#numberALWAYS
Current coin balance.

Eg0

roles#string[]ALWAYS
Roles the trader holds in this community.

Eg["@all"]

highestRole#stringALWAYS
The trader's highest role.

Eg"@all"

customFields#objectALWAYS
The requested custom fields, keyed by field key.

RuleOnly keys you requested

Eg{"customerid": "<brokerCustomerId>"}

{
  "status": "success",
  "code": "USER_DATA_RETRIEVED",
  "message": "User data retrieved successfully",
  "data": {
    "_id": "<userObjectId>",
    "userId": "3247779",
    "username": "sample_trader",
    "xp": 0,
    "coins": 0,
    "roles": ["@all"],
    "highestRole": "@all",
    "customFields": {
      "customerid": "<brokerCustomerId>"
    }
  }
}

Errors#

401 and 403 responses carry the code in meta.code. The 400 for sending neither or both lookups has no code; every other error carries it in code.

Fix the request07

400Fix the request
You sent neither or both of idOrEmail and identifier. There is no code; detail.identifier says which. Send exactly one.
400CUSTOM_FIELD_IDENTIFIER_NOT_FOUNDFix the request
No custom user field has this key. Built-in fields such as country aren't accepted. Correct the key, or look up by email or platform user ID.
400CUSTOM_FIELD_IDENTIFIER_UNSUPPORTED_TYPEFix the request
The identifier field isn't a single-line text or numerical field. Look up by email or platform user ID instead.
400CUSTOM_FIELD_IDENTIFIER_INVALID_VALUEFix the request
The value is empty, or isn't a number for a numerical field. Correct it and retry.
400INVALID_CUSTOM_FIELDSFix the request
A key in customFields is not valid. Check the keys against your community's user fields.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, malformed, invalid or expired. Send Authorization: Bearer <API_KEY> with a current key.
403API_KEY_PERMISSION_DENIEDFix the request
The key is valid but lacks getUserData. Add the permission in Settings > Integration > API Keys.

Fix the data02

404USER_NOT_FOUNDFix the data
No active trader in this community matches. Check the email or ID; do not retry against other communities.
409CUSTOM_FIELD_IDENTIFIER_DUPLICATEFix the data
More than one trader has that identifier value. Look up by email or platform user ID instead.

Retry with backoff02

500USER_DATA_RETRIEVAL_FAILEDRetry with backoff
Retry the same request with exponential backoff. Keep the identifier and time for support.
503CUSTOM_FIELD_IDENTIFIER_NOT_READYRetry with backoff
Custom identifier lookup is unavailable, for example for a field created in the last few minutes. Use email or platform user ID, or retry with backoff.
{
  "status": "error",
  "code": "CUSTOM_FIELD_IDENTIFIER_NOT_FOUND",
  "message": "Custom field identifier does not exist"
}

Next step#

Update User DataPOST/v1/users/updateChange a trader's profile, roles or identifier using the userId you just read.