Carrier Alerts

The carrier alert system monitors FMCSA data for all active carriers and surfaces material safety or compliance changes to underwriters. A daily cron job diffs current FMCSA data against stored snapshots, inserts alerts into the carrier_alerts table, and makes them visible in the Underwriting Workbench.

How It Works

Daily Cron (00:00 UTC)
        │
        ▼
For each carrier with a DOT number:
  ├── GET /carriers/:dot       → authority & insurance status
  ├── GET /carriers/:dot/basics → CSA BASIC percentile scores
  └── GET /carriers/:dot/oos    → out-of-service rates
        │
        ▼
fmcsa-diff.ts compares current vs. last snapshot
        │
        ├── No material change → skip
        │
        └── Material change detected
                │
                ▼
        Insert row into carrier_alerts
        Emit carrier_alert_created event

The diff logic lives in apps/api/src/lib/fmcsa-diff.ts. It compares authority status codes, insurance status, CSA BASIC percentile scores (triggering on changes ≥ 10 points), and out-of-service rates (triggering on changes ≥ 5 percentage points).

caution

A chameleon_detected alert is treated as a critical compliance event. It indicates that a carrier has obtained a new USDOT number to escape a poor safety record — a known fraud pattern. These alerts bypass normal acknowledgment workflow and are escalated immediately to the compliance queue.

Alert Types

Alert Type	Severity	Description
authority_revoked	critical	Operating authority revoked by FMCSA
authority_suspended	critical	Operating authority suspended
safety_rating_downgrade	high	Safety rating changed to Conditional or Unsatisfactory
insurance_lapse	high	Active insurance on file no longer shows as current
csa_basic_alert	medium	One or more CSA BASIC percentile scores crossed the intervention threshold
oos_rate_spike	medium	Out-of-service rate increased by ≥ 5 percentage points since last check
crash_increase	medium	Crash indicator score increased materially
chameleon_detected	critical	Carrier obtained a new USDOT number to circumvent poor safety record

API Endpoints

List Alerts

GET /v1/carrier-alerts
Authorization: Bearer <token>

Query parameters:

Parameter	Type	Description
orgId	string	Filter to a specific organization
carrierId	string	Filter to a specific carrier
alertType	string	Filter by alert type (e.g. authority_revoked)
severity	string	Filter by severity (critical, high, medium)
status	string	open (default) or acknowledged
limit	number	Page size (default 50, max 200)
cursor	string	Pagination cursor from previous response

Response:

{
  "data": [
    {
      "id": "cal_01J8...",
      "carrierId": "car_01J8...",
      "dotNumber": "1234567",
      "carrierName": "Apex Freight LLC",
      "alertType": "csa_basic_alert",
      "severity": "medium",
      "status": "open",
      "detail": {
        "basic": "HOS_COMPLIANCE",
        "previousScore": 62,
        "currentScore": 78,
        "interventionThreshold": 65
      },
      "createdAt": "2026-03-24T00:14:22Z",
      "acknowledgedAt": null,
      "acknowledgedBy": null
    }
  ],
  "nextCursor": "eyJpZCI6ImNhbF8wMUo4Li4uIn0="
}

Alert Count

Returns a summary count grouped by severity, useful for dashboard badges.

GET /v1/carrier-alerts/count
Authorization: Bearer <token>

Response:

{
  "open": {
    "critical": 2,
    "high": 5,
    "medium": 12,
    "total": 19
  },
  "acknowledgedToday": 4
}

Acknowledge a Single Alert

PATCH /v1/carrier-alerts/:id/acknowledge
Authorization: Bearer <underwriter_token>
Content-Type: application/json

{
  "note": "Verified with carrier — insurance lapse was a billing error, reinstated same day."
}

Response: the updated alert record with status: "acknowledged", acknowledgedAt, and acknowledgedBy populated.

Bulk Acknowledge

PATCH /v1/carrier-alerts/bulk-acknowledge
Authorization: Bearer <underwriter_token>
Content-Type: application/json

{
  "ids": ["cal_01J8...", "cal_01J9..."],
  "note": "Reviewed in weekly carrier audit — no policy action required."
}

Returns:

{ "acknowledged": 2, "failed": 0 }

note

Acknowledgment is not the same as resolution. Acknowledged alerts remain in the audit log indefinitely. If the same alert condition recurs on a subsequent cron run, a new alert row is inserted rather than reopening the acknowledged one.

Authorization

All carrier alert endpoints require one of: underwriter, org_admin, compliance_officer, or superadmin role. Acknowledgment operations additionally require that the actor's organization matches the alert's orgId (or superadmin for cross-org access).

UW Workbench — CarrierAlertsPanel

The CarrierAlertsPanel component is embedded inline within the FMCSAPanel in the Underwriting Workbench. It renders the most recent open alerts for the carrier under review, grouped by severity, with inline acknowledgment controls.

The panel polls GET /v1/carrier-alerts?carrierId=...&status=open using TanStack Query with a 60-second refetchInterval. Acknowledging an alert from the panel calls the single-acknowledge endpoint and invalidates the query.

Key Files

File	Purpose
apps/api/src/cron/fmcsa-monitor.ts	Daily cron entry point — iterates carriers, calls diff
apps/api/src/lib/fmcsa-diff.ts	Diff logic — compares FMCSA snapshots, builds alert payloads
apps/api/src/routes/carrier-alerts.ts	Hono route handlers for all four endpoints