carrierscore

Look up an FMCSA-registered motor carrier's identity by US DOT number: legal name, DBA, operating status, FMCSA safety rating, fleet size (power units, drivers), physical address, and registration dates.

Use this first when a booking/dispatch agent needs to confirm WHO a carrier is — that a DOT number is real, active, and matches the company name on a rate confirmation. It does not return a risk score (use carrier_score for that).

Returns JSON: { dot_number, legal_name, dba_name, status_code, safety_rating, power_units, total_drivers, phy_street, phy_city, phy_state, phy_zip, add_date, mcs150_date }.

Errors: 404 if the DOT is not in the FMCSA census (likely a typo or a fraudulent/never-registered carrier — treat as a red flag for booking).

Get the CarrierScore risk score (0-100, HIGHER = RISKIER) for a carrier by US DOT number, with a full component breakdown.

This is the core "is this carrier safe to book?" signal for AI booking agents. The score is population-relative and built from public FMCSA data: out-of-service rates, violation trends (acute vs chronic), exposure-normalized crash rates, insurance churn, and operation age. Hard flags (active out-of-service order, no active insurance, high-confidence reincarnated-carrier link) add explicit surcharges — a carrier with any flag deserves extra scrutiny regardless of score.

Returns JSON: { dot_number, legal_name, carrier_score, base_score, surcharge, components: { : { label, value, percentile, weight } }, flags: string[], data_sufficiency (0-1, how much of the score rests on observed vs neutral-imputed data), scored_as_of, disclaimer }.

Interpreting for booking decisions: treat the score as documented decision-support evidence, not an approve/deny verdict. Low data_sufficiency means limited inspection history — common for new carriers, itself a risk signal. Always relay the disclaimer when presenting the score.

Errors: 404 if the DOT is not in the scored population; 503 if scores have not been computed yet.

Retrieve the alert history for a saved carrier list (see save_carrier_list), newest first. Requires the same paid API key that saved the list.

Each alert records one change detected between consecutive daily scoring runs for one carrier: type (oos_order_activated, authority_lost, insurance_lapsed, status_changed, score_jump, reincarnation_link), severity (critical / high / medium), the field that changed with its before/after values, the DOT and legal name, and the scoring dates compared. Use it to answer "did anything change on my carrier list?" — critical alerts (new OOS order, authority lost) mean the carrier should not be dispatched until verified; follow up with carrier_score or montgomery_file for the full picture.

Args:

• list_id: the lst_... id returned by save_carrier_list

• since (optional): YYYY-MM-DD; only alerts from scoring runs on/after this date

Returns JSON: { list_id, since, count, alerts: [{ ts, as_of, prev_as_of, list_id, list_name, dot, legal_name, type, severity, field, before, after }] }. An empty alerts array means no monitored change since the given date (alerts only exist once two daily scoring runs have happened).

Errors: 403 without a paid key; 404 if the list id is unknown for this key; 400 if since is not YYYY-MM-DD.

Batch risk check for a list of carriers by US DOT number (max 100 per call): score summary and hard flags for each.

Use when an agent is screening multiple candidate carriers for a load, or re-checking a broker's active carrier roster ("did any of my carriers pick up an out-of-service order or drop insurance?"). For a full breakdown of any single carrier that looks risky here, follow up with carrier_score or montgomery_file.

Args:

• dot_numbers: array of DOT number strings, 1-100 entries

Returns JSON: { scored_as_of, requested, found, carriers: [{ dot_number, legal_name, carrier_score (0-100, higher = riskier), data_sufficiency, flags: string[] }], not_found: string[], disclaimer }. DOTs in not_found are absent from the scored population — verify them with carrier_lookup; an unknown DOT on your roster is itself a red flag.

Errors: 400 if the list is empty or exceeds 100 (split into batches); 503 if scores are not computed yet.

Generate a timestamped Montgomery file — a carrier-selection evidence report — for a carrier by US DOT number.

Since Montgomery v. Caribe Transport II (SCOTUS, May 2026), freight brokers are exposed to state-law negligent-selection claims and need documented, timestamped, safety-data-based carrier selection. This report is that artifact: score, component percentiles, hard flags, FMCSA safety rating, and the methodology disclaimer, dated as of the scoring run. A booking agent should generate and retain this file at the moment a carrier is selected for a load.

Args:

• dot_number: US DOT number, digits only

• format: "text" (default; the filing-ready plain-text report, available on the free tier) or "json" (structured fields; requires an API key on the monitor or compliance tier)

Returns: format="text" gives the plain-text report (structured field report_text); format="json" gives structured fields { report, generated, dot_number, legal_name, dba_name, safety_rating, status_code, power_units, carrier_score, components, flags, data_sufficiency, scored_as_of, disclaimer }. Every report embeds the disclaimer verbatim — keep it when storing or quoting the report.

Errors: 403 if format=json without an API key; 404 unknown DOT; 503 if scores are not computed yet.

Save a named list of carriers (by US DOT number) for continuous monitoring. Requires a paid API key (CARRIERSCORE_API_KEY on the Monitor or Compliance tier) — the free tier gets a 403 with an upgrade link.

Once saved, CarrierScore diffs every carrier on the list against the previous day's scoring run after each daily run and records alerts: new out-of-service order (critical), operating authority lost (critical), insurance filing lapsed (high), operating status leaving Active (high), risk score up 10+ points (medium), high-confidence reincarnated-carrier link appearing (medium). Alerts are always retrievable with list_alerts; optionally they are also pushed to a webhook (JSON POST, HMAC-signed via the X-CarrierScore-Signature header with the per-key secret from GET /v1/lists) and/or summarized in one daily digest email.

Use this when a broker asks to "watch" or "keep an eye on" their carrier roster. Caps: 500 DOTs total across all lists on the Monitor tier, 5000 on Compliance; up to 50 lists per key. Saving the same DOT twice in one list is deduped.

Args:

• name: short label for the list (1-100 chars)

• dot_numbers: array of DOT number strings (1-8 digits each)

• webhook_url (optional): https URL to POST new alerts to

• email (optional): address for the daily digest

Returns JSON: { list_id, name, dots, created, updated, webhook_url?, email? }. Keep list_id — list_alerts needs it.

Errors: 403 without a paid key; 400 on invalid DOTs, empty list, or exceeding the tier cap (message says which); 401 bad key.