Returning.AIDevelopers
v1

API reference / Users

.md

Get Users with Filters

Search the traders in your community by profile, join date, balance, role or custom field, and get back only the fields you ask for, 200 at a time.

Last updated 26 Sep 2026API v1

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

When to use this

  • Check whether a trader with a broker customer ID already exists before you call Create User.
  • Sync or reconcile your trader list, for example everyone who joined this month.
  • Build a segment, such as traders with a role or with more than a set number of coins.

Authentication#

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

Every search needs getUserData and only ever returns traders in the API key's community. Keep the key on your server.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with getUserData.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send both fields and filter. filter: {} returns every trader in your community.

Supported filter keys, all of which must match:

  • email, first_name, last_name, username, country, phone: exact value, not case-sensitive.
  • Any custom field key, such as customerid: exact value, or an operator object on number and date fields. You can also group custom fields under customFields, for exact values only.
  • join_date, xp, coins: an operator object with gt, gte, lt, lte or eq, for example {"xp": {"gte": 1000}}.
  • roles, tags, badges: {"inc": [...]} for traders who have every listed name, {"exc": [...]} for traders who have none of them. Names are not case-sensitive.
  • language: {"eq": "en"}.

There is no page parameter. To walk the results, send each response's nextCursor back as cursor.

fields#string[]REQUIRED
The fields to return for each trader. Profile: id, _id, email, username, first_name, last_name, country, phone, join_date. Activity: xp, coins, language, roles, tags, badges. You can also name any custom field key.

RuleAt least one

Eg["id", "email", "username", "join_date", "customerid"]

filter#objectREQUIRED
Conditions every returned trader must meet. Send {} to list everyone.

RuleObject; {} allowed

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

customerid#string | number | objectOPTIONAL
Any custom field key, such as your broker customer ID. Matches the exact value, or use gt, gte, lt, lte or eq on number and date fields.

Eg"<brokerCustomerId>"

email#stringOPTIONAL
Exact email, not case-sensitive.

Eg"trader@example.com"

first_name#stringOPTIONAL
Exact first name, not case-sensitive. last_name, username, country and phone work the same way.

Eg"Sample"

join_date#objectOPTIONAL
When the trader joined your community. Use gt, gte, lt, lte or eq; combine two for a range.

Eg{"gte": "2026-09-01", "lte": "2026-09-30"}

gte#stringOPTIONAL
On or after this date. A date-only value (YYYY-MM-DD) compares whole days.

Eg"2026-09-01"

lte#stringOPTIONAL
On or before this date. A date-only value includes that whole day.

Eg"2026-09-30"

cursor#stringOPTIONAL
The nextCursor from the previous page. Omit it for the first page.

RuleSend exactly as received

curl --request POST \
  --url https://api.returning.ai/v1/users/filter \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": [
      "id",
      "email",
      "username",
      "join_date",
      "customerid"
    ],
    "filter": {
      "customerid": "<brokerCustomerId>"
    }
  }'

Response#

A 200 returns up to 200 traders in data.data. No match is still a 200, with an empty list and total: 0. Branch on the HTTP status, never on message.

status#stringALWAYS
Result of the request.

Rulesuccess

data#objectALWAYS
The page of results.

Eg{ ... }

data#object[]ALWAYS
The matching traders, each with only the fields you asked for, in a fixed order.

Eg[ ... ]

id#stringWHEN REQUESTED
Platform user ID. Store it as a string and never do arithmetic on it.
email#stringWHEN REQUESTED
The trader's email.

Eg"trader@example.com"

username#stringWHEN REQUESTED
The trader's username.
first_name#stringWHEN REQUESTED
The trader's first name.
last_name#stringWHEN REQUESTED
The trader's last name.
join_date#stringWHEN REQUESTED
When the trader joined your community, or null if unknown.

Eg"2026-09-26T08:30:00.000Z"

customerid#stringWHEN REQUESTED
A requested custom field, keyed by its field key. Holds the field's default value, or null, when the trader has no value.
pagination#objectALWAYS
Where this page sits in the full result.

Eg{ ... }

total#integerALWAYS
Number of matching traders across all pages.

Eg1

currentPage#integerALWAYS
This page's number, starting at 1.

Eg1

totalPages#integerALWAYS
Number of pages.

Rule200 traders per page

Eg1

hasNextPage#booleanALWAYS
true when another page follows. Send nextCursor to get it.

Egfalse

hasPrevPage#booleanALWAYS
true on every page after the first.

Egfalse

nextCursor#stringWHEN hasNextPage
Send this as cursor to get the next page.
{
  "status": "success",
  "data": {
    "pagination": {
      "total": 1,
      "currentPage": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    },
    "data": [
      {
        "id": "3247779",
        "email": "trader@example.com",
        "username": "sample_trader",
        "join_date": "2026-09-26T08:30:00.000Z",
        "customerid": "<brokerCustomerId>"
      }
    ]
  }
}

Errors#

Errors from the API key check, such as 401 and 403, carry the code in meta.code. A 400 has no code; its detail names each invalid field. A 500 has no code.

Fix the request03

400Fix the request
fields or filter is missing, fields is empty, or a filter uses an unsupported operator. detail names the field. Send both keys; filter may be {}.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, 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 data01

404COMMUNITY_NOT_FOUNDFix the data
The key's community no longer exists. Use a key from an active community.

Retry with backoff02

500Retry with backoff
An unexpected error, or a cursor that was not returned to you. Send nextCursor exactly as received, then retry with backoff.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry the same request with backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Get users by filter endpoint validation error.",
  "detail": {
    "fields": "Fields are required"
  },
  "solution": "Check your body in request and try again"
}

Next step#

Get User DataPOST/v1/users/infoRead one trader's full profile, roles, coins and XP using the id from a row.