FMCSA API

    FMCSA API Documentation

    Complete reference for AlphaLoops's carrier data API. Look up carriers by DOT number, MC number, or name. Access safety data, authority status, technology stack, and more.

    Enterprise PlanAPI access is available exclusively on our Enterprise plan.

    New to FMCSA data? Start with our complete guide →

    OpenAPI SpecRun in Postman

    Quick Start

    Base URL

    https://api.runalphaloops.com

    Authentication

    Include your API key in the Authorization header:

    Authorization: Bearer YOUR_API_KEY

    Rate Limits

    Enterprise API access includes 60 requests per minute and 5,000 requests per day. Need more? Additional credits are available for purchase. Rate limit headers are included in every response:

    X-RateLimit-Limit: 60 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1709325600 X-DailyLimit-Limit: 5000 X-DailyLimit-Remaining: 4832 X-DailyLimit-Reset: 1709337600

    Endpoints

    Safety, Authority & Insurance

    GET/v1/carriers/{dot_number}/safetyCOMING SOON

    Get detailed safety data including BASIC scores, inspection history, and crash records.

    GET/v1/carriers/{dot_number}/authority

    Get the carrier's operating authority history. Returns all authority actions including grants, revocations, and reinstatements.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Results per page (default: 50)
    offset number No Number of results to skip (default: 0)

    Response Example

    {
  "dot_number": "2247505",
  "total_records": 5,
  "limit": 50,
  "offset": 0,
  "authority_history": [
    {
      "docket_number": "MC-728261",
      "sub_number": "1",
      "authority_type": "COMMON",
      "original_action": "GRANT",
      "original_served_date": "1990-06-15",
      "disposition_action": "GRANT",
      "disposition_decided_date": "1990-06-15",
      "disposition_served_date": "1990-06-20"
    }
  ]
}
    GET/v1/carriers/{dot_number}/insurance

    Retrieve insurance filings (BIPD, cargo, bond) for a carrier from the FMCSA insurance table. Includes policy numbers, coverage limits, and insurer details.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Results per page (default: 50, max: 500)
    page number No Page number (default: 1)
    sort_by string No Sort field: effective_date, insurance_type_code, bipd_maximum_dollar_limit, insurance_company_name (default: effective_date)
    sort_order string No "asc" or "desc" (default: "desc")
    insurance_type string No Filter by insurance type code
    insurer string No Partial match on insurance company name
    min_coverage number No Minimum BIPD dollar limit
    date_from string No Effective date start (ISO date)
    date_to string No Effective date end (ISO date)

    Response Example

    {
  "dot_number": "2233855",
  "total_policies": 8,
  "insurance": [
    {
      "id": 123456,
      "docket_number": "MC133655",
      "dot_number": "2233855",
      "mc_number": 133655,
      "insurance_type": {
        "code": "BIPD",
        "description": "Bodily Injury & Property Damage"
      },
      "bipd": {
        "class_code": "PRIMARY",
        "class_description": "Primary BIPD",
        "maximum_dollar_limit": 5000000,
        "underlying_dollar_limit": null
      },
      "policy_number": "PLC-2024-001234",
      "effective_date": "2024-01-15",
      "form": {
        "code": "BMC91X",
        "description": "Motor Carrier Surety Bond"
      },
      "insurance_company_name": "National Union Fire Ins Co Of Pittsburgh"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_results": 8,
    "total_pages": 1
  }
}
    GET/v1/carriers/mc/{mc_number}/insurance

    Retrieve insurance filings by MC docket number. Same response shape and filters as the DOT-based insurance endpoint.

    Parameters

    Name Type Required Description
    mc_number string Yes MC docket number (numeric)
    limit number No Results per page (default: 50, max: 500)
    page number No Page number (default: 1)
    sort_by string No Sort field: effective_date, insurance_type_code, bipd_maximum_dollar_limit, insurance_company_name (default: effective_date)
    sort_order string No "asc" or "desc" (default: "desc")
    insurance_type string No Filter by insurance type code
    insurer string No Partial match on insurance company name
    min_coverage number No Minimum BIPD dollar limit

    Response Example

    {
  "mc_number": 133655,
  "total_policies": 8,
  "insurance": [
    {
      "id": 123456,
      "docket_number": "MC133655",
      "dot_number": "2233855",
      "mc_number": 133655,
      "insurance_type": {
        "code": "BIPD",
        "description": "Bodily Injury & Property Damage"
      },
      "bipd": {
        "class_code": "PRIMARY",
        "class_description": "Primary BIPD",
        "maximum_dollar_limit": 5000000
      },
      "policy_number": "PLC-2024-001234",
      "effective_date": "2024-01-15",
      "form": {
        "code": "BMC91X",
        "description": "Motor Carrier Surety Bond"
      },
      "insurance_company_name": "National Union Fire Ins Co Of Pittsburgh"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_results": 8,
    "total_pages": 1
  }
}
    GET/v1/carriers/{dot_number}/timeline

    Retrieve a merged chronological feed of carrier change events and authority history. Combines field-level changes from monthly FMCSA census diffs (contact, address, fleet, operations, authority, people) with authority history records.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Max results (default: 50, max: 200)
    offset number No Pagination offset (default: 0)
    category string No Comma-separated categories: contact, address, fleet, operations, authority, people
    date_from string No Start date (ISO date)
    date_to string No End date (ISO date)

    Response Example

    {
  "dot_number": "2233855",
  "total": 127,
  "category_counts": {
    "fleet": 25,
    "authority": 12,
    "operations": 45,
    "contact": 18,
    "address": 8,
    "people": 19
  },
  "limit": 50,
  "offset": 0,
  "events": [
    {
      "id": 98765,
      "dot_number": "2233855",
      "detected_at": "2024-03-01",
      "category": "fleet",
      "event_type": "fleet_size_changed",
      "headline": "Power units changed from 9,200 to 9,500",
      "field_name": "power_units",
      "old_value": "9200",
      "new_value": "9500",
      "metadata": null,
      "source": "census_diff"
    },
    {
      "id": "auth_44321",
      "dot_number": "2233855",
      "detected_at": "2024-01-10",
      "category": "authority",
      "event_type": "authority_action",
      "headline": "[COMMON] GRANTED",
      "field_name": null,
      "old_value": null,
      "new_value": null,
      "metadata": {
        "docket_number": "MC-133655",
        "sub_number": "1",
        "authority_type": "COMMON",
        "original_action": "GRANTED",
        "disposition_action": "GRANTED",
        "disposition_decided_date": "2024-01-08",
        "disposition_served_date": "2024-01-10"
      },
      "source": "fmcsa_authority"
    }
  ]
}

    Fleet & Equipment

    GET/v1/carriers/{dot_number}/trucks

    Get the carrier's registered truck (power unit) fleet. Includes VIN, make, model, engine specs, weight, and manufacturing details.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Results per page (default: 50, max: 200)
    offset number No Number of results to skip (default: 0)

    Response Example

    {
  "dot_number": "2247505",
  "total_trucks": 18643,
  "trucks": [
    {
      "vin": "1XKYD49X0MJ441234",
      "dot_number": "2247505",
      "cab_type": "CONVENTIONAL",
      "make": "KENWORTH",
      "model": "T680",
      "model_year": 2022,
      "engine_manufacturer": "PACCAR",
      "license_plate": "AZ-4821",
      "manufactured_by": "KENWORTH TRUCK CO",
      "manufactured_in": "UNITED STATES",
      "gross_weight": 80000,
      "body_type": "TRUCK TRACTOR",
      "engine_displacement": "12.9L",
      "engine_type": "DIESEL",
      "engine_cylinders": 6,
      "engine_model": "MX-13",
      "brake_system_type": "AIR",
      "plant_city": "CHILLICOTHE",
      "plant_state": "OH"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total_results": 18643
}
    GET/v1/carriers/{dot_number}/trailers

    Get the carrier's registered trailer fleet. Includes VIN, manufacturer, type, and reefer status.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Results per page (default: 50, max: 200)
    offset number No Number of results to skip (default: 0)

    Response Example

    {
  "dot_number": "2247505",
  "total_trailers": 62104,
  "trailers": [
    {
      "vin": "1JJV532D8ML920456",
      "dot_number": "2247505",
      "manufacturer": "WABASH",
      "model_year": 2021,
      "trailer_type": "VAN/ENCLOSED BOX",
      "reefer": false,
      "license_plate": "AZ-11204"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total_results": 62104
}
    GET/v1/carriers/{dot_number}/equipment-for-sale

    Cross-references the VINs this carrier has been inspected with against a marketplace dataset of trucks and trailers currently (or recently) listed for sale. Returns one row per matching VIN, sorted by most recent inspection date. Each row's `equipment_type` field ("truck" or "trailer") determines which extra fields are populated. Empty results are common — most carriers' equipment is never listed publicly.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Results per page (default: 25, max: 200)
    page number No Page number, 1-based (default: 1)

    Response Example

    {
  "dot_number": "3701071",
  "total_listings": 12,
  "equipment": [
    {
      "equipment_type": "truck",
      "vin": "3AKJHHDR3RSUV5213",
      "last_seen_in_inspection": "2026-05-12",
      "inspection_count": 2,
      "listing_title": "2024 FREIGHTLINER CASCADIA 126",
      "manufacturer": "FREIGHTLINER",
      "model": "CASCADIA 126",
      "model_year": 2024,
      "category": null,
      "sub_category": null,
      "color": null,
      "price": 128900,
      "mileage": 249855,
      "fuel_type": null,
      "engine": {
        "manufacturer": "DETROIT",
        "model": null,
        "type": null,
        "displacement": null,
        "horsepower": "505 HP",
        "brake": null
      },
      "transmission": {
        "raw": null,
        "type": "Detroit DT12",
        "manufacturer": "DETROIT",
        "speeds": "12 Spd"
      },
      "cab": "SLEEPERCAB",
      "sleeper": { "type": null, "size": null },
      "cab_style": null,
      "drive": null,
      "suspension": "Air Ride",
      "axle_configuration": null,
      "wheelbase": null,
      "gvwr": null,
      "apu": null,
      "stock_number": null,
      "source": null,
      "description": "VEHICLE HIGHLIGHTS\nStock #: SUV5213..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_results": 12,
    "total_pages": 1
  }
}

// Equipment shape — common fields (both types):
//   equipment_type ("truck" | "trailer") — discriminator
//   vin — normalized uppercase
//   last_seen_in_inspection — most recent FMCSA inspection where this VIN
//     appeared under this DOT
//   inspection_count — how many distinct inspections that VIN appeared in
//     for this DOT
//   listing_title, manufacturer, model, model_year, price (USD),
//   category, description, stock_number
//
// equipment_type: "trailer" extra fields:
//   trailer_type, length, condition, retail_price, reefer,
//   reefer_manufacturer, reefer_model, dealer, dealer_location,
//   location: { city, state, postal_code, country },
//   listing_url, image_count, listing_updated
//
// equipment_type: "truck" extra fields:
//   sub_category, color, mileage (numeric), fuel_type,
//   engine: { manufacturer, model, type, displacement, horsepower, brake },
//   transmission: { raw, type, manufacturer, speeds },
//   cab (e.g. DAYCAB/SLEEPERCAB), sleeper: { type, size },
//   cab_style, drive, suspension, axle_configuration, wheelbase, gvwr,
//   apu, source
//
// Matching is VIN-based: a result means the same VIN appears in both the
// carrier's inspection-unit history and a listing record. inspection_count
// and last_seen_in_inspection help judge how strongly the VIN is tied to
// that carrier (e.g. a single 5-year-old inspection vs. 12 inspections
// over the past year). Garbage placeholder VINs (all-zeros, repeated chars,
// UNKNOWN/N/A) are filtered out before matching.

    Inspections & Crashes

    GET/v1/carriers/{dot_number}/inspections

    Get the carrier's roadside inspection history. Returns inspection metadata and out-of-service counts. Use /v1/inspections/{inspection_id}/violations to get violation details for a specific inspection.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Results per page (default: 50, max: 200)
    offset number No Number of results to skip (default: 0)

    Response Example

    {
  "dot_number": "2247505",
  "total_inspections": 4521,
  "inspections": [
    {
      "inspection_id": "AZ2024061512345",
      "report_number": "AZ2024061512345",
      "date": "2024-06-15",
      "state": "AZ",
      "level": 1,
      "start_time": "08:30",
      "end_time": "09:45",
      "location": "I-10 MM 142",
      "facility": "ROADSIDE",
      "carrier_name": "SWIFT TRANSPORTATION CO OF ARIZONA LLC",
      "shipper_name": "ACME CORP",
      "gross_vehicle_weight": 72000,
      "violations_total": 2,
      "driver_violations": 1,
      "vehicle_violations": 1,
      "hazmat_violations": 0,
      "oos_total": 0,
      "oos_driver": false,
      "oos_vehicle": false,
      "oos_hazmat": false,
      "traffic_enforcement": false,
      "size_weight_enforcement": false
    }
  ],
  "limit": 50,
  "offset": 0,
  "total_results": 4521
}
    GET/v1/inspections/vin/{vin}

    Look up the inspection history for a Vehicle Identification Number (VIN). Returns the unique DOT numbers the VIN has been associated with (with the last date seen on each), plus the unique locations (FIPS-coded counties enriched with county name, state abbreviation, latitude, and longitude) where the VIN has been inspected. Designed for verification workflows — confirming which carriers a tractor/trailer has run for and where it's been operating. Capped at the 5,000 most-recent inspections; when truncated, aggregations are computed over the returned sample. Successful responses are edge-cached for 24h; 404s for 1h.

    Parameters

    Name Type Required Description
    vin string Yes Vehicle Identification Number (case-insensitive — normalized to uppercase server-side)

    Response Example

    {
  "vin": "1FUJGLDR8DSBJ8237",
  "inspection_count": 47,
  "sample_size": 47,
  "truncated": false,
  "dot_numbers": [
    {
      "dot_number": "2233855",
      "last_seen": "2025-09-12",
      "inspection_count": 31
    },
    {
      "dot_number": "1287194",
      "last_seen": "2023-04-08",
      "inspection_count": 16
    }
  ],
  "locations": [
    {
      "fips": "48201",
      "state_fips": "48",
      "county_fips": "201",
      "county_name": "Harris County",
      "state_abbrev": "TX",
      "latitude": 29.857908,
      "longitude": -95.392479,
      "last_seen": "2025-09-12",
      "inspection_count": 9
    },
    {
      "fips": "06037",
      "state_fips": "06",
      "county_fips": "037",
      "county_name": "Los Angeles County",
      "state_abbrev": "CA",
      "latitude": 34.196869,
      "longitude": -118.261862,
      "last_seen": "2025-07-22",
      "inspection_count": 5
    }
  ]
}
    GET / POST/v1/vins

    Look up one or more VINs. For each VIN, returns its FMCSA inspection-unit history (where the equipment has been), its most recent sighting, every DOT it has been associated with, and whether it has ever been listed for sale (as a truck or trailer). Accepts a single VIN, a comma-separated list, or a JSON array (POST). VINs are uppercased, trimmed, and de-duplicated server-side; matching is case-insensitive. Max 100 VINs per request. Results preserve input order and include misses (found: false), so callers can tell which VINs had no data.

    Parameters

    Name Type Required Description
    vin string No A single VIN to look up — GET query form (e.g. ?vin=3AKJHHDR3RSUV5213). Case-insensitive.
    vins string | string[] No Multiple VINs. GET: comma-separated query string (?vins=VIN1,VIN2,VIN3). POST: JSON array in the request body ({ "vins": [...] }). Max 100 VINs per request.

    Request Examples

    # Single VIN (GET)
curl "https://api.runalphaloops.com/v1/vins?vin=3AKJHHDR3RSUV5213" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Comma-separated list (GET)
curl "https://api.runalphaloops.com/v1/vins?vins=3AKJHHDR3RSUV5213,1XKYDP9X3KJ239110" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Batch (POST)
curl -X POST "https://api.runalphaloops.com/v1/vins" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vins": ["3AKJHHDR3RSUV5213", "1XKYDP9X3KJ239110"]}'

    Response Example

    {
  "requested": 2,
  "results": [
    {
      "vin": "3AKJHHDR3RSUV5213",
      "found": true,
      "inspection_count": 2,
      "most_recent": {
        "date": "2026-05-12",
        "time": "0740",
        "location": "I-10 23 WB",
        "state": "CA",
        "dot_number": "3701071",
        "inspection_id": 87942748
      },
      "dots_associated": ["3701071"],
      "inspections": [
        {
          "inspection_id": 87942748,
          "insp_unit_number": 2,
          "unit_type": "TRAILER",
          "make": "FREIGHTLINER",
          "license": "DM1882",
          "license_state": "CA",
          "company": "LAND OF LIGHT TRANSPORT LLC",
          "date": "2026-05-12",
          "start_time": "0740",
          "end_time": "0810",
          "location": "I-10 23 WB",
          "state": "CA",
          "dot_number": "3701071"
        }
      ],
      "for_sale": {
        "listed": true,
        "as_truck": {
          "listing_title": "2024 FREIGHTLINER CASCADIA 126",
          "manufacturer": "FREIGHTLINER",
          "model": "CASCADIA 126",
          "model_year": 2024,
          "price": 128900,
          "mileage": 249855,
          "engine": { "manufacturer": "DETROIT", "model": null, "type": null, "displacement": null, "horsepower": "505 HP", "brake": null },
          "transmission": { "raw": null, "type": "Detroit DT12", "manufacturer": "DETROIT", "speeds": "12 Spd" },
          "cab": "SLEEPERCAB",
          "sleeper": { "type": null, "size": null },
          "suspension": "Air Ride",
          "description": "..."
        },
        "as_trailer": null
      }
    },
    {
      "vin": "1XKYDP9X3KJ239110",
      "found": false,
      "inspection_count": 0,
      "most_recent": null,
      "dots_associated": [],
      "inspections": [],
      "for_sale": { "listed": false, "as_truck": null, "as_trailer": null }
    }
  ]
}

// Top-level: requested = unique VIN count after normalization. results
//   preserves input order — one entry per VIN, including misses.
// most_recent is the most recent sighting ({ date, time, location, state,
//   dot_number, inspection_id }) or null if the VIN was never inspected.
// dots_associated with more than one DOT is a strong signal the equipment
//   changed hands or was re-registered between carriers.
// A VIN can be found: false (no inspections) but still have
//   for_sale.listed: true, or vice-versa — the two data sources are independent.
// for_sale.as_truck / as_trailer match the truck/trailer object shapes from
//   GET /v1/carriers/{dot_number}/equipment-for-sale.
    GET/v1/inspections/{inspection_id}/violations

    Retrieve all violations from a specific roadside inspection. Use the inspection report number returned from the Inspections endpoint to drill into violation details.

    Parameters

    Name Type Required Description
    inspection_id string Yes The inspection report number
    page number No Page number (default: 1)
    limit number No Results per page (default: 25, max: 100)

    Response Example

    {
  "inspection_id": "TX2400012345",
  "total_violations": 3,
  "violations": [
    {
      "violation_code": "393.100",
      "description": "ADB - No or Defective ABS on Trailer",
      "oos": true,
      "unit_type": "TRAILER",
      "basic_category": "Vehicle Maintenance"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_results": 3,
    "total_pages": 1
  }
}
    GET/v1/carriers/{dot_number}/crashes

    Get the carrier's reported crash history. Includes crash details, severity, and contributing factors.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    start_date string No Filter from date (ISO 8601, e.g. "2024-01-01")
    end_date string No Filter to date (ISO 8601, e.g. "2024-12-31")
    severity string No Filter by severity: "FATAL", "INJURY", "TOW", "PROPERTY_DAMAGE"
    page number No Page number (default: 1)
    limit number No Results per page (default: 25, max: 100)

    Response Example

    {
  "dot_number": "2247505",
  "total_crashes": 89,
  "crashes": [
    {
      "crash_id": "TX20240322-0041",
      "report_number": "AZ20240322-0041",
      "date": "2024-03-22",
      "state": "TX",
      "city": "DALLAS",
      "location": "I-35 SB MM 428",
      "fatalities": 0,
      "injuries": 1,
      "tow_away": true,
      "hazmat_released": false,
      "severity": "INJURY",
      "vehicle_configuration": "TRUCK TRACTOR/SEMI-TRAILER",
      "cargo_body_type": "VAN/ENCLOSED BOX",
      "road_surface_condition": "DRY",
      "trafficway": "DIVIDED HIGHWAY",
      "weather_condition": "CLEAR",
      "light_condition": "DAYLIGHT",
      "vehicles_in_accident": 2,
      "truck_or_bus": "TRUCK",
      "gvw_rating": "26,001 LBS. OR MORE",
      "federal_recordable": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_results": 89,
    "total_pages": 4
  }
}

    MC Sales & Listings

    GET/v1/carriers/{dot_number}/mc-sales

    Get any authority-for-sale listings (social sale channels, marketplaces, etc.) that have been linked to this carrier's DOT number. Returns all detected occurrences with seller info, asking prices, post URLs, and matching reasoning. Each listing also carries structured metadata extracted from the post itself — claimed authority age and status, safety stats (inspections, violations, OOS rates), and which business assets transfer with the sale (Amazon Relay, Highway, bank account, factoring, insurance). Returns `found: false` with `mc_sale: null` when no listings have been linked to this carrier.

    Parameters

    Name Type Required Description
    dot_number integer Yes The carrier's USDOT number

    Response Example

    {
  "dot_number": 2567323,
  "found": true,
  "mc_sale": {
    "mc_numbers": ["896740"],
    "carrier": {
      "legal_name": "DRZ TRANSPORT LLC",
      "dba_name": null,
      "state": "MN",
      "city": null,
      "phone": null,
      "email": null,
      "officers": []
    },
    "summary": {
      "occurrence_count": 1,
      "avg_confidence": 0.75,
      "max_confidence": 0.75
    },
    "listings": [
      {
        "seller_name": "JJ Junior (Mohamed Yusuf)",
        "phone": null,
        "email": null,
        "asking_price": null,
        "authority_age": "10 years",
        "post_url": "https://www.facebook.com/groups/.../permalink/...",
        "source_file": null,
        "confidence": 0.75,
        "reasoning": "Seller \"JJ Junior\" Facebook profile shows Minneapolis, MN...",
        "post": {
          "source": "facebook_group",
          "source_url": "https://www.facebook.com/groups/1473049439938346/",
          "source_name": null,
          "posted_at": "2026-05-25T18:12:04+00:00",
          "engagement": { "likes": 3, "comments": 13, "shares": 0 }
        },
        "authority": {
          "type": "Carrier",
          "status": "Active",
          "state": "MN",
          "mc_number": "896740",
          "dot_number": "2567323",
          "granted_date": "2016-05-25",
          "granted_date_precision": "age",
          "reinstated_date": null,
          "ein_disclosed": false
        },
        "safety": {
          "total_inspections": 7,
          "total_violations": 2,
          "total_crashes": 0,
          "vehicle_oos_pct": 0,
          "driver_oos_pct": 0,
          "vehicle_oos_count": null,
          "driver_oos_count": null
        },
        "included_assets": {
          "highway_setup": true,
          "amazon_status": "Live",
          "bank_name": "Chase",
          "factoring_name": "OTR Solutions",
          "insurer": "Progressive",
          "insurance_limit_k": null,
          "fleet_size": 1,
          "email_included": true,
          "phone_included": true
        },
        "asking_price_usd": 28000,
        "sold": null
      }
    ],
    "first_seen": "2026-05-25T20:59:29.761414+00:00",
    "last_seen": "2026-05-25T20:59:29.733220+00:00"
  }
}

// 200 OK — no match
{ "dot_number": 999999999, "found": false, "mc_sale": null }

// Field notes
// - mc_sale.listings[] is a per-occurrence array. Each item represents one
//   detected sales post; the fields on it come from a single observation.
// - summary.max_confidence and summary.avg_confidence are 0-1 floats from the
//   matching pipeline; treat low scores (<0.4) as weak/uncertain matches.
// - post.source is one of "facebook_group" | "facebook_page" | "telegram" |
//   "mcxchange" | "bizbuysell". Social posts carry the full extracted field
//   set; marketplace sources populate the structured
//   fields they natively expose and leave the rest null.
// - post / authority / safety / included_assets are extracted from the post
//   text by our classification pipeline. They reflect the SELLER'S CLAIMS,
//   not FMCSA records — cross-check against /authority and /inspections.
//   The whole group is null when the source post is no longer available.
// - authority.granted_date_precision is one of "exact" | "month" | "year" |
//   "age". An "age" date is back-computed from wording like "4 years old"
//   anchored to the post date — treat it as approximate (±1 year).
// - Booleans in included_assets are tri-state: true / false / null, where
//   null means the post didn't mention it (not that it's absent).
// - included_assets.amazon_status is "Live" | "Suspended" | "Not Applicable"
//   (never applied / no access) | null.
// - asking_price_usd is the parsed numeric price. The legacy top-level
//   asking_price string is retained for backwards compatibility.
// - sold flips to true once a sold marker is detected on the post; expect lag.
// - first_seen / last_seen are ISO-8601 timestamps showing when this carrier
//   first/last appeared in the sales-monitoring pipeline.
    GET/v1/mc-sales

    Paginated collection of every carrier-resolved authority-for-sale record (one row per DOT) — the same shape as `/v1/carriers/{dot_number}/mc-sales`, built for bulk export and incremental sync. To sync changes since your last pull, pass `updated_after` with `sort_by=updated_at&sort_order=asc`; to pull only newly detected carriers, use `created_after`.

    Parameters

    Name Type Required Description
    limit number No Results per page (default: 25, max: 100)
    page number No Page number, 1-based (default: 1)
    sort_by string No "updated_at" (default), "created_at", "max_confidence", or "occurrence_count"
    sort_order string No "desc" (default) or "asc"
    created_after string No ISO-8601 — records first seen on/after
    created_before string No ISO-8601 — records first seen on/before (date-only includes the whole day)
    updated_after string No ISO-8601 — records changed on/after
    updated_before string No ISO-8601 — records changed on/before (date-only includes the whole day)
    state string No 2-letter carrier state
    min_confidence number No Minimum match confidence, 0-1

    Response Example

    {
  "total_results": 2952,
  "mc_sales": [
    {
      "dot_number": 2567323,
      "mc_numbers": ["896740"],
      "carrier": {
        "legal_name": "DRZ TRANSPORT LLC",
        "dba_name": null,
        "state": "MN",
        "city": null,
        "phone": null,
        "email": null,
        "officers": []
      },
      "summary": {
        "occurrence_count": 1,
        "avg_confidence": 0.75,
        "max_confidence": 0.75
      },
      "listings": [
        { "...": "same enriched listing shape as /v1/carriers/{dot_number}/mc-sales" }
      ],
      "first_seen": "2026-05-25T20:59:29.761414+00:00",
      "last_seen": "2026-05-25T20:59:29.733220+00:00"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total_results": 2952, "total_pages": 119 }
}

// Field notes
// - One row per resolved carrier (DOT). Listings within each row carry the
//   full enriched shape documented on /v1/carriers/{dot_number}/mc-sales.
// - first_seen / last_seen map to the record's created/updated timestamps
//   and drive the created_* / updated_* filters. Incremental-sync recipe:
//   updated_after=<your last cursor>&sort_by=updated_at&sort_order=asc,
//   page until done, then remember the max last_seen you saw.
// - Carrier identity fields come from the resolution-time snapshot; use
//   /v1/carriers/{dot_number} for the live FMCSA record.
    GET/v1/mc-sale-listings

    Paginated feed of raw authority-for-sale listings across all monitored sources — social sale channels and public marketplaces — independent of whether they've been resolved to a carrier. Ordered by posted-at descending with cursor pagination: follow `next_cursor` until `has_more` is false. Structured fields (`authority`, `safety`, `included_assets`) are extracted from the post text and reflect the seller's claims, not FMCSA records.

    Parameters

    Name Type Required Description
    limit number No Results per page (default: 25, max: 100)
    cursor string No Opaque cursor from a previous response's next_cursor
    source string No Comma-separated subset of: facebook_group, facebook_page, telegram, mcxchange, bizbuysell
    state string No 2-letter state code claimed in the listing
    posted_after string No ISO-8601 date — listings posted on/after
    posted_before string No ISO-8601 date — listings posted on/before (a date-only value includes that whole day)
    min_price number No Minimum asking price (USD)
    max_price number No Maximum asking price (USD)
    amazon_status string No "Live", "Suspended", or "Not Applicable"
    highway_setup boolean No Highway account claimed in the listing

    Response Example

    {
  "listings": [
    {
      "id": "facebook_group:e27603ca-654b-491d-b677-c27fded3298e",
      "post_url": "https://www.facebook.com/groups/.../permalink/...",
      "post_text": "Company for sale MC&DOT — State: Illinois, Age: 6+ years, Inspection: 9 ...",
      "seller_name": "Aisha Ahmed",
      "phone": "7246035657",
      "email": null,
      "linked_dot_numbers": [2966078],
      "post": {
        "source": "facebook_group",
        "source_url": "https://www.facebook.com/groups/1473049439938346/",
        "source_name": null,
        "posted_at": "2026-07-08T12:23:07+00:00",
        "engagement": { "likes": 2, "comments": 9, "shares": 0 }
      },
      "authority": {
        "type": "Carrier",
        "status": "Active",
        "state": "IL",
        "mc_number": null,
        "dot_number": null,
        "granted_date": "2020-05-28",
        "granted_date_precision": "age",
        "reinstated_date": null,
        "ein_disclosed": false
      },
      "safety": {
        "total_inspections": 9,
        "total_violations": 2,
        "total_crashes": 0,
        "vehicle_oos_pct": 20,
        "driver_oos_pct": null,
        "vehicle_oos_count": null,
        "driver_oos_count": null
      },
      "included_assets": {
        "highway_setup": true,
        "amazon_status": "Not Applicable",
        "bank_name": null,
        "factoring_name": null,
        "insurer": "United Financial Casualty",
        "insurance_limit_k": null,
        "fleet_size": null,
        "email_included": null,
        "phone_included": true
      },
      "asking_price_usd": 15000,
      "sold": null
    }
  ],
  "limit": 25,
  "has_more": true,
  "next_cursor": "eyJmYWNlYm9va19ncm91cCI6..."
}

// Field notes
// - id is namespaced "{source}:{native_id}" and stable across pages.
// - linked_dot_numbers lists carriers this listing has been resolved to
//   (highest match confidence first); empty when unresolved. Cross-reference
//   with /v1/carriers/{dot_number}/mc-sales for the carrier-side view —
//   seller_name / phone / email match that endpoint's listing fields.
// - post_text is truncated to 1,000 characters; follow post_url for the
//   full post.
// - This feed uses cursor pagination (no total count) — it merges five
//   source tables on a keyset cursor. Pass next_cursor back verbatim;
//   page/offset params return 400.
// - For facebook_page and bizbuysell, ordering and the posted_after/
//   posted_before filters use the time the listing was first ingested
//   (their native post dates are unreliable), so post.posted_at may differ
//   from the filter bound.
// - Filters push down per source: some marketplace sources carry no
//   Amazon/Highway metadata, so amazon_status / highway_setup filters
//   exclude them. Price filters only match listings with a parsed
//   price between $1 and $1M.
// - The extracted-claim caveats from /mc-sales apply here too:
//   granted_date_precision "age" dates are ±1 year, and included_assets
//   booleans are tri-state (null = not mentioned).

    Risk & Intelligence

    GET/v1/carriers/{dot_number}/risk-signals

    Aggregated carrier risk assessment in a single call. Returns an AI-generated risk score (0-10) and level, plus six signal categories — authority-for-sale listings, equipment-for-sale marketplace matches, financial-distress indicators, fraud/chameleon patterns, historical authority/insurance/change-event patterns, and recent news sentiment. Each category carries a derived `level` of "high", "medium", "clear", or "unknown" so you can triage without re-implementing the scoring logic. The risk summary is cached (regenerated when the underlying signals change); pass force_refresh=true to force a fresh generation.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    force_refresh boolean No Set to "true" to bypass the cached risk summary and regenerate it from current signals (slower). Default: false.
    include_equipment boolean No Set to "false" to skip the equipment-marketplace VIN lookup for a faster response. When false, equipment match details are omitted (the match count still reflects the carrier). Default: true.

    Response Example

    {
  "dot_number": "2567323",
  "carrier_name": "DRZ TRANSPORT LLC",
  "location": { "city": "MINNEAPOLIS", "state": "MN" },
  "risk_score": 7.4,
  "risk_level": "HIGH",
  "summary": "DRZ Transport (DOT 2567323) shows an active authority-for-sale listing and a triggered sold-MC chameleon pattern...",
  "generated_at": "2026-06-10T18:24:05.118Z",
  "cached": true,
  "summary_available": true,
  "signals": {
    "authority_for_sale": { "level": "high", "subtitle": "1 occurrence · 75% confidence", "...": "..." },
    "equipment_for_sale": { "level": "medium", "subtitle": "1 VIN found on equipment marketplaces", "...": "..." },
    "financial_risk":     { "level": "clear",  "...": "..." },
    "fraud_signals":      { "level": "medium", "is_chameleon": true, "...": "..." },
    "historical_patterns":{ "level": "high",   "subtitle": "2 risk patterns triggered", "...": "..." },
    "recent_activity":    { "level": "clear",  "...": "..." }
  }
  // ... expand to see the full signal payload
}
    GET/v1/carriers/{dot_number}/news

    Get recent news articles and press mentions related to the carrier.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    start_date string No Filter from date (ISO 8601, e.g. "2024-01-01")
    end_date string No Filter to date (ISO 8601, e.g. "2024-12-31")
    page number No Page number (default: 1)
    limit number No Results per page (default: 25, max: 100)

    Response Example

    {
  "dot_number": "2247505",
  "total_results": 3,
  "articles": [
    {
      "id": "381500d33fe54ca0b62b69e33b865f68",
      "title": "Insurers Judged By The Trucking \"Company\" They Keep",
      "description": "The recent fatal crashes in Texas and Florida highlight the vulnerability of insurance companies in trucking, highlighting inconsistencies and underwriting issues in the industry.",
      "url": "https://finance.yahoo.com/news/insurers-judged-trucking-company-keep-111253688.html",
      "source": "finance.yahoo.com",
      "date": "2026-02-22T11:12:53+00:00",
      "type": "Accidents & Disasters",
      "sentiment": "negative",
      "image_url": "https://s.yimg.com/ny/api/res/1.2/wMWUugFK7QqYSEXxs8QrDQ--/YXBwaWQ9aGlnaGxhbmRlcjt3PTEyMDA7aD04MDA7Y2Y9d2VicA--/https://media.zenfs.com/en/freightwaves_373/b9fd29b5cc823ae09f9fd12f0cf2579f",
      "categories": [],
      "topics": [],
      "people": [],
      "companies": []
    },
    {
      "id": "0c51db4f048f4874a8af42da909ca2fb",
      "title": "The Catastrophic State of Trucking and Highway Safety",
      "description": "Yahoo's AI generates key points for safety, highlighting widespread failures in trucking and highway safety, with individuals like Harjinder Singh killing multiple people.",
      "url": "https://www.yahoo.com/news/articles/catastrophic-state-trucking-highway-safety-132927796.html",
      "source": "yahoo.com",
      "date": "2026-02-11T13:29:27+00:00",
      "type": "Accidents & Disasters",
      "sentiment": "negative",
      "image_url": "https://s.yimg.com/ny/api/res/1.2/Zk4JxiUGmyzXoXv9h4Zxgg--/YXBwaWQ9aGlnaGxhbmRlcjt3PTEyMDA7aD02NzU7Y2Y9d2VicA--/https://media.zenfs.com/en/freightwaves_373/205c14e7c6be280421261ab640e2acbc",
      "categories": ["Tech"],
      "topics": [],
      "people": [],
      "companies": []
    },
    {
      "id": "6d3b7429157c4e3db038913179cb0c26",
      "title": "Blind Spots: A Nationwide Pattern of Loopholes, Lapses and Lost Lives",
      "description": "The Dill family faces daily challenges due to a severe crash involving a semi-truck, resulting in multiple injuries, and inconsistent documentation.",
      "url": "https://www.wtsp.com/article/news/investigations/10-investigates/trucking-industry-investigation-blind-spots/67-a07664b7-235d-4d1f-aef0-6f44663671f2",
      "source": "wtsp.com",
      "date": "2026-02-02T00:00:00",
      "type": "Death & Tragedy",
      "sentiment": "negative",
      "image_url": "https://media.wtsp.com/assets/WTSP/images/b71d9cea-3867-4cab-ba79-b7a072a63558/20260115T204722/b71d9cea-3867-4cab-ba79-b7a072a63558_1140x641.jpg",
      "categories": [],
      "topics": [],
      "people": [],
      "companies": []
    }
  ]
}
    GET/v1/carriers/{dot_number}/connections

    Retrieve a carrier's corporate connections graph — shared officers, addresses, and related entities.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Max results (default: 50, max: 200)

    Response Example

    {
  "dot_number": "2233855",
  "total_nodes": 15,
  "total_edges": 22,
  "nodes": [
    {
      "id": "2233855",
      "type": "carrier",
      "label": "SCHNEIDER NATIONAL CARRIERS INC"
    },
    {
      "id": "1098765",
      "type": "carrier",
      "label": "SCHNEIDER LOGISTICS INC"
    }
  ],
  "edges": [
    {
      "source": "2233855",
      "target": "1098765",
      "relationship": "shared_officer"
    }
  ]
}
    GET/v1/carriers/{dot_number}/similar

    Find carriers similar to the specified carrier based on fleet size, location, cargo type, and other attributes.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    limit number No Max results (default: 20, max: 100)

    Response Example

    {
  "dot_number": "2233855",
  "similar_carriers": [
    {
      "dot_number": "1123456",
      "legal_name": "HEARTLAND EXPRESS INC",
      "state": "IA",
      "power_units": 4200,
      "similarity_score": 0.91
    }
  ]
}
    GET/v1/carriers/{dot_number}/overview

    Get an AI-generated summary overview of a carrier including key highlights.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number

    Response Example

    {
  "dot_number": "2233855",
  "overview": "Schneider National Carriers Inc is a large, well-established carrier operating out of Green Bay, WI...",
  "highlights": [
    "One of the largest for-hire carriers in North America",
    "Strong safety record with Satisfactory rating",
    "Diversified operations across truckload, intermodal, and logistics"
  ]
}
    GET/v1/intentCOMING SOON

    Build a list of carriers showing intent around specific topics. Returns carriers that are actively researching, clicking, and engaging with content related to your query — powered by click-level web activity data.

    GET/v1/carriers/{dot_number}/transactionsCOMING SOON

    See what a carrier is spending money on. Returns anonymized, aggregated transaction data showing vendor categories, spend trends, and purchasing patterns.

    Contacts & Enrichment

    GET/v1/contacts/search

    Find people at a given company. Returns professional profiles including name, title, seniority, social profiles, and industry. Use dot_number or company_name to search. Note: This endpoint may return HTTP 202 with a Retry-After header if contacts are still being fetched — retry after the specified delay.

    Parameters

    Name Type Required Description
    dot_number string No The carrier's USDOT number
    company_name string No Company name to search (required if dot_number not provided)
    job_title string No Filter by job title keyword (e.g. "safety", "operations")
    job_title_levels string No Filter by seniority: "vp", "director", "manager", "c_suite"
    page number No Page number (default: 1)
    limit number No Results per page (default: 25, max: 100)

    Response Example

    // 200 OK — contacts ready
{
  "dot_number": "90849",
  "total_contacts": 42,
  "contacts": [
    {
      "id": "PEKpu5zopJZKUJWTUMvYFA_0000",
      "full_name": "Christopher Cada",
      "first_name": "Christopher",
      "last_name": "Cada",
      "sex": "male",
      "job_title": "Vice President Operations & Strategic Accounts",
      "job_title_role": "fulfillment",
      "job_title_levels": ["vp"],
      "job_company_name": "KTL Inc",
      "job_company_website": "ktlinc.com",
      "job_company_size": "51-200",
      "job_company_industry": "transportation/trucking/railroad",
      "job_start_date": "2019-01",
      "industry": "transportation/trucking/railroad",
      "linkedin_url": "linkedin.com/in/christophercada",
      "facebook_url": "facebook.com/christopher.cada.7",
      "location_name": "west olive, michigan, united states",
      "location_region": "michigan",
      "location_country": "united states"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_results": 42,
    "total_pages": 2
  }
}

// 202 Accepted — contacts still being fetched (Retry-After: 5)
{
  "status": "pending",
  "dot_number": "90849",
  "message": "Contacts are being fetched. Please retry in a few seconds.",
  "retry_after": 5
}
    GET/v1/contacts/{contact_id}/enrich

    Enrich a contact profile by ID. Returns verified emails, phone numbers, skills, full work history, education, and social profiles.

    Parameters

    Name Type Required Description
    contact_id string Yes The contact ID returned from /v1/contacts/search

    Response Example

    {
  "id": "PEKpu5zopJZKUJWTUMvYFA_0000",
  "full_name": "Christopher Cada",
  "first_name": "Christopher",
  "last_name": "Cada",
  "sex": "male",
  "job_title": "Vice President Operations & Strategic Accounts",
  "job_title_role": "fulfillment",
  "job_title_levels": ["vp"],
  "job_company_name": "KTL Inc",
  "job_company_website": "ktlinc.com",
  "job_company_size": "51-200",
  "job_company_industry": "transportation/trucking/railroad",
  "work_email": "ccada@ktlinc.com",
  "personal_emails": ["christopher.cada@gmail.com"],
  "mobile_phone": null,
  "phone_numbers": ["+1 630-817-6841", "+1 301-360-0001"],
  "linkedin_url": "linkedin.com/in/christophercada",
  "facebook_url": "facebook.com/christopher.cada.7",
  "location_name": "west olive, michigan, united states",
  "location_locality": "west olive",
  "location_region": "michigan",
  "location_country": "united states",
  "location_geo": "42.91,-86.14",
  "skills": [
    "3pl", "account management", "logistics", "supply chain management",
    "transportation", "freight", "operations management", "tms"
  ],
  "experience": [
    {
      "title": "Vice President Operations & Strategic Accounts",
      "company": "KTL Inc",
      "start_date": "2019-01",
      "end_date": null,
      "is_primary": true
    },
    {
      "title": "Business Product Owner",
      "company": "BluJay Solutions",
      "start_date": "2018-03",
      "end_date": "2019-08",
      "is_primary": false
    }
  ],
  "education": [
    {
      "school": "Embry-Riddle Aeronautical University",
      "start_date": "2006-01",
      "end_date": "2014"
    }
  ],
  "profiles": [
    { "network": "linkedin", "url": "linkedin.com/in/christophercada" },
    { "network": "facebook", "url": "facebook.com/christopher.cada.7" }
  ],
  "credits": {
    "remaining": 49,
    "total": 50,
    "used": 1
  }
}

    Custom Data

    GET/v1/custom-data/fields

    Discover whether custom data is enabled for your account and which fields it exposes. Accounts with a connected CRM integration can have their own custom data — account-specific fields keyed by DOT number — served through the API. Call this first: a key without custom data gets a 200 flag here (never a 403), so it is always safe to probe.

    Response Example

    // Enabled
{
  "custom_data_enabled": true,
  "source_integration": "salesforce",
  "fields": [
    { "field_key": "predicted_loads_per_month", "display_name": "Predicted Loads Per Month", "data_type": "number" },
    { "field_key": "percentile", "display_name": "Percentile", "data_type": "number" },
    { "field_key": "named_account__c", "display_name": "Named Account", "data_type": "boolean" },
    { "field_key": "engagement_cohort_tag", "display_name": "Engagement Cohort", "data_type": "text" }
  ],
  "total_records": 2729295
}

// Not enabled — still 200, never 403
{
  "custom_data_enabled": false,
  "fields": [],
  "message": "Your account does not have a custom data integration configured. Contact support to enable it."
}

// Field notes
// - Availability and the field list are per-account, driven by your CRM
//   integration configuration. source_integration is "salesforce" or "hubspot".
// - total_records is an estimate (custom datasets can run to millions of rows).
// - Fields archived from your configuration are permanently excluded from
//   every endpoint (including historical values) and reappear automatically
//   if re-enabled.
// - On the three data endpoints, 403 means custom data is NOT enabled for
//   your account — it is not an auth failure, so do not retry with backoff.
//   503 means your configuration is invalid; contact support.
// - updated_at on records reflects when the data was last loaded into
//   AlphaLoops, not real-time CRM state.
    GET/v1/custom-data

    Paginated collection of your account's custom-data records. Two pagination modes: page mode for browsing, and cursor (keyset) mode — required for full exports, since offset pagination degrades past ~100,000 rows on multi-million-row datasets. After an initial pull, use updated_after for incremental sync instead of re-exporting.

    Parameters

    Name Type Required Description
    limit number No Results per page (default: 100, max: 1000)
    page number No Page number, 1-based (default: 1). Mutually exclusive with cursor — sending both returns 400.
    cursor string No Keyset mode: opaque value from a previous response's next_cursor. Forces dot_number ascending order; follow next_cursor until has_more is false. Required mode for full exports.
    dot_number string No Comma-separated list of up to 50 DOT numbers (each 1-8 digits). For larger batches use POST /v1/custom-data/lookup.
    updated_after string No ISO-8601 — records loaded on/after this date
    updated_before string No ISO-8601 — records loaded on/before this date (date-only includes the whole day)
    sort_by string No "updated_at" (default) or "dot_number" only; anything else returns 400. Ignored in cursor mode.
    sort_order string No "desc" (default) or "asc"

    Response Example

    // Page mode
{
  "total_results": 2729295,
  "fields": [ { "field_key": "percentile", "display_name": "Percentile", "data_type": "number" } /* ... */ ],
  "records": [
    {
      "dot_number": "1234567",
      "custom_data": {
        "predicted_loads_per_month": 42,
        "percentile": 0.91,
        "named_account__c": false,
        "engagement_cohort_tag": "high"
      },
      "updated_at": "2026-07-01T00:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 100, "total_results": 2729295, "total_pages": 27293 }
}

// Cursor mode — pagination object is replaced, no totals
// "pagination": { "limit": 1000, "next_cursor": "1084321", "has_more": true }

// Field notes
// - Records share one shape everywhere: dot_number, custom_data (only your
//   account's enabled fields — never spread at the top level), updated_at.
// - total_results may be approximate when no filters are applied (exact when
//   filtered).
// - Cursor ordering is lexicographic — dot_number is a string, so "2" >
//   "1084321". Complete and stable, just not numeric.
// - Full exports: at limit=1000 a full export costs ~1 request per 1,000
//   records, which for large datasets exceeds the default 5,000/day quota.
//   Contact support to arrange a daily-limit increase before a full export,
//   then switch to updated_after incremental sync. Watch the
//   X-DailyLimit-Remaining and X-RateLimit-Remaining response headers.
    GET/v1/carriers/{dot_number}/custom-data

    Point lookup: your account's custom-data record for a single carrier. A miss returns 200 with found: false — never 404.

    Parameters

    Name Type Required Description
    dot_number string Yes USDOT number (1-8 digits; non-numeric returns 400)

    Response Example

    // Hit
{
  "dot_number": "1234567",
  "found": true,
  "custom_data": {
    "predicted_loads_per_month": 42,
    "percentile": 0.91,
    "named_account__c": false,
    "engagement_cohort_tag": "high"
  },
  "updated_at": "2026-07-01T00:00:00Z",
  "fields": [ /* same field descriptors as GET /v1/custom-data/fields */ ]
}

// Miss — 200, never 404
{
  "dot_number": "9999991",
  "found": false,
  "custom_data": null,
  "fields": [ /* ... */ ]
}

// Field notes
// - A request with leading zeros is automatically retried with the zeros
//   stripped, so a padded DOT ("0012345") matches an unpadded stored record
//   ("12345"). The reverse is not attempted.
// - The top-level dot_number always echoes the value you requested.
    POST/v1/custom-data/lookup

    Batch hydration: your account's custom-data records for up to 500 DOT numbers in one call. Ideal for enriching an existing carrier list without paging through the full collection.

    Parameters

    Name Type Required Description
    dot_numbers string[] Yes Array of 1-500 DOT numbers (numeric strings or numbers, each 1-8 digits)
    fields string[] No Optional projection: subset of your account's field keys to return. An unknown field key returns 400 naming it.

    Response Example

    // Request body
{
  "dot_numbers": ["1234567", "2345678", "9999991"],
  "fields": ["percentile", "engagement_cohort_tag"]
}

// Response
{
  "requested_count": 3,
  "found_count": 2,
  "records": [
    { "dot_number": "1234567", "custom_data": { "percentile": 0.91, "engagement_cohort_tag": "high" }, "updated_at": "2026-07-01T00:00:00Z" },
    { "dot_number": "2345678", "custom_data": { "percentile": 0.55, "engagement_cohort_tag": "low" }, "updated_at": "2026-06-28T00:00:00Z" }
  ],
  "missing_dot_numbers": ["9999991"]
}

// Field notes
// - Records come back under the DOT number you requested; misses are listed
//   in missing_dot_numbers as requested. Duplicates are deduplicated.
// - Leading-zero requests are matched against unpadded stored records
//   automatically (stripping only, one direction).
// - No pagination object — the batch is bounded at 500.

    Safety Benchmarks

    GET/v1/peer-groups

    The peer framings accepted by the peer_group parameter on the safety benchmark endpoints. 33 lenses: the whole industry, 7 single axes (region, carrier type, fleet size, radius, equipment, cab, mileage), 21 axis pairs, and the 4 canonical scoring groups the fixed grade is computed against. Static metadata — call it once to build a lens picker.

    Response Example

    {
  "peer_groups": [
    { "group_type": "industry", "label": "Industry (all benchmarkable carriers)", "kind": "industry", "axes": [], "precomputed": true },
    { "group_type": "ax_region", "label": "Region", "kind": "axis", "axes": ["region"], "precomputed": false },
    { "group_type": "ax_region__fleet_size", "label": "Region × Fleet Size", "kind": "axis_pair", "axes": ["region", "fleet_size"], "precomputed": false },
    { "group_type": "peer_a", "label": "Carrier Type × Region", "kind": "canonical", "axes": ["carrier_type", "region"], "precomputed": true }
    // ... 33 total
  ],
  "total": 33,
  "reliable_min_n": 384
}

// Field notes
// - Pair spellings follow a fixed axis order: ax_region__fleet_size is valid,
//   ax_fleet_size__region is not.
// - reliable_min_n is the bucket-size threshold below which a peer comparison
//   is flagged low_sample (±5% at 95% confidence).
    GET/v1/carriers/{dot_number}/safety-benchmark

    A carrier's safety standing: a fixed overall score and letter grade, plus a peer comparison re-framed against whichever lens you pick. The grade never changes with the lens — it is computed once against the canonical peer model — while per-metric percentiles, boxplots, and violation over-indexes are re-placed inside the peer distribution that peer_group names. Data refreshes weekly; as_of carries the vintage.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    peer_group string No Comparison lens (default: "industry"). Any group_type from GET /v1/peer-groups.
    include string No Comma-separated subset of: overall, categories, metrics, violations, flags. Omit for all five.
    peer_key string No Advanced: compare against a specific bucket (e.g. "2-5 Trucks | Local") instead of the carrier's own.
    violations_limit number No Max violation rows returned inline (default: 25, max: 100). Use the /violations sub-resource to page through all of them.

    Response Example

    {
  "dot_number": 1234567,
  "as_of": "2026-08-11",
  "carrier": {
    "name": "EXAMPLE TRUCKING LLC",
    "profile": { "region": "South", "carrier_type": "for_hire", "fleet_size": "2-5 Trucks",
                 "radius": "Local", "equipment": "Majority Class 8", "cab": "Day Cab",
                 "mileage": "<15K mi/truck" }
  },
  "peer_group": { "group_type": "industry", "label": "Industry (all benchmarkable carriers)",
                  "peer_key": "ALL", "n": 705210, "reliable": true, "available": true },
  "overall": { "score": 81.2, "grade": "B", "peer_percentile": 74,
               "industry_percentile": 58, "data_confidence": "High" },
  "categories": {
    "Vehicle Condition": { "score": 74.1, "grade": "C", "method": "weighted" },
    "Driver Conduct":    { "score": 88.0, "grade": "B", "method": "weighted" }
  },
  "metrics": [
    { "metric": "vehicle_oos_pct", "label": "Vehicle OOS %", "units": "% of inspections",
      "carrier_value": 7.1, "percentile": 62, "direction": "lower_is_better",
      "scored": true, "percentile_source": "precomputed",
      "peer": { "n": 705210, "median": 7.14,
                "boxplot": { "min": 0, "p10": 0, "p25": 0, "p50": 7.14,
                             "p75": 33.3, "p90": 66.7, "max": 100 } } }
  ],
  "violations": [
    { "unit": "family", "unit_id": "Brakes", "family": "Brakes",
      "basic": "Vehicle Maintenance", "severity": 6, "eligible_denominator": true,
      "carrier": { "times_cited": 12, "last_cited_date": "2026-06-10", "days_since": 65,
                   "trend_direction": "worsening", "trend_slope_per_yr": 0.31,
                   "rate_per_1k": 436.9, "total_inspections": 47,
                   "q_citations": [0,2,1,3,2,1,2,1], "q_inspections": [4,6,5,8,6,7,6,5],
                   "q_inspections_eligible": [3,5,4,6,4,6,5,4] },
      "peer": { "rate_per_1k": 312.1, "rate_per_1k_eligible": 481.0, "oos_pct": 62.2,
                "group_carriers": 612, "group_inspections": 41022, "low_sample": false,
                "q_rate_per_1k": [280, 300], "q_starts": ["2024-10-01"] },
      "over_index": 0.91 }
  ],
  "violations_truncated": false,
  "flags": { "low_sample": false,
             "litigation_notes": ["outlier_metrics: Driver Violations / Inspection"],
             "data_limitations": [] }
}

// How to work with this endpoint
// 1. Call GET /v1/peer-groups once to see the 33 available lenses.
// 2. Fetch with the default industry lens; switch peer_group to re-frame the
//    comparison (the grade and score never move — only the peer side does).
// 3. Check peer_group.reliable before presenting comparisons: n < 384 means
//    the bucket is too thin to be statistically reliable. Thin buckets are
//    returned flagged (flags.low_sample), never hidden — fall back to a
//    broader lens like industry if you need a reliable frame.
// 4. Use include= to slim the payload (e.g. include=overall for scorecards).
//
// Field notes
// - Percentiles are always oriented so 100 IS BEST, regardless of whether the
//   raw metric runs high-good or low-good; direction tells you the raw
//   orientation. percentile_source is "precomputed" (the pipeline's own
//   number, used for the 5 canonical lenses so it matches the grade) or
//   "interpolated" (computed against the lens's quantile distribution).
// - over_index is carrier rate ÷ peer rate for that violation family: 1.0 is
//   at-peer, 2.0 is double the peer rate. Sorted worst-first.
// - Vehicle-condition families (Brakes, Tires, Steering & Suspension, and 9
//   more) are only citable on inspections that examined the vehicle, so their
//   rates use an eligible-inspection denominator on BOTH sides;
//   eligible_denominator tells you which pair was used. over_index is null
//   rather than ever mixing denominators.
// - peer_group.available: false means the carrier's profile is missing the
//   axis that lens needs (e.g. unknown region) — the fixed grade still
//   returns; only the comparison is omitted.
// - q_* arrays are aligned trailing quarters, oldest first.
// - 404 {"error": "no_benchmark"} means the carrier has no inspection history
//   to benchmark — not an invalid DOT.
    GET/v1/carriers/{dot_number}/safety-benchmark/violations

    The violations section of the safety benchmark on its own, paginated — for paging through a carrier's full violation-family list instead of the inline top-25. Same peer framing and row shape as the parent endpoint, sorted worst-over-index first.

    Parameters

    Name Type Required Description
    dot_number string Yes The carrier's USDOT number
    peer_group string No Comparison lens (default: "industry")
    peer_key string No Advanced: explicit peer bucket override
    limit number No Rows per page (default: 25, max: 100)
    page number No Page number (default: 1)

    Response Example

    {
  "dot_number": 1234567,
  "as_of": "2026-08-11",
  "peer_group": { "group_type": "industry", "label": "Industry (all benchmarkable carriers)",
                  "peer_key": "ALL", "n": 705210, "reliable": true, "available": true },
  "violations": [ /* same row shape as the parent endpoint */ ],
  "pagination": { "page": 1, "limit": 25, "total_results": 18, "total_pages": 1 }
}

    Error Codes

    Code Description
    200 Success
    202 Accepted — contacts are being fetched asynchronously, retry after delay
    400 Bad Request — invalid parameters
    401 Unauthorized — invalid or missing API key
    402 Payment Required — enrichment credits exhausted
    403 Forbidden — demo key restriction, or custom data not enabled for your account (not an auth failure; do not retry)
    404 Not Found — carrier does not exist
    405 Method Not Allowed — wrong HTTP method for this endpoint
    429 Rate Limited — too many requests
    500 Internal Server Error
    502 Bad Gateway — upstream service (freight API or news provider) failed
    503 Service Unavailable — custom data configuration invalid; contact support

    General Notes

    Error Response Format

    All errors return a consistent JSON shape:

    {
  "error": "Short error type",
  "message": "Human-readable description of what went wrong."
}

    CORS

    All endpoints support CORS preflight (OPTIONS → 204) with Access-Control-Allow-Origin: *. Safe to call directly from browser-based applications.

    Enrichment Credits

    The /v1/contacts/{contact_id}/enrich endpoint consumes 1 credit per new enrichment. Cached results are free. Credits remaining are returned in both the response body (credits object) and the X-Enrichment-Credits-Remaining header. When credits are exhausted, the endpoint returns HTTP 402.

    Pagination

    Most endpoints use page/limit pagination. However, trucks, trailers, inspections, and authority use offset/limit instead. Check each endpoint's parameter table for the correct style.

    Field Projection

    The ?fields= parameter is only available on the carrier profile endpoints (/v1/carriers/{dot_number} and /v1/carriers/mc/{mc_number}). It is not supported on other endpoints.

    Need API Access?

    Contact our team to get your API key and start building with FMCSA carrier data.

    Get API Access