Identity Graph API & webhooks

Run link analysis inside your TMS or onboarding flow, keep a watchlist of the carriers you use, and get signed webhooks when their FMCSA details change.

Authentication

Every broker plan gets an access key (starts with fdw_) when the plan starts. Send it in the X-API-Key header. The same key signs you in on the identity page for full reports and the watchlist. Keep it server-side.

curl -H "X-API-Key: $FDW_KEY" "https://freightdatawatch.com/api/v1/identity/report?dot=53467"

Endpoints

Base URL https://freightdatawatch.com/api/v1/identity. All responses are JSON.

GET/report?dot=53467billable check

Full identity report: every linked carrier (active and inactive), unmasked identifiers, full change history, review level and items. Also accepts ?q= with an MC number, name, phone or email; several matches return 300 with a list.

GET/search?q=…

Find carriers by USDOT, MC, company or officer name, phone, email or @domain.

GET/watchlist

Carriers you watch, with alert counts.

POST/watchlist

Add carriers: {"dot": 53467} or {"dots": [53467, 1234567], "label": "Q4 onboarding"}. Up to 1,000 per call.

DELETE/watchlist?dot=53467

Stop watching a carrier.

GET/alerts?since=2026-10-01&limit=100

Change alerts on watched carriers, newest first. Use this to poll if you do not want webhooks.

PUT/webhook

Set {"url": "https://…"} and/or {"emailAlerts": false}. Sends a signed test event; returns the signing secret the first time (or with "rotateSecret": true).

GET/usage

Billable checks this month, quota, watchlist size and delivery settings.

Only report calls are billed. A billable check is one carrier per calendar day (UTC), so reopening the same report that day is free. Search, watchlist, alerts and usage calls are not billed.

Errors & limits

401	Missing, wrong or disabled key.
402	Monthly check quota or watchlist limit reached.
404	No carrier for that USDOT.
429	More than 120 requests per minute on one key.
502	The FMCSA source did not answer in time; retry shortly.

Change alerts

Every night after the FMCSA sync, new changes on watched carriers become alerts: new registrations, phone/email, address, officer, name, fleet-size and USDOT status changes, authority actions, insurance cancellations and suspension notices. Only changes detected after you add a carrier are sent. Each key can receive them as an email digest, a webhook, or by polling /alerts.

POST https://your-server.example.com/fdw-webhook
X-FDW-Timestamp: 1792137600
X-FDW-Signature: sha256=5f2c…

{
  "event": "carrier.changes",
  "sentAt": "2026-10-17T07:42:10.000Z",
  "alerts": [{
    "id": "al…", "dot": 1234567, "docket": "MC987654", "carrier": "EXAMPLE FREIGHT LLC",
    "kind": "contact_change", "label": "Phone / email change", "field": "phone",
    "oldValue": "(312) 555-0100", "newValue": "(786) 555-0199",
    "eventDate": null, "detectedAt": "2026-10-17T07:41:55.000Z"
  }]
}

Verify the signature before trusting the payload: HMAC-SHA256 of `${timestamp}.${rawBody}` with your signing secret. Reply with any 2xx status; failed deliveries are retried on the next nightly run, up to 5 times.

import crypto from 'crypto'

function verify(rawBody, timestamp, signature, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex')
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 600
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Good to know

Data comes from FMCSA public records. Change history starts October 16, 2026. Links and alerts show shared or changed public-record details for review; they are not evidence of fraud or wrongdoing. Public records have no VINs, so equipment is not matched.

Need a key? Request broker access.