---
title: "Search Carriers"
method: GET
path: "/v2/tms/carriers/search"
tags: ["v2", "tms", "carriers"]
---

# Search Carriers

`GET /v2/tms/carriers/search`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v2/tms/carriers/search`
- Auth: HTTP bearer

Search for carriers with various filters

Uses CarrierServiceClient from libs to call Vortex - clean and simple!
Note: Contacts and equipment are NOT included by default for performance.
Pass include_contacts=true to include contacts (needed for email availability checks).
Use GET /carriers/{id} to fetch full carrier details.

Query Parameters:
    - integration_connection_id: TMS integration connection ID (required)
    - external_reference_id: Search by external reference ID (for autocomplete/partial matching)
    - name: Filter by carrier name (partial match)
    - dot_number: Filter by DOT number (partial match)
    - phone_number: Filter by phone number (partial match)
    - include_contacts: Include carrier contacts in response (default: false)
    - limit: Maximum number of results (default: 20)
    - offset: Offset for pagination (default: 0)

Returns:
    List of Carrier models (basic info only unless include_contacts is true)

## Query parameters

- `integration_connection_id` string, required
- `external_reference_id` string, nullable
- `name` string, nullable
- `dot_number` string, nullable
- `phone_number` string, nullable
- `include_contacts` boolean
- `limit` integer
- `offset` integer

## Headers

- `mentium-workspace-id` string, nullable

## Response `200`

Successful Response

- NexusAppSchemasTmsCarriersCarrierSchema[]
  - `id` string, required: Carrier UUID
  - `organization_id` string, required: Organization UUID
  - `integration_connection_id` string, required: Integration connection UUID
  - `external_reference_id` string, required: External reference ID from TMS
  - `name` string, required: Carrier name
  - `email` string, nullable: Primary contact email
  - `phone_number` string, nullable: Primary phone number
  - `dot_number` string, nullable: DOT (Department of Transportation) number
  - `mc_number` string, nullable: MC (Motor Carrier) number
  - `billing_currency` string: Billing currency (USD, CAD, MXN)
  - `custom_max_deadhead_distance_miles_analytics` integer, nullable: Carrier-specific maximum deadhead distance (miles) for Analytics Carrier and Load Searches
  - `custom_max_deadhead_distance_miles_potential_empty_truck_nearby` integer, nullable: Carrier-specific maximum deadhead distance (miles) for Potential Empty Truck Nearby Carrier and Load Searches
  - `send_email_offers_enabled` boolean: When false, email load offers are not sent to this carrier
  - `email_offers_opted_out_at` string, date-time, nullable: When the carrier last opted out of email load offers
  - `email_offers_opt_out_reason` string, nullable: Reason provided when opting out of email load offers
  - `email_offers_opted_out_by` string, nullable: Who opted the carrier out: broker or carrier
  - `historical_rate_can_exceed_range` boolean, nullable: Honor a historical lane rate even when it falls outside the offer's min/max range (default true)
  - `addresses` AddressSchema[]: Carrier addresses (physical, billing, terminal, etc.)
    - `id` string, nullable: Address UUID
    - `name` string, nullable: Address name/label
    - `street` string, nullable: Street address (alias for address_line1)
    - `address_line1` string, nullable: Street address line 1
    - `address_line2` string, nullable: Street address line 2
    - `city` string, nullable: City
    - `state` string, nullable: State/province
    - `postal_code` string, nullable: Postal/ZIP code
    - `country` string, nullable: Country
    - `full_text` string, nullable: Full formatted address
  - `certifications` CertificationSchema[]: Carrier certifications (PHMSA, TANKER_ENDORSED_DRIVERS, etc.)
    - `certification_type` 'PHMSA' | 'TANKER_ENDORSED_DRIVERS' | 'SMART_WAY' | 'CARB_TRUCK_AND_BUS' | 'CARB_TRU' | 'CTPAT' | 'TWIC' | 'TSA' | 'CALIFORNIA' | 'TEXAS' | 'OKLAHOMA' | 'MENTIUM_UNKNOWN_VALUE', required
    - `certification_number` string, nullable: Certification number or ID
    - `effective_at` string, date-time, nullable: When certification becomes effective
    - `expiration_at` string, date-time, nullable: When certification expires
    - `filed_at` string, date-time, nullable: When certification was filed
    - `first_seen_at` string, date-time, nullable: First time we saw this certification
    - `last_seen_at` string, date-time, nullable: Last time we saw this certification
    - `is_verified` boolean: Is this certification verified by a trusted source?
    - `verification_source` string, nullable: Source that verified this certification (e.g., 'Highway')
    - `data_origin` 'TMS' | 'HIGHWAY' | 'GENLOGS' | 'MY_CARRIER_PACKETS' | 'FMCSA' | 'DAT' | 'MENTIUM'
  - `contacts` CarrierContactSchema[]: Carrier contacts (dispatchers, admins, etc.)
    - `id` string, required: Contact UUID
    - `carrier_id` string, required: Parent carrier UUID
    - `external_reference_id` string, nullable: External reference ID from TMS
    - `first_name` string, nullable: First name (Sunnybrook)
    - `last_name` string, nullable: Last name (Sunnybrook)
    - `full_name` string, nullable: Full name (3G TMS)
    - `contact_type` string, nullable: Contact type (MentiumTmsContactType value, e.g. DISPATCHER)
    - `job_title` string, nullable: Job title or position
    - `is_primary_contact` boolean: Is this the primary contact?
    - `is_default` boolean: Is this the default contact?
    - `primary_phone` string, nullable: Primary phone number
    - `primary_phone_extension` string, nullable: Phone extension
    - `secondary_phone` string, nullable: Secondary phone number
    - `fax` string, nullable: Fax number
    - `primary_email` string, nullable: Primary email address
    - `secondary_email` string, nullable: Secondary email address
    - `phone_numbers` string[]: Phone numbers (ordered by priority)
    - `fax_numbers` string[]: Fax numbers
    - `email_addresses` string[]: Email addresses (ordered by priority)
    - `is_bill_to_contact` boolean: Bill-to contact?
    - `is_remit_to_contact` boolean: Remit-to contact?
    - `is_active` boolean: Is contact active?
    - `email_suppressed` boolean: Primary email previously hard-bounced and is flagged undeliverable
    - `email_suppressed_reason` string, nullable: Provider failure reason from the bounce that flagged the email
    - `email_suppressed_at` string, date-time, nullable: When the email was last flagged undeliverable
    - `deactivated` boolean: Contact is deactivated (bounce or manual)
    - `deactivation_source` string, nullable: Why deactivated: "bounce" (email hard-bounced) or "manual"
    - `deactivation_reason` string, nullable: Reason for deactivation
    - `deactivated_at` string, date-time, nullable: When the contact was deactivated
    - `deactivation_email` string, nullable: The exact blocked address (primary or secondary); pass to reactivate to release it
    - `birthday` string, date, nullable: Birthday (for CRM)
    - `notes` string, nullable: Contact notes
    - `created_at` string, date-time, required: Record created timestamp
    - `updated_at` string, date-time, required: Record updated timestamp
    - `data_origin` 'TMS' | 'HIGHWAY' | 'GENLOGS' | 'MY_CARRIER_PACKETS' | 'FMCSA' | 'DAT' | 'MENTIUM'
  - `equipment` CarrierEquipmentSchema[]: Carrier equipment and capabilities
    - `id` string, required: Equipment UUID
    - `carrier_id` string, required: Parent carrier UUID
    - `external_reference_id` string, nullable: External reference ID from TMS
    - `equipment_type` string, nullable: Equipment type (Tractor, Trailer, Reefer, Capabilities)
    - `equipment_number` string, nullable: Unit number or identifier
    - `equipment_name` string, nullable: Equipment name or description
    - `length` number, nullable: Length in feet
    - `width` number, nullable: Width in feet
    - `height` number, nullable: Height in feet
    - `is_owned` boolean: Is equipment owned by carrier?
    - `is_active` boolean: Is equipment active?
    - `is_available` boolean: Is equipment available?
    - `is_reefer` boolean: Refrigerated capability
    - `is_hazmat_certified` boolean: HazMat certified
    - `is_team_equipped` boolean: Team driver equipped
    - `is_oversize_capable` boolean: Can handle oversize loads
    - `is_overweight_capable` boolean: Can handle overweight loads
    - `has_liftgate` boolean: Has liftgate
    - `has_pallet_jack` boolean: Has pallet jack
    - `has_blanket_wrap` boolean: Has blanket wrap
    - `temp_min` integer, nullable: Minimum temperature capability
    - `temp_max` integer, nullable: Maximum temperature capability
    - `created_at` string, date-time, required: Record created timestamp
    - `updated_at` string, date-time, required: Record updated timestamp
  - `financial_summary` CarrierFinancialSummarySchema: Carrier financial summary - payment totals and statistics
    - `total_paid` number: Total amount paid to carrier for delivered loads
    - `total_loads` integer: Total number of loads for this carrier
    - `delivered_loads` integer: Number of delivered loads
    - `outstanding_balance` number: Outstanding balance for non-delivered loads
    - `average_load_rate` number: Average carrier rate per load
  - `recent_payments` CarrierPaymentSchema[]: Recent payments (based on delivered loads)
    - `date` string, nullable: Delivery date (payment date)
    - `amount` number: Carrier amount for this load
    - `load_ref` string, nullable: Load external reference ID
  - `payment_terms` CarrierPaymentTermsSchema: Carrier payment terms from TMS
    - `payment_term` string, nullable: Payment terms (e.g., 'Net 30', 'Net 25')
    - `payment_method` string, nullable: Payment method (e.g., 'ACH', 'Check')
  - `factor_info` CarrierFactorInfoSchema: Factoring company info from TMS
    - `factor_name` string, nullable: Factoring company name
    - `factor_address1` string, nullable: Factor address line 1
    - `factor_address2` string, nullable: Factor address line 2
    - `factor_city` string, nullable: Factor city
    - `factor_state` string, nullable: Factor state
    - `factor_zip` string, nullable: Factor ZIP code
    - `factor_country` string, nullable: Factor country
  - `engagement_metrics` CarrierEngagementMetricsSchema: Carrier engagement metrics for tracking carrier performance
    - `response_rate` number: Percentage of times carrier responded to offers (0-100)
    - `acceptance_rate` number: Percentage of times carrier accepted offers (0-100)
    - `total_offers_sent` integer: Total number of offers sent to this carrier
    - `total_responses` integer: Total number of responses from carrier
    - `total_accepted` integer: Total number of offers accepted by carrier
  - `created_at` string, date-time, required: Record created timestamp
  - `updated_at` string, date-time, required: Record updated timestamp

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)