Admin user search
curl --request GET \
--url https://api.example.com/api/v1/admin/usersimport requests
url = "https://api.example.com/api/v1/admin/users"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/admin/users', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/admin/users",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/admin/users"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/admin/users")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/admin/users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyUsers
Admin user search
Search + filter user accounts with free-text query, status filters, and opaque cursor pagination.
GET
/
api
/
v1
/
admin
/
users
Admin user search
curl --request GET \
--url https://api.example.com/api/v1/admin/usersimport requests
url = "https://api.example.com/api/v1/admin/users"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/admin/users', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/admin/users",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/admin/users"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/admin/users")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/admin/users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_bodyOverview
The user-management list view. Combines a free-text query, several status filters, and cursor pagination into a single read. Available to any admin role (SUPER, MODERATOR, FINANCE) — it is read-only.Authentication
Bearer <accessToken> required, where the token has scope: 'admin' (issued by /admin/auth/mfa-verify). The requireAdmin middleware rejects any user-scope token with 401 UNAUTHENTICATED.
Read-only — all three admin roles (SUPER, MODERATOR, FINANCE) may call this endpoint. No per-route role gate.
Path parameters
None.Query parameters
| Name | Type | Required | Notes | Example |
|---|---|---|---|---|
q | string | no | Free-text search across email, firstName, lastName. Matched via a case-insensitive anchored regex, and capped at 100 chars (longer values are rejected with VALIDATION_FAILED) to bound regex cost. | jane |
status | enum | no | ACTIVE, BANNED, or SUSPENDED. | BANNED |
tenancyStatus | enum | no | NOT_SUBMITTED, PENDING, APPROVED, REJECTED. | PENDING |
hasActiveSub | boolean | no | true/false. Filters by whether the user currently has an active subscription. | true |
cursor | string | no | Opaque base64url pagination cursor returned as nextCursor from a previous page. 1..512 chars. Do not construct or parse it. | eyJjcmVhdGVkQXQ… |
limit | integer | no | Page size, 1..100. Default 25. | 50 |
Request body
None.Response — 200 OK
| Field | Type | Notes |
|---|---|---|
items | array | Array of user summary objects (below). |
nextCursor | string | null | Opaque cursor for the next page, or null when this is the last page. |
User summary object
| Field | Type | Notes |
|---|---|---|
id | string | User ObjectId. |
email | string | |
firstName | string | null | |
lastName | string | null | |
status | enum | ACTIVE | BANNED | SUSPENDED. |
tenancyStatus | enum | NOT_SUBMITTED | PENDING | APPROVED | REJECTED. |
subscriptionStatus | string | Denormalised subscription status (e.g. ACTIVE, TRIALING, NONE). |
bannedAt | string | null | ISO timestamp of the ban, or null. |
bannedReason | string | null | Reason recorded at ban time, or null. |
createdAt | string | ISO timestamp. |
{
"items": [
{
"id": "66400a8f1c2b4d5e6f7a8b01",
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Doe",
"status": "ACTIVE",
"tenancyStatus": "APPROVED",
"subscriptionStatus": "ACTIVE",
"bannedAt": null,
"bannedReason": null,
"createdAt": "2026-04-12T09:00:00.000Z"
}
],
"nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTEyVDA5OjAwOjAwLjAwMFoifQ"
}
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | q over 100 chars, limit out of 1..100, or an enum filter has an unknown value. |
| 401 | UNAUTHENTICATED | Missing, malformed, expired, or non-admin-scope token. |
Example error — 401 UNAUTHENTICATED
{
"type": "https://api.swappr.co.uk/errors/unauthenticated",
"title": "Authentication required",
"status": 401,
"code": "UNAUTHENTICATED",
"detail": "Admin scope required",
"instance": "/api/v1/admin/users",
"requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}
See also
- Ban user — moderation action on a result row.
- Pagination — the opaque-cursor contract.
curl
curl "https://api.swappr.co.uk/api/v1/admin/users?q=jane&status=ACTIVE&limit=50" \
-H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"
Postman
Seedocs/postman/swappr.postman_collection.json → Admin Users → Search.