Skip to content
FIRMSapi Docs

Watchlists

Enterprise. Your watchlist is the set of codes you want to hear about when they change; webhooks fire for watched codes.

Request
GET /v1/watchlists List watched codes, with a summary of each facility
PUT /v1/watchlists/{code} Watch a code. Idempotent: watching it again keeps the original created_at. 404 if the code is not on the FIRMS list (deleted codes are fine).
GET /v1/watchlists/{code} One watched code. 404 if you are not watching it.
DELETE /v1/watchlists/{code} Stop watching. Idempotent: removed is false if you were not watching it.
Terminal window
curl -X PUT https://api.firmsapi.com/v1/watchlists/E430 -H "x-api-key: $FIRMSAPI_KEY"
{
  "data": {
    "code": "E430",
    "created_at": "2026-10-23T12:00:00Z",
    "facility": { "code": "E430", "name": "MAHER TERMINAL", "status": "active", "type": { "code": "03", "label": "Pier or terminal" }, "city": "Elizabeth", "state": "NJ", "port": "4601" }
  },
  "meta": { "...": "..." }
}

Adding and removing codes (PUT and DELETE) does not count toward your monthly calls; reading the watchlist (GET) counts as one call per request. With a test key the watchlist is a fixed sample and changes are not saved.