Workflow examples

Beta: CarrierVet is in active testing. Verify critical decisions against FMCSA SAFER, and report anything that looks wrong to hello@carriervet.dev.

Two common ways to put CarrierVet in the loop. In both, CarrierVet supplies explainable evidence (verdict, reasons, risk signals, a saved receipt) and a person or your own rules make the decision.

1. TMS or backend: check before tender, monitor on booking

1. Before tender: call POST /v1/eligibility with your load rules. eligible → tender; needs_review or ineligible → hold the load and show the failed rules to a person.
2. On booking: add the carrier to your watchlist (POST /v1/monitors, paid plans) so changes to authority, insurance or out-of-service status reach you by email or signed webhook.
3. Keep the receipt: every lookup returns receipt_id; GET /v1/receipts/{id} returns exactly what CarrierVet said at the time.

JavaScript (Node 18+)

// Before tender: your rules, CarrierVet's evidence. One lookup.
const res = await fetch("https://carriervet.dev/v1/eligibility", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.CARRIERVET_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({ mc: load.carrierMc, rules: { min_bipd_usd: 1000000, max_risk_score: 40, min_authority_age_days: 180 } }),
});
const r = await res.json();
if (r.eligibility === "eligible") await tender(load);
else await holdForReview(load, { outcome: r.eligibility, failed: r.failed_rules, verdict: r.verdict, receipt: r.receipt_id });

// On booking: watch the carrier for changes (paid plans; webhooks are HMAC-signed).
await fetch("https://carriervet.dev/v1/monitors", { method: "POST", headers: { authorization: `Bearer ${process.env.CARRIERVET_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({ dot_number: r.dot_number, webhook_url: "https://tms.example.com/hooks/carriervet" }) });

Python

import os, requests

KEY = os.environ["CARRIERVET_KEY"]
r = requests.post("https://carriervet.dev/v1/eligibility",
    headers={"authorization": f"Bearer {KEY}"},
    json={"dot": "53467", "rules": {"min_bipd_usd": 1_000_000, "require_cargo": False, "block_reason_codes": ["out_of_service"]}},
    timeout=15).json()
print(r["eligibility"], r["verdict"], r["failed_rules"])
for rule in r["rules"]:
    print(("ok  " if rule["passed"] else "FAIL"), rule["rule"], "-", rule["detail"])

Webhook signature check

# Verify a CarrierVet webhook (header x-carriervet-signature: t=<unix>,v1=<hex>)
import hmac, hashlib
def valid(body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"])

2. AI assistant: check the carrier, escalate REVIEW and FAIL

Connect the MCP server at https://carriervet.dev/mcp (see MCP setup). The assistant calls check_load_eligibility (or lookup_carrier), answers on PASS/eligible, and hands REVIEW/FAIL to a human with the reasons. This also works for dispatchers who use an AI assistant instead of code.

User: Can we give the Dallas load to MC 123456?

Assistant → check_load_eligibility {"mc": "MC123456", "rules": {"min_bipd_usd": 1000000}}
CarrierVet ← {"eligibility": "needs_review", "verdict": "REVIEW",
              "verdict_reasons": [{"code": "authority_under_90_days", ...}],
              "failed_rules": ["follow_verdict"], "receipt_id": "rcpt_…"}

Assistant: Not automatically. CarrierVet returned REVIEW: the carrier's authority is under 90 days old.
Insurance and out-of-service checks passed. I've flagged this for a dispatcher to confirm
with the carrier before booking. (Evidence: receipt rcpt_…)

Suggested instruction for the assistant: “Use CarrierVet before recommending a carrier. If eligibility is not eligible or the verdict is not PASS, don't book; explain the reasons and ask a person to decide. Mention that CarrierVet is in beta.”

Eligibility rules

One eligibility check counts as one lookup, on every plan including free. It never changes CarrierVet's verdict, which is returned alongside.

Get a free API key 50 lookups a month, no card. Paid plans open after the beta.

Not a consumer report. Carrier data is derived from records maintained by the Federal Motor Carrier Safety Administration (FMCSA). It is provided as-is, may be delayed or incomplete, and is not a consumer report under the Fair Credit Reporting Act. Do not use it to evaluate a natural person for credit, insurance, employment, or any other purpose covered by the FCRA. Questions: hello@carriervet.dev.