Watchlist

The watchlist lets your account subscribe to specific carriers. After every nightly ETL, DotLookup compares the new data to the previous run and publishes diffs scoped to carriers your account watches — delivered as an email digest or, for programmatic consumers, an HMAC-signed webhook.

All watchlist endpoints require an API key. See Authentication.

List watched carriers

GET /v1/watchlist

Returns the carriers your account is currently watching.

curl https://api.dotlookup.dev/v1/watchlist \
  -H "X-API-Key: your_api_key_here"

{
  "carriers": [
    {
      "dot_number": "2233855",
      "carrier_name": "ACME TRUCKING LLC",
      "status": "ACTIVE",
      "entity_type": "CARRIER",
      "city": "Dallas",
      "state": "TX",
      "created_at": "2026-04-12T15:30:00Z"
    }
  ],
  "total": 1
}

Add carriers to the watchlist

POST /v1/watchlist

Add up to 50 DOT numbers in a single request. Adding a DOT that’s already watched is a no-op.

string[]

required

Array of USDOT numbers (max 50 per request)

curl -X POST https://api.dotlookup.dev/v1/watchlist \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"dot_numbers": ["2233855", "1234567"]}'

{
  "added": 2,
  "skipped": 0,
  "status": "ok"
}

Returns 400 LIMIT_EXCEEDED if the addition would exceed your account’s watchlist cap.

Remove a carrier

DELETE /v1/watchlist/{dot_number}

Removes a single DOT from the watchlist. Idempotent.

curl -X DELETE https://api.dotlookup.dev/v1/watchlist/2233855 \
  -H "X-API-Key: your_api_key_here"

{ "status": "removed" }

Check whether a carrier is watched

GET /v1/watchlist/check?dot_number=2233855

Lightweight check for one DOT — returns just a boolean. Useful for surfacing a “watching” toggle in a UI.

string

required

The carrier’s USDOT number. Singular — pass one DOT per request.

curl "https://api.dotlookup.dev/v1/watchlist/check?dot_number=2233855" \
  -H "X-API-Key: your_api_key_here"

{ "watching": true }

Recent changes for watched carriers

GET /v1/watchlist/changes

Returns recent diffs for carriers on your watchlist. The shape mirrors GET /v1/changes/{etl_run_id} — same category, old_values, new_values fields. Use this for catch-up after a webhook delivery failure or when wiring up a new dashboard.

This endpoint looks back 30 days, not the 52-week window used by the change feed. If your integration has been offline longer than 30 days, those changes are not available here.

string

Return only changes at or after this instant. Accepts RFC3339 (2026-05-01T00:00:00Z) or a bare date (2026-05-01), which is read as midnight UTC. Narrows within the 30-day window — it never reaches further back

string

Filter to a single change category, using the same values as the change feed

integer

default:"1"

Page number

integer

default:"25"

Results per page (max: 100)

For an incremental feed, pass the batch_ts of the newest change you have already processed as since on the next poll.

curl "https://api.dotlookup.dev/v1/watchlist/changes?since=2026-05-01" \
  -H "X-API-Key: your_api_key_here"

Carriers

Change Feed

Account

System

Watchlist

List watched carriers

Add carriers to the watchlist

Remove a carrier

Check whether a carrier is watched

Recent changes for watched carriers

​List watched carriers

​Add carriers to the watchlist

​Remove a carrier

​Check whether a carrier is watched

​Recent changes for watched carriers

List watched carriers

Add carriers to the watchlist

Remove a carrier

Check whether a carrier is watched

Recent changes for watched carriers