searchcarriers-api

name	searchcarriers-api
description	Complete integration guide for the SearchCarriers API — access U.S. DOT carrier data, safety records, inspections, insurance, risk factors, and vetting reports. Covers all 26 endpoints (V1: 18, V2: 8), authentication, rate limiting, error handling, pagination, and best practices.
argument-hint	[dot-number or carrier-name]

SearchCarriers API

Overview

SearchCarriers provides programmatic access to U.S. Department of Transportation (DOT) motor carrier data sourced from the FMCSA database. Use it to search, profile, and vet trucking companies, freight brokers, and other regulated carriers.

Key capabilities:

• Search carriers by name, DOT number, MC/MX/FF number, SCAC, VIN, or location
• Retrieve company profiles: authorities, equipment, fleet size, operation types
• Access inspection history and safety ratings
• View active insurance policies and out-of-service orders
• Generate comprehensive vetting reports with risk factor scoring
• Monitor companies via watch lists with email alerting
• Export carrier data in bulk

API versions: V1 (18 endpoints) + V2 (8 endpoints) = 26 total

---

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Environment setup

Store your token in an environment variable — never hardcode it or commit it to source control.

export SEARCHCARRIERS_API_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."

Example cURL

curl -X GET "https://searchcarriers.com/api/v2/company/1911857/vetting-report" \
  -H "Authorization: Bearer $SEARCHCARRIERS_API_TOKEN" \
  -H "Accept: application/json"

Authentication errors

Situation	Response
Missing header	401 {"message": "Unauthorized"}
Invalid / expired token	401 {"message": "Unauthorized"}
Valid token, no permission	403 {"message": "Forbidden"}

Common fixes:

• Confirm format is Bearer <space> YOUR_TOKEN
• Rotate the token in your account settings if expired
• Use separate tokens per environment (dev / staging / prod)

---

Base URLs

V1: https://searchcarriers.com/api/v1
V2: https://searchcarriers.com/api/v2

Use V2 when available — it has enhanced endpoints. Fall back to V1 for search, inspections, watch lists, and export.

---

Rate Limiting

Limit	Value
Requests per minute	180

Rate limit headers (on every response)

X-RateLimit-Limit: 180
X-RateLimit-Remaining: 142
X-RateLimit-Reset: 1640001234

• X-RateLimit-Remaining — requests left in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets

429 response body

{ "message": "Too many attempts. Please try again later." }

Retry strategy (exponential backoff)

attempt 1 → wait 1s
attempt 2 → wait 2s
attempt 3 → wait 4s
attempt 4 → wait 8s

Check the Retry-After header first; fall back to 2^attempt seconds if absent.

Staying under the limit

1. Cache responses — carrier data rarely changes minute-to-minute; 5–10 min TTL is safe
2. Use bulk/paginated calls — fetch 100 records per page instead of 100 individual calls
3. Queue high-volume jobs — smooth traffic to ≤ 3 req/s (180/min)
4. Watch X-RateLimit-Remaining — log a warning when it drops below 20

---

Error Handling

HTTP status codes

Code	Meaning
200	Success
400	Bad Request — malformed syntax or invalid parameters
401	Unauthorized — missing or invalid token
403	Forbidden — valid token, insufficient permissions
404	Not Found — resource doesn't exist
422	Unprocessable Entity — validation errors
429	Too Many Requests — rate limit exceeded
500	Server Error — retry with backoff

Error response format

{
  "message": "The given data was invalid.",
  "errors": {
    "dotNumber": ["The dot number field is required."],
    "perPage": ["The per page may not be greater than 100."]
  }
}

• message — human-readable summary
• errors — field-level validation details (present on 422)

Retry-safe status codes

Retry on 429 and 5xx. Do not retry on 4xx (fix the request first).

---

V1 API Reference

Base: https://searchcarriers.com/api/v1

Search (3 endpoints)

GET /api/v1/search — Super Search

The primary search endpoint. Accepts free-text plus many optional filters.

Query parameters:

Parameter	Type	Description
superSearchTerm	string	Free-text: company name, website, DOT#, etc.
docketNumber	integer	MC / MX / FF docket number
dotNumber	integer	DOT number
companyTypes[]	array	Filter by type: Broker, Carrier, etc.
radiusZipcode	string	Center ZIP for radius search
radiusMiles	integer	Radius in miles
addressState	string	Two-letter state code (e.g. CA)
addressCity	string	City name
minPowerUnits	integer	Minimum fleet size
maxPowerUnits	integer	Maximum fleet size
minTrailers	integer	Minimum trailer count
maxTrailers	integer	Maximum trailer count
safetyScorePresent	boolean	Only return companies with a safety score
minAuthorityAge	integer	Oldest authority age, months (min)
maxAuthorityAge	integer	Oldest authority age, months (max)
includeAuthorities[]	array	Authority types to include
excludeAuthorities[]	array	Authority types to exclude
includeOperationTypes[]	array	Operation classifications to include
excludeOperationTypes[]	array	Operation classifications to exclude
page	integer	Page number (default: 1)
perPage	integer	Results per page (default: 10, max: 100)
useSuperWideSearch	boolean	Deprecated
useLegacySearch	boolean	Deprecated

Array parameter format:

?companyTypes[]=Broker&companyTypes[]=Carrier

Response (200):

{
  "data": [
    {
      "id": "mixed",
      "dot_number": "string",
      "docket_numbers": "mixed",
      "legal_name": "string",
      "dba_name": "string",
      "status_code": "string",
      "mcs150_date": "datetime",
      "add_date": "datetime",
      "carrier_operation": "mixed",
      "business_org_desc": "string",
      "phone": "mixed",
      "fax": "mixed",
      "cell_phone": "mixed",
      "truck_units": "mixed",
      "power_units": "mixed",
      "phy_street": "string",
      "phy_city": "string",
      "phy_state": "string",
      "phy_zip": "string",
      "carrier_mailing_street": "string",
      "carrier_mailing_city": "string",
      "carrier_mailing_state": "string",
      "carrier_mailing_zip": "string",
      "email_address": "mixed",
      "safety_rating": "mixed",
      "safety_rating_date": "datetime",
      "scac": "mixed",
      "match_hint": "mixed"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string | null",
    "next": "string | null"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "path": "string",
    "per_page": 10,
    "to": 10,
    "total": 100
  }
}

Errors: 401, 422

---

GET /api/v1/search/scac — Search by SCAC

Search for a carrier by Standard Carrier Alpha Code.

Query parameters:

Parameter	Type	Required	Description
scac	string	✓	Standard Carrier Alpha Code
page	integer		Default: 1
perPage	integer		Default: 10

---

GET /api/v1/search/by-vin/{vin} — Get Companies by VIN

Find companies associated with a specific vehicle.

Path parameters:

Parameter	Type	Required	Description
vin	string	✓	Vehicle Identification Number

---

Inspection (2 endpoints)

GET /api/v1/inspections — Search Inspections

Search vehicle inspection records.

Query parameters:

Parameter	Type	Description
dotNumber	integer	Filter by DOT number
inspectionDate	date	Filter by inspection date (YYYY-MM-DD)
page	integer	Default: 1
perPage	integer	Default: 10

---

GET /api/v1/inspection/details — Inspection Details

Get full details for a specific inspection.

Query parameters:

Parameter	Type	Required	Description
inspectionId	string	✓	Unique inspection identifier

---

Company Details (7 endpoints)

All endpoints in this group take {dotNumber} as a path parameter (integer, required).

GET /api/v1/company/{dotNumber}/insurances

Active and historical insurance policies for the company.

GET /api/v1/company/{dotNumber}/inspections

Inspection history. Supports page / perPage pagination.

GET /api/v1/company/{dotNumber}/out-of-service-orders

Out-of-service orders issued to the company.

GET /api/v1/company/{dotNumber}/safety-summary

Safety rating summary including scores and rating date.

GET /api/v1/company/{dotNumber}/authorities

All authority records (MC/MX/FF) associated with the company.

GET /api/v1/company/{dotNumber}/equipment

Equipment on file (truck types, trailer types).

GET /api/v1/company/{dotNumber}/vehicles ⚠️ DEPRECATED

Vehicle records. Use equipment endpoint instead.

---

Authority (1 endpoint)

GET /api/v1/authority/{docketNumber}/history

Full history for a docket number (MC/MX/FF).

Path parameters:

Parameter	Type	Required	Description
docketNumber	string	✓	Docket number, e.g. MC596655

---

Equipment (1 endpoint)

GET /api/v1/equipment/details

Get detailed information about a specific piece of equipment.

Query parameters:

Parameter	Type	Required	Description
equipmentId	string	✓	Unique equipment identifier

---

Export (1 endpoint)

GET /api/v1/export

Export carrier data in bulk.

Query parameters:

Parameter	Type	Description
format	string	Output format: csv, json
filters	object	Same filter params as /v1/search

---

Company Watches (3 endpoints)

Watch lists let you monitor carriers for changes and receive email alerts.

POST /api/v1/company/{dotNumber}/watch — Add/Update Watch

Path parameters: dotNumber (integer, required)

Request body (JSON):

{
  "notes": "string",
  "alertEmail": true
}

---

GET /api/v1/company/{dotNumber}/watch — Get Watch for Company

Returns watch details for a single company. dotNumber in path (required).

---

GET /api/v1/company/watch — Get All Watches

Returns all companies on your watch list.

Query parameters:

Parameter	Type	Description
page	integer	Default: 1
perPage	integer	Default: 10

---

V2 API Reference

Base: https://searchcarriers.com/api/v2

Company Details (6 endpoints)

All require {dotNumber} as path parameter (integer, required).

GET /api/v2/company/{dotNumber}/insurances

Enhanced insurance details (V2 version with richer data than V1).

---

GET /api/v2/company/{dotNumber}/service-areas

Geographic service areas the company operates in.

---

GET /api/v2/company/{dotNumber}/physical-geo-location

Lat/lng and address for the company's physical location.

Response:

{
  "latitude": 34.052235,
  "longitude": -118.243683,
  "address": "123 Main St",
  "city": "Los Angeles",
  "state": "CA",
  "zip": "90001"
}

---

GET /api/v2/company/{dotNumber}/logo

Returns the company logo (image file or URL).

---

GET /api/v2/company/{dotNumber}/truck-trailer-driver-count

Current fleet and driver counts.

Response:

{
  "trucks": 42,
  "trailers": 35,
  "drivers": 50,
  "powerUnits": 42,
  "lastUpdated": "2026-01-15T00:00:00Z"
}

---

GET /api/v2/company/{dotNumber}/common-authority-status

Current common authority status.

Response:

{
  "status": "ACTIVE",
  "authorityType": "Common",
  "statusDate": "2020-03-01T00:00:00Z",
  "active": true
}

---

Risk Factors (1 endpoint)

GET /api/v2/company/{dotNumber}/risk-factors

Risk factor analysis for the company.

Response:

{
  "overallRiskScore": 72.5,
  "riskFactors": [
    {
      "factor": "Inspection Violations",
      "severity": "medium",
      "description": "3 violations in past 12 months",
      "impact": "score reduced by 5 points"
    }
  ],
  "lastAssessed": "2026-02-01T00:00:00Z"
}

---

Vetting Engine (1 endpoint)

GET /api/v2/company/{dotNumber}/vetting-report

Comprehensive vetting report — the most complete single-call profile of a carrier.

Query parameters:

Parameter	Type	Default	Description
includeInsurance	boolean	true	Include insurance section
includeInspections	boolean	true	Include inspection history
includeRiskFactors	boolean	true	Include risk factor analysis
includeSafetyRating	boolean	true	Include safety rating

Response:

{
  "dotNumber": 1911857,
  "companyName": "ACME Trucking LLC",
  "vettingScore": 84.0,
  "recommendation": "APPROVED",
  "generatedAt": "2026-02-16T00:00:00Z",
  "insurance": { "...": "..." },
  "inspections": ["..."],
  "riskFactors": { "...": "..." },
  "safetyRating": { "...": "..." }
}

Recommendation values: APPROVED, CONDITIONAL, REJECTED

---

Common Patterns

Pagination

All list endpoints support page + perPage (max 100).

GET /api/v1/search?superSearchTerm=trucking&page=2&perPage=50

Iterate using meta.last_page or follow links.next until null.

page = 1
while True:
    resp = get("/api/v1/search", params={"superSearchTerm": "trucking", "page": page, "perPage": 100})
    data = resp.json()
    process(data["data"])
    if data["links"]["next"] is None:
        break
    page += 1

Array parameters

Repeat the key with bracket notation:

?companyTypes[]=Broker&companyTypes[]=Carrier

In code, most HTTP libraries handle this automatically when you pass an array value.

Lookup by DOT number (recommended flow)

1. GET /api/v1/search?dotNumber=1911857 — confirm the company
2. GET /api/v2/company/1911857/common-authority-status — check authority
3. GET /api/v2/company/1911857/vetting-report — full vetting in one call

Watch a carrier

POST /api/v1/company/1911857/watch
Content-Type: application/json
Authorization: Bearer TOKEN

{"notes": "Preferred vendor", "alertEmail": true}

---

Best Practices

1. Use HTTPS only — HTTP requests are rejected
2. Handle all status codes — 401, 403, 404, 422, 429, 500 each need distinct logic
3. Cache aggressively — carrier data changes slowly; 5–10 min TTL is fine for most fields
4. Prefer V2 endpoints — richer data, better maintained
5. Use vetting-report for full profiles — one call instead of six
6. Validate inputs first — check DOT/MC format client-side to avoid 422s
7. Log rate limit headers — warn at X-RateLimit-Remaining < 20
8. Exponential backoff — for 429 and 5xx responses
9. Use environment variables — never hardcode tokens
10. Separate tokens per env — dev, staging, prod each get their own token
11. Set request timeouts — 30s is a reasonable default; don't hang indefinitely
12. Paginate large exports — use perPage=100 and iterate; avoid unbounded loops

---

Quick Carrier Vetting Checklist

When evaluating a carrier, check these in order:

• GET /api/v2/company/{dot}/common-authority-status → active: true
• GET /api/v1/company/{dot}/insurances → valid cargo + liability, not expired
• GET /api/v1/company/{dot}/out-of-service-orders → none active
• GET /api/v1/company/{dot}/safety-summary → acceptable rating
• GET /api/v2/company/{dot}/risk-factors → overallRiskScore ≥ threshold
• GET /api/v2/company/{dot}/vetting-report → recommendation: APPROVED

---

Additional Resources

• Quick reference (all endpoints at a glance): See quick-reference.md
• Code examples (Python, JavaScript, Go, Ruby, PHP): See the examples/ directory — each file is a complete, working client for that language with full error handling, rate limit management, and pagination