Skip to content

User Search (API v2)

DATAMIMIC exposes a typed user search endpoint intended for the user-management UI and other authenticated clients.

Endpoint

  • POST /api/v2/users/search — Search system users (user auth).

The endpoint uses a backend-owned table-search envelope in the request body:

1
2
3
4
5
{
  "filters": { },
  "pagination": { "page": 1, "per_page": 10 },
  "sorting": { "sort_by": "id", "sort_order": "desc" }
}

Example: free-text search (case-insensitive substring):

1
2
3
4
5
{
  "filters": { "q": "76b5aa94-" },
  "pagination": { "page": 1, "per_page": 10 },
  "sorting": { "sort_by": "id", "sort_order": "desc" }
}

Legacy note:

  • This POST .../search endpoint does not use page / per_page query parameters; clients must send pagination in the request body.

Pagination rules:

  • page is 1-based; page<=0 is clamped to 1
  • per_page<=0 uses the API default (10)
  • per_page is capped by server_settings.DB_ITEM_LIMIT (page-size cap only, no separate total-results cap)
  • page is clamped to total_pages

Substring filters:

  • All substring filters are case-insensitive (ILIKE %value%) when match_type="like".

Request Model

UserSearchRequest

Body shape:

  • filters — UserSearchFilters
  • pagination — PaginationRequest
  • sorting — UserSortConfig

UserSearchFilters:

Field Type Match semantics
q string \| null Free-text filter. Case-insensitive substring match across supported text fields and ID fields (id).
id integer \| null Exact match (==)
email string \| null match_type="like": substring match (ILIKE %value%, case-insensitive); match_type="exact": exact match (==)
active boolean \| null Exact match (==)
first_name string \| null match_type="like": substring match (ILIKE %value%, case-insensitive); match_type="exact": exact match (==)
last_name string \| null match_type="like": substring match (ILIKE %value%, case-insensitive); match_type="exact": exact match (==)
language string \| null match_type="like": substring match (ILIKE %value%, case-insensitive); match_type="exact": exact match (==)
match_type "like" \| "exact" Controls whether string filters use substring vs exact matching (default: like)

Unknown fields are rejected with 422 (request models forbid extras).

Sorting

UserSortConfig:

  • sort_by: one of id, tc_creation, tc_update, email
  • sort_order: asc or desc (default: desc)

Default behaviour: sort by id descending (deterministic, tie-broken by id).

Response Model

The endpoint returns UserSearchResponse:

  • data: UserSearchDataResponse[]
  • meta:
  • pagination: total_items, total_pages, current_page, per_page, next_page_num, prev_page_num
  • sorting: the applied sorting config
  • applied_filters: normalized filters actually applied by the server

UserSearchDataResponse includes: id, email, first_name, last_name, language, active, tc_creation, tc_update, auth_groups, preferences.

Known Limitations (No Fake Features)

  • No date-range filters (e.g. from/to, tc_creation_from, …)