Skip to main content
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 TypeSeverityDescription
authority_revokedcriticalOperating authority revoked by FMCSA
authority_suspendedcriticalOperating authority suspended
safety_rating_downgradehighSafety rating changed to Conditional or Unsatisfactory
insurance_lapsehighActive insurance on file no longer shows as current
csa_basic_alertmediumOne or more CSA BASIC percentile scores crossed the intervention threshold
oos_rate_spikemediumOut-of-service rate increased by ≥ 5 percentage points since last check
crash_increasemediumCrash indicator score increased materially
chameleon_detectedcriticalCarrier obtained a new USDOT number to circumvent poor safety record

​
API Endpoints

​
List Alerts

GET /v1/carrier-alerts
Authorization: Bearer <token>
Query parameters:
ParameterTypeDescription
orgIdstringFilter to a specific organization
carrierIdstringFilter to a specific carrier
alertTypestringFilter by alert type (e.g. authority_revoked)
severitystringFilter by severity (critical, high, medium)
statusstringopen (default) or acknowledged
limitnumberPage size (default 50, max 200)
cursorstringPagination 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

FilePurpose
apps/api/src/cron/fmcsa-monitor.tsDaily cron entry point — iterates carriers, calls diff
apps/api/src/lib/fmcsa-diff.tsDiff logic — compares FMCSA snapshots, builds alert payloads
apps/api/src/routes/carrier-alerts.tsHono route handlers for all four endpoints