# Search carriers

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

This endpoint searches both:
- ONBOARDED carriers: Carriers with profiles in your organization
- FMCSA carriers: Public carrier records from FMCSA database

Features:
- Full-text search across multiple fields
- Field-specific filtering with various operators
- Sorting and pagination
- Saved search preferences

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

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

## Request fields (application/json):

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

  - `criteria.id` (object)
    Carrier ID (carrierProfileId for onboarded, goldenCarrierId otherwise)

  - `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.carrierProfileId` (object)
    Profile ID for onboarded carriers only

  - `criteria.goldenCarrierId` (object)
    Golden carrier ID from FMCSA data

  - `criteria.friendlyId` (object)
    Account ID for onboarded carriers

  - `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)
    Carrier company 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.carrierStatus` (object)
    Status within the system (pending, active, inactive, doNotUse)

  - `criteria.type` (object)
    Carrier type (TL, LTL, LINEHAUL, CARTAGE, AIR, OCEAN, RAIL)

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

  - `criteria.market` (object)
    DAT market

  - `criteria.zone` (object)
    DAT zone

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

  - `criteria.fmcsaStatus` (object)
    FMCSA status (active, inactive)

  - `criteria.mcNumber` (object)
    Motor Carrier number

  - `criteria.dotNumber` (object)
    DOT number

  - `criteria.einNumber` (object)
    Employer Identification Number

  - `criteria.safetyRating` (object)
    FMCSA safety rating

  - `criteria.equipments` (object)
    Equipment types (VAN, REEFER, FLATBED, POWER_ONLY, SPECIALIZED, CONTAINER, TANKER)

  - `criteria.powerUnits` (object)
    Number of power units

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

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

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

  - `criteria.trucks` (object)
    Number of trucks

  - `criteria.monthsActiveAuthority` (object)
    Months of active authority

  - `criteria.highwayId` (object)
    Highway ID

  - `criteria.highwayRulesAssessment` (object)
    Highway rules assessment

  - `criteria.rmisId` (object)
    RMIS ID

  - `criteria.rmisOperatingStatus` (object)
    RMIS operating status

  - `criteria.rmisInvitationStatus` (object)
    RMIS invitation status (ERROR, INVITED, SUCCESS)

  - `criteria.mcpStatus` (object)
    MyCarrierPortal invite status

  - `criteria.mcpReviewStatus` (object)
    MyCarrierPortal review status (acceptable, moderate, unacceptable)

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

  - `criteria.factorBankNames` (object)
    Factoring company names

  - `criteria.paymentTermName` (object)
    Payment term

  - `criteria.quickPayFee` (object)
    Quick pay discount rate

  - `criteria.accountOwnerId` (object)
    Account owner user ID

  - `criteria.accountOwnerName` (object)
    Carrier owner name

  - `criteria.loadsCount` (object)
    Number of loads delivered

  - `criteria.totalMiles` (object)
    Total miles driven

  - `criteria.totalRevenue` (object)
    Total revenue generated

  - `criteria.totalCostOfGoodsSold` (object)
    Total COGS

  - `criteria.ratePerMile` (object)
    Average rate per mile

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

  - `criteria.createdAt` (object)
    Onboarding date

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

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

## Response 200 fields (application/json):

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