This endpoint searches and retrieves platform users based on specified filter criteria, returning only the requested fields for each matching user. It provides flexible filtering capabilities with pagination support for large result sets. Authorization# Found in the platform under community settings > API keys .Get User Data Available Fields# All user fields (including custom fields) can be requested in the response. Platform field Field name Email email First Name first_name Last Name last_name Join date join_date Total XP xp Total Coins coins
Field names in the request must match the database column names shown in the user fields table. Filter Options# All user fields (including custom fields) can be filtered.filter parameter supports three types of filtering operations: 1. Exact Match# Filter users by exact field value. 2. Comparison Operators# Use operators for numeric and date field comparisons:Supported operators: gte - Greater than or equal to
lte - Less than or equal to
3. Range Queries# Combine operators to filter within a range. Results are paginated with a fixed page size of 200 records per response. Use for sequential retrieval of all pages: 1.
Response includes next_cursor when more results exist.
2.
Send cursor parameter in subsequent requests to get the other pages.
Use to get to a specific page: 1.
Response includes total_pages and current_page.
2.
Send page with the number in subsequent requests to get the specific page.
Important : Do not send both cursor and page parameters in the same request. Choose one pagination method per request sequence.Request Provide your bearer token in the Authorization
header when making requests to protected resources. Example: Authorization: Bearer ********************
Body Params application/json
{
"fields" : [
"email" ,
"join_date" ,
"first_name" ,
"last_name"
] ,
"filter" : {
"join_date" : {
"lte" : "2025-08-28" ,
"gte" : "2025-01-01"
} ,
"first_name" : "Annie"
}
} Request Code Samples
curl --location --request POST 'https://integration.returning.ai/apis/v1/users/filter' \
--header 'Content-Type: application/json' \
--data-raw '{
"fields": [
"email",
"join_date",
"first_name",
"last_name"
],
"filter": {
"join_date": {
"lte": "2025-08-28",
"gte": "2025-01-01"
},
"first_name": "Annie"
}
}' Responses application/json Generate Code
{
"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 2025-08-12 10:33:55
