# Search vendors

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

This endpoint provides fast, indexed search across vendor 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) vendors 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 vendor objects with all relationships

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

## Request fields (application/json):

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

  - `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.friendlyId` (object)
    Vendor ID

  - `criteria.friendlyId.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.friendlyId.values` (array)
    Array of values for ONE_OF or NOT_ONE_OF operators
    Example: ["ACTIVE","PENDING"]

  - `criteria.name` (object)
    Vendor 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.status` (object)
    Status (active, inactive, do_not_use)

  - `criteria.service` (object)
    Services provided by the vendor

  - `criteria.taxId` (object)
    EIN or other tax ID

  - `criteria.location` (object)
    Computed field "city, state"

  - `criteria.city` (object)
    Search criteria for text fields (supports wildcards and partial matching)

  - `criteria.state` (object)
    Search criteria for keyword fields (exact match, no partial matching)

  - `criteria.zip` (object)
    Postal code

  - `criteria.country` (object)
    Search criteria for keyword fields (exact match, no partial matching)

  - `criteria.primaryContactName` (object)
    Search criteria for text fields (supports wildcards and partial matching)

  - `criteria.primaryContactEmail` (object)
    Search criteria for text fields (supports wildcards and partial matching)

  - `criteria.primaryContactPhone` (object)
    Search criteria for text fields (supports wildcards and partial matching)

  - `criteria.paymentTermName` (object)
    Search criteria for keyword fields (exact match, no partial matching)

  - `criteria.quickbooksVendorId` (object)
    QuickBooks Online vendor ID (internal field qboVendorId)

  - `criteria.numberOfTimesUsed` (object)
    Number of times vendor was used

  - `criteria.numberOfTimesUsed.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.numberOfTimesUsed.value` (integer)
    Single value for EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN

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

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

  - `criteria.lastUsed` (object)
    Last date vendor was used

  - `criteria.lastUsed.operator` (string, required)
    Search operator (same as DatetimeSearchCriteria)
    Enum: "EQUALS", "NOT_EQUALS", "BEFORE", "AFTER", "BETWEEN", "NOT_BETWEEN", "EXISTS", "DOES_NOT_EXIST"

  - `criteria.lastUsed.value` (string)
    Absolute date for EQUALS, NOT_EQUALS
    Example: "2025-01-15"

  - `criteria.lastUsed.min` (string)
    Minimum date for BETWEEN or NOT_BETWEEN
    Example: "2025-01-01"

  - `criteria.lastUsed.max` (string)
    Maximum date for BETWEEN or NOT_BETWEEN
    Example: "2025-12-31"

  - `criteria.lastUsed.valueRelative` (integer)
    Relative time from now

  - `criteria.lastUsed.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.lastUsed.minRelative` (integer)

  - `criteria.lastUsed.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.lastUsed.maxRelative` (integer)

  - `criteria.lastUsed.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.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.minRelative` (integer)
    Relative time for min boundary

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

  - `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 vendor objects
    Enum: "flat", "full"

## Response 200 fields (application/json):

  - `data` (array, required)
    Search results - either flat rows or full vendor 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