# Search users

Search users using OpenSearch-powered full-text and field-specific search.

This endpoint provides fast, indexed search across user data with support for:
- Full-text search across multiple fields
- Field-specific filtering with various operators
- Sorting and pagination
- Saved search preferences

Note: Only active (non-deleted) users are searchable. Soft-deleted records are automatically excluded from all search results.

Response Formats:
- flat (default): Returns indexed fields only for faster performance
- full: Returns complete user objects with all relationships

Endpoint: POST /users/search
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `criteria` (object)
    Search criteria to filter users

  - `criteria.id` (object)
    Search criteria for UUID fields

  - `criteria.id.operator` (string, required)
    Search operator:
- EQUALS: Exact match
- NOT_EQUALS: Not equal to
- ONE_OF: Matches any UUID in array
- NOT_ONE_OF: Does not match any UUID in array
- EXISTS: Field has a value (not null)
- DOES_NOT_EXIST: Field is null
    Enum: "EQUALS", "NOT_EQUALS", "ONE_OF", "NOT_ONE_OF", "EXISTS", "DOES_NOT_EXIST"

  - `criteria.id.values` (array)
    Array of UUIDs for ONE_OF or NOT_ONE_OF operators
    Example: ["550e8400-e29b-41d4-a716-446655440000","550e8400-e29b-41d4-a716-446655440001"]

  - `criteria.name` (object)
    User name

  - `criteria.name.operator` (string, required)
    Search operator:
- EQUALS: Exact match
- NOT_EQUALS: Not equal to
- STARTS_WITH: Begins with prefix
- ENDS_WITH: Ends with suffix
- INCLUDES: Contains substring
- ONE_OF: Matches any value in array
- NOT_ONE_OF: Does not match any value in array
- EXISTS: Field has a value (not null)
- DOES_NOT_EXIST: Field is null
    Enum: "EQUALS", "NOT_EQUALS", "STARTS_WITH", "ENDS_WITH", "INCLUDES", "ONE_OF", "NOT_ONE_OF", "EXISTS", "DOES_NOT_EXIST"

  - `criteria.name.values` (array)
    Array of values for ONE_OF or NOT_ONE_OF operators
    Example: ["value1","value2"]

  - `criteria.email` (object)
    Email address

  - `criteria.emailVerified` (object)
    Whether email is verified

  - `criteria.emailVerified.operator` (string, required)
    Search operator:
- TRUE: Field is true
- FALSE: Field is false
    Enum: "TRUE", "FALSE"

  - `criteria.phone` (object)
    Phone number

  - `criteria.status` (object)
    Status (pending, active, inactive)

  - `criteria.status.operator` (string, required)
    Search operator:
- EQUALS: Exact match
- NOT_EQUALS: Not equal to
- ONE_OF: Matches any value in array
- NOT_ONE_OF: Does not match any value in array
- EXISTS: Field has a value (not null)
- DOES_NOT_EXIST: Field is null
    Enum: "EQUALS", "NOT_EQUALS", "ONE_OF", "NOT_ONE_OF", "EXISTS", "DOES_NOT_EXIST"

  - `criteria.roles` (object)
    User roles

  - `criteria.visibility` (object)
    Visibility level (ALL, LIMITED)

  - `criteria.teamIds` (object)
    Team IDs (internal field groupIds)

  - `criteria.teamNames` (object)
    Team names (internal field groupNames)

  - `criteria.customersCount` (object)
    Number of customers (internal field shippersCount)

  - `criteria.customersCount.operator` (string, required)
    Search operator:
- EQUALS: Exact match
- NOT_EQUALS: Not equal to
- GREATER_THAN: Greater than value
- LESS_THAN: Less than value
- BETWEEN: Between min and max (inclusive)
- NOT_BETWEEN: Not between min and max
- EXISTS: Field has a value (not null)
- DOES_NOT_EXIST: Field is null
    Enum: "EQUALS", "NOT_EQUALS", "GREATER_THAN", "LESS_THAN", "BETWEEN", "NOT_BETWEEN", "EXISTS", "DOES_NOT_EXIST"

  - `criteria.customersCount.value` (integer)
    Single value for EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN

  - `criteria.customersCount.min` (integer)
    Minimum value for BETWEEN or NOT_BETWEEN

  - `criteria.customersCount.max` (integer)
    Maximum value for BETWEEN or NOT_BETWEEN

  - `criteria.quotesCount` (object)
    Number of quotes

  - `criteria.quotesWon` (object)
    Number of quotes won

  - `criteria.quoteWinRate` (object)
    Quote win rate percentage

  - `criteria.ordersCount` (object)
    Number of shipments

  - `criteria.ordersTotalRevenue` (object)
    Total shipment revenue

  - `criteria.ordersTotalTransportationCost` (object)
    Total shipment transportation cost

  - `criteria.ordersTotalGrossProfit` (object)
    Total shipment gross profit

  - `criteria.averageGrossProfitPerOrder` (object)
    Average gross profit per shipment

  - `criteria.carriersCount` (object)
    Number of carriers

  - `criteria.createdAt` (object)
    Search criteria for datetime fields.
Supports both absolute datetime values and relative time expressions.

  - `criteria.createdAt.operator` (string, required)
    Search operator:
- EQUALS: Exact match
- NOT_EQUALS: Not equal to
- BEFORE: Before datetime
- AFTER: After datetime
- BETWEEN: Between min and max (inclusive)
- NOT_BETWEEN: Not between min and max
- EXISTS: Field has a value (not null)
- DOES_NOT_EXIST: Field is null
    Enum: "EQUALS", "NOT_EQUALS", "BEFORE", "AFTER", "BETWEEN", "NOT_BETWEEN", "EXISTS", "DOES_NOT_EXIST"

  - `criteria.createdAt.value` (string)
    Absolute datetime for EQUALS, NOT_EQUALS
    Example: "2025-01-15T10:00:00Z"

  - `criteria.createdAt.min` (string)
    Minimum datetime for BETWEEN or NOT_BETWEEN
    Example: "2025-01-01T00:00:00Z"

  - `criteria.createdAt.max` (string)
    Maximum datetime for BETWEEN or NOT_BETWEEN
    Example: "2025-12-31T23:59:59Z"

  - `criteria.createdAt.valueRelative` (integer)
    Relative time from now (negative for past, positive for future).
Example: -7 with WEEK unit means 7 weeks ago.

  - `criteria.createdAt.valueRelativeUnit` (string)
    Time unit for relative time calculations:
- YEAR: Years
- MONTH: Months
- WEEK: Weeks
- DAY: Days
- HOUR: Hours
- MINUTE: Minutes
- SECOND: Seconds
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `criteria.createdAt.minRelative` (integer)
    Relative time for min boundary

  - `criteria.createdAt.minRelativeUnit` (string)
    Time unit for relative time calculations:
- YEAR: Years
- MONTH: Months
- WEEK: Weeks
- DAY: Days
- HOUR: Hours
- MINUTE: Minutes
- SECOND: Seconds
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `criteria.createdAt.maxRelative` (integer)
    Relative time for max boundary

  - `criteria.createdAt.maxRelativeUnit` (string)
    Time unit for relative time calculations:
- YEAR: Years
- MONTH: Months
- WEEK: Weeks
- DAY: Days
- HOUR: Hours
- MINUTE: Minutes
- SECOND: Seconds
    Enum: "YEAR", "MONTH", "WEEK", "DAY", "HOUR", "MINUTE", "SECOND"

  - `criteria.lastInvitedAt` (object)
    When the user was last invited

  - `pagination` (object)
    Pagination options for search requests

  - `pagination.pageNumber` (integer)
    Page number (1-based)
    Example: 1

  - `pagination.pageSize` (integer)
    Number of results per page (max 250)
    Example: 50

  - `sort` (array)
    Sort options for the search results
    Example: [{"field":"createdAt","order":"desc"}]

  - `sort.field` (string, required)
    Field name to sort by (must be an indexed field)
    Example: "createdAt"

  - `sort.order` (string, required)
    Sort direction (ascending or descending)
    Enum: "asc", "desc"

  - `savedSearch` (object)
    Optional saved search to load preferences from.
When provided, the saved search criteria will be loaded and merged with any explicit criteria.

  - `savedSearch.id` (string)
    Saved search UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `savedSearch.key` (string)
    Client-defined key for the saved search
    Example: "my-carrier-search"

  - `format` (string)
    Response format:
- flat: Returns only indexed fields (default, faster)
- full: Returns complete user objects
    Enum: "flat", "full"

## Response 200 fields (application/json):

  - `data` (array, required)
    Search results - either flat rows or full user objects based on format parameter

  - `pagination` (object, required)
    Pagination information for search results

  - `pagination.pageNumber` (integer, required)
    Current page number
    Example: 1

  - `pagination.pageSize` (integer, required)
    Number of results returned on this page
    Example: 50

  - `pagination.totalPages` (integer, required)
    Total number of pages available
    Example: 25

  - `totalResults` (integer, required)
    Total number of matching results (excluding soft-deleted records)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message