Get Users with Filters
POST
/v1/users/filter
What this endpoint does
POST /v1/users/info.INFO
POST /v1/users/filter with both fields and filter → paginate data.data → call POST /v1/users/info when you need the full profile.Quick start
fields and filter are required on the current public runtime. Omitting either returns 400. An empty filter object is valid and returns the community directory page.Authentication and permission
Authorization: Bearer <COMMUNITY_API_KEY>. The key must include Get User Data (getUserData). Keep it server-side.| Failure | Observed result | Recovery |
|---|---|---|
Missing Authorization | 401 AUTHENTICATION_REQUIRED A valid bearer token or API key is required for this endpoint. | Add the Bearer community key. |
| Invalid token | 401 API request rejected | Replace the key. |
Complete examples
fields plus filter.email returns data.pagination.total: 1 when that member exists in this community."filter": {} with fields returns the community directory. On 2026-08-19 Codex this was 59 rows in one page.200 with data.data: [] and total: 0. That is not a 404.{} returns detail.fields: Required and detail.filter: Required. Sending fields without filter returns only detail.filter: Required.Success and readback
200. Envelope is { status: "success", data: { pagination, data } }. There is no top-level message on the current runtime.data.data is an array of user objects containing only the requested fields. pagination includes total, currentPage, totalPages, hasNextPage, and hasPrevPage.POST /v1/users/info when you need the full profile for one row.CHECK
200 with total: 0 means no rows matched this community and filter. It does not prove the email is unknown globally. A later POST /v1/users/info may still find the same email.Errors and recovery
| Status | When | Recovery |
|---|---|---|
400 Get users by filter endpoint validation error. | Missing fields, missing filter, or invalid field names | Send both keys. filter may be {}. |
401 AUTHENTICATION_REQUIRED | Missing or invalid Bearer token | Add a valid community key. |
200 empty data.data | Valid query, no matches | Stop or widen filter. Do not treat this as 404. |
500 was not induced in the 2026-08-19 Codex run.Retry safety
TIP
500 with bounded backoff. Do not retry 400 or 401 without changing the body or credential. Repeating a successful filter does not duplicate members.Gotchas
fields as required. The public gateway also requires filter.POST /v1/users/manage status plus admin UI, not this list, as proof of deletion.GET /v1/communities/{communityId}/users?page=&limit= returns empty data on the current runtime. Prefer this filter endpoint for search, and the community list with no query string for the default first page.Next steps
Request
Body Params application/json
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://adss-integration.returning.ai/apis/v1/users/filter' \
--header 'Content-Type: application/json' \
--data '{
"fields": [
"email",
"join_date",
"first_name",
"last_name"
],
"filter": {
"join_date": {
"lte": "2025-08-28",
"gte": "2025-01-01"
},
"first_name": "Annie"
}
}'Response Response Example
200 - Success Example
{
"status": "success",
"data": {
"pagination": {
"total": 14,
"currentPage": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
},
"data": [
{
"email": "Test@gmail.com",
"join_date": "2025-03-03T03:24:54.828Z",
"first_name": "Test",
"last_name": "Lee"
},
...
{
"email": "coffeeplanetklee@outlook.com",
"join_date": "2025-02-13T04:44:56.067Z",
"first_name": "Klee",
"last_name": "Planet"
}
]
}
}Modified at 2026-08-18 17:20:28