FreightGuard

01 · Quickstart

Make your first request

Send your API key in the X-API-Key header. The search endpoint accepts filters for entity type, geography, fleet size, safety, contacts and federal awards.

bash

curl "https://getfreightguard.com/api/data/search?q=145%20Marston%20Street%20Inc&limit=5" \
  -H "X-API-Key: fg_live_your_api_key"

json

{
  "results": [{
    "dotNumber": "339731",
    "mcNumber": "157050",
    "legalName": "145 Marston Street Inc",
    "entityType": "carrier",
    "status": "active",
    "address": { "city": "Lawrence", "state": "MA" },
    "fleet": { "powerUnits": 21, "totalDrivers": 18 }
  }],
  "pagination": {
    "page": 1, "limit": 5, "total": 1,
    "pages": 1, "hasMore": false
  }
}

02 · Authentication

Use X-API-Key on every data request

Keys begin with fg_live_ in production. Keep the key server-side; never place it in public browser code or commit it to source control.

Key security

FreightGuard stores only a SHA-256 hash of your key. Rotating it invalidates the old key immediately, and the replacement is shown once.

http

X-API-Key: fg_live_your_api_key

03 · Search

GET /api/data/search

Returns active carriers and brokers with normalized identity, contact, fleet, authority, safety and contract fields.

Parameter	Type	Description
`q`	string	Company, DBA, city, DOT or MC search
`type`	enum	carrier, broker or all
`state`	string	Two-letter US state code
`city`	string	Case-insensitive city match
`minUnits / maxUnits`	integer	Power-unit range
`safety`	enum	S, C or U safety rating
`hasEmail / hasPhone`	boolean	Require contact fields
`hasContract`	boolean	Require federal awards
`page / limit`	integer	Pagination; limit max is 100
`sort / order`	enum	name, powerUnits, state, safety; asc or desc

04 · Entity lookup

GET /api/data/dot/:dotNumber

Returns one USDOT record. Developer Preview redacts phone, email and award details; paid plans return the complete core record.

bash

curl "https://getfreightguard.com/api/data/dot/339731" \
  -H "X-API-Key: fg_live_your_api_key"

05 · Carrier Alerts

Monitor a portfolio for real data changes

Carrier Alerts save a baseline when a USDOT number is added, then compare future normalized FMCSA, SMS and OSHA snapshots. Adding a carrier never generates a synthetic alert. Paid plans differ by watchlist size and external delivery channels.

bash

curl -X POST "https://getfreightguard.com/api/alerts/watches" \
  -H "X-API-Key: fg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"dotNumber":"339731"}'

bash

curl "https://getfreightguard.com/api/alerts/events?unread=true&severity=critical" \
  -H "X-API-Key: fg_live_your_api_key"

Method	Endpoint	Description
`GET`	`/api/alerts/summary`	Watchlist usage, unread counts and channel availability
`GET`	`/api/alerts/watches`	List monitored carriers
`POST`	`/api/alerts/watches`	Add one USDOT carrier and save its baseline
`DELETE`	`/api/alerts/watches/:dotNumber`	Stop monitoring while preserving history
`GET`	`/api/alerts/events`	List detected changes; filter by unread and severity
`POST`	`/api/alerts/check`	Request a rate-limited immediate comparison
`GET / PUT`	`/api/alerts/channels`	Read or update email, Slack and Telegram settings

Decision support, not a verdict

An alert reports a field change in a source snapshot. Verify critical decisions with the relevant regulator and your own risk policy.

06 · Enrichment datasets

Additional endpoints

GET /api/data/stats/summary

Aggregate freight market counts, states, cargo and safety distribution

GET /api/data/states/:state

Paginated entities for one US state

GET /api/data/crashes

FreightGuard Pro/FreightGuard Enterprise: NHTSA FARS crashes filtered by state and year

GET /api/data/epa

FreightGuard Pro/FreightGuard Enterprise: EPA ECHO facilities filtered by state, city and name

GET /api/data/fuel-prices

FreightGuard Pro/FreightGuard Enterprise: weekly EIA diesel and gasoline prices

GET /api/data/export/csv

Paid-plan CSV export with search-compatible filters

07 · Errors and limits

Predictable HTTP responses

Status	Meaning	Action
`400`	Invalid parameter	Correct the request
`401`	Invalid API key	Check or rotate the key
`403`	Paid feature required	Upgrade the plan
`404`	Entity not found	Verify the DOT number
`429`	Daily limit reached	Wait for reset or upgrade
`500`	Server error	Retry with backoff

Rate-limit headers

Every response includes RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 response also includes Retry-After.

Build freight intelligence into any workflow.

Make your first request

Use X-API-Key on every data request

GET /api/data/search

GET /api/data/dot/:dotNumber

Monitor a portfolio for real data changes

Additional endpoints

Predictable HTTP responses