Carrier Monitoring API

Add carriers to a watchlist and receive real-time alerts on authority, insurance, safety, fleet, contact, and risk factor changes. Filter and paginate monitored carriers by change type and date range.

POST/v2/monitoring/add

POST/v2/monitoring/remove

GET/v2/monitoring/list

POST

Add carriers to monitoring

Add carrier profiles to the monitoring watchlist. Each unique monitored DOT is billed once per calendar month; removing mid-month does not refund, and re-adding the same DOT within the month is free (idempotent). A single request can carry your whole network — profiles are committed in chunks (200 once committed, 207 if some chunks failed).

Authorization — API Key

Request Body

Parameter	Type	Description
`profile_ids`required	string[]	Array of carrier profile IDs to monitor, formatted {dot}-{docket} (e.g. 568253-MC277621).

Example

curl -X POST "https://api.carrierok.com/v2/monitoring/add" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_ids":["568253-MC277621"]}'

Response200 OK

{
  "status": "Profiles added or updated successfully",
  "added": 3
}

Response Fields

Field	Type	Description
`status`	string	Human-readable status ('Profiles added or updated successfully'; a partial commit returns 207).
`added`	integer	Number of profiles committed to the watchlist.
`error`	string	Present only on a 207 partial commit — retry the remainder.

POST

Remove carriers from monitoring

Remove carrier profiles from the monitoring watchlist. Removal is free and does not refund the current month's billing — un-monitoring simply stops future months from billing that DOT.

Authorization — API Key

Request Body

Parameter	Type	Description
`profile_ids`required	string[]	Array of carrier profile IDs to remove, formatted {dot}-{docket} (e.g. 568253-MC277621).

Example

curl -X POST "https://api.carrierok.com/v2/monitoring/remove" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_ids":["568253-MC277621"]}'

Response200 OK

{
  "status": "Profiles removed successfully",
  "removed": 2
}

Response Fields

Field	Type	Description
`status`	string	Human-readable status ('Profiles removed successfully'; a partial commit returns 207).
`removed`	integer	Number of profiles removed from the watchlist.
`error`	string	Present only on a 207 partial commit — retry the remainder.

GET

List monitored carriers with change tracking

Returns a paginated list of monitored carriers with optional filtering by change type (insurance, authority, safety, fleet, contact, risk), date range, and sort order. Supports granular change visibility flags.

Authorization — API Key

Parameters

Parameter	Type	Description
`page`	integer= 1	Page number
`pageSize`	integer= 100	Results per page (clamped to 500 max)
`view_changes`	boolean	Filter to profiles with any changes
`view_changes_insurance`	boolean	Filter to insurance changes
`view_changes_authority`	boolean	Filter to authority changes
`view_changes_safety`	boolean	Filter to safety changes
`view_changes_fleet`	boolean	Filter to fleet changes
`view_changes_contact`	boolean	Filter to contact changes
`view_changes_risk`	boolean	Filter to risk factor changes
`date_type`	string	Date field to filter: last_changed_date, started_monitoring_at, last_acknowledged_at, mcs150_date_current, safety_rating_date_current, last_crash_date_current, insurance_pending_cancel_date_current
`date_min`	string	Minimum date (YYYYMMDD format)
`date_max`	string	Maximum date (YYYYMMDD format)
`sortBy`	string= last_changed_date	Sort field
`sortOrder`	string= desc	Sort direction: asc or desc
`profile_id`	string	Filter to a single profile

Example

curl "https://api.carrierok.com/v2/monitoring/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200 OK

{
  "total_count": 1,
  "items": {
    "568253-MC277621": [
      {
        "safety_rating_desc_current": "Satisfactory",
        "safety_rating_desc_prior": "Conditional",
        "safety_rating_desc_changed": true,
        "insurance_bipd_on_file_current": 1000000,
        "insurance_bipd_on_file_prior": 750000,
        "insurance_bipd_on_file_changed": true
      }
    ]
  }
}

Response Fields

Field	Type	Description
`total_count`	integer	Total monitored profiles matching the filters.
`items`	object	Changed profiles keyed by profile_id. Each value is an array of the fields that changed since you last acknowledged them — each as a {field}_current / {field}_prior / {field}_changed triple. External (developer-portal) keys receive change events only.

← Getting Started Authentication →