searchcarriers-api

name	searchcarriers-api
description	Integrate with the SearchCarriers API for U.S. DOT carrier data, safety records, inspections, insurance, and vetting reports across 26 endpoints (V1 + V2). Use when building freight/logistics tools, carrier vetting workflows, or DOT compliance checks. Trigger with "search carriers", "DOT lookup", "carrier vetting", "FMCSA data", or "freight broker check".
allowed-tools	Read, WebFetch, Bash(curl:*)
version	1.0.0
author	Adam Battenfield
license	MIT
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

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

Prerequisites

• SearchCarriers API token (Bearer auth)
• Token stored in SEARCHCARRIERS_API_TOKEN env var

Instructions

1. Read the endpoint reference for the user's task:

   • V1 endpoints: {baseDir}/references/v1-endpoints.md
   • V2 endpoints: {baseDir}/references/v2-endpoints.md
   • Auth/rate limits: {baseDir}/references/authentication-and-rate-limits.md

2. Prefer V2 endpoints when available (richer data)

3. Use GET /api/v2/company/{dot}/vetting-report for full carrier profiles

4. Include Bearer token auth and handle rate limiting (180 req/min)

5. Paginate with page + perPage (max 100 per page)

Base URLs

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

Output

• Return structured JSON responses with relevant carrier data
• Include the API endpoint used and any pagination metadata
• Flag risk factors or safety concerns when present

Error Handling

Code	Meaning	Action
401/403	Auth failure	Check Bearer token format and permissions
422	Validation error	Validate DOT/MC number format before sending
429	Rate limit	Exponential backoff (1s, 2s, 4s, 8s), check Retry-After header
5xx	Server error	Retry with backoff, max 3 attempts

Best Practices

1. Use HTTPS only
2. Cache aggressively (5-10 min TTL)
3. Prefer V2 endpoints (richer data)
4. Use vetting-report for full profiles (one call instead of six)
5. Validate inputs client-side to avoid 422s
6. Log rate limit headers (warn at X-RateLimit-Remaining < 20)
7. Use environment variables for tokens
8. Set request timeouts (~30s default)

Quick Carrier Vetting Checklist

When evaluating a carrier:

1. Check authority status: GET /api/v2/company/{dot}/common-authority-status → active: true
2. Verify insurance: GET /api/v1/company/{dot}/insurances → valid, not expired
3. Check out-of-service: GET /api/v1/company/{dot}/out-of-service-orders → none active
4. Review safety: GET /api/v1/company/{dot}/safety-summary → acceptable rating
5. Assess risk: GET /api/v2/company/{dot}/risk-factors → score ≥ threshold
6. Generate report: GET /api/v2/company/{dot}/vetting-report → recommendation: APPROVED

Examples

Language-specific examples: {baseDir}/../../examples/ directory

• Python, JavaScript, Go, Ruby, PHP — each is a complete working client

Resources

• SearchCarriers API
• Quick reference: {baseDir}/../../quick-reference.md
• Detailed references: See references/ directory