# Search shipments

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

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

Note: Only active (non-deleted) shipments 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 shipment objects with all relationships

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

## Request fields (application/json):

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

  - `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)
    Search criteria for keyword fields (exact match, no partial matching)

  - `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.status` (object)
    Shipment status (PENDING, BOOKED, IN_TRANSIT, DELIVERED, CANCELED, etc.)

  - `criteria.orderStatus` (object)
    AR (accounts receivable) status

  - `criteria.loadStatuses` (object)
    AP (accounts payable) statuses for carriers/vendors

  - `criteria.mode` (object)
    Transportation mode (TL, LTL, AIR, OCEAN, RAIL)

  - `criteria.tonu` (object)
    Truck Order Not Used flag

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

  - `criteria.pickUp` (object)
    Origin city and state

  - `criteria.pickUp.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.pickUpCity` (object)
    Search criteria for text fields (supports wildcards and partial matching)

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

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

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

  - `criteria.dropOff` (object)
    Destination city and state

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

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

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

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

  - `criteria.pickUpStartDatetime` (object)
    Scheduled pickup datetime

  - `criteria.pickUpStartDatetime.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.pickUpStartDatetime.value` (string)
    Absolute datetime for EQUALS, NOT_EQUALS
    Example: "2025-01-15T10:00:00Z"

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

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

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

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

  - `criteria.pickUpStartDatetime.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.pickUpStartDatetime.maxRelative` (integer)
    Relative time for max boundary

  - `criteria.pickUpStartDatetime.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.dropOffStartDatetime` (object)
    Scheduled delivery datetime

  - `criteria.bookedAt` (object)
    When carrier was booked

  - `criteria.shipperId` (object)
    Customer ID

  - `criteria.shipperName` (object)
    Customer name

  - `criteria.carrierIds` (object)
    Carrier IDs

  - `criteria.carrierNames` (object)
    Carrier names

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

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

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

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

  - `criteria.groupId` (object)
    Team ID

  - `criteria.groupName` (object)
    Team name

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

  - `criteria.weight` (object)
    Search criteria for float/decimal fields

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

  - `criteria.weight.min` (number)
    Minimum value for BETWEEN or NOT_BETWEEN

  - `criteria.weight.max` (number)
    Maximum value for BETWEEN or NOT_BETWEEN

  - `criteria.totalMiles` (object)
    Search criteria for float/decimal fields

  - `criteria.revenue` (object)
    Search criteria for float/decimal fields

  - `criteria.cost` (object)
    Search criteria for float/decimal fields

  - `criteria.profit` (object)
    Gross profit

  - `criteria.profitMargin` (object)
    Search criteria for float/decimal fields

  - `criteria.referenceValues` (object)
    Reference values (PO, BOL, customer ref, etc.)

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

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

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

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

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

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

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

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

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

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

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

  - `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

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

## Response 200 fields (application/json):

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

## 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