API Documentation | CarrierMetric

Introduction

The CarrierMetric API provides programmatic access to the same carrier intelligence data available in the web application. Each request returns a structured JSON payload for a single DOT record including identity, safety metrics, compliance data, insurance, and risk scores.

The API is versioned at /api/v1. The current stable version is v1. We will maintain backwards compatibility within this major version.

Base URL

https://carriermetric.com

Authentication

All API requests must be authenticated using your personal API key, passed as a Bearer token in the Authorization header.

Header format

Authorization: Bearer cm_live_YOUR_API_KEY

ℹ️

API keys are shown only once When you generate your key from Account Settings, the raw key is displayed exactly once. Copy and store it securely — you will not be able to retrieve it again. You can always rotate to issue a new key.

Managing Your Key

Generate, rotate, and revoke your API key from Account Settings → API Access.

Eligibility

API access is available on Trial and Ultimate (Scale) subscriptions with an active status. API keys from users who lose eligibility (canceled, expired, or downgraded subscriptions) will stop working immediately at the next request — eligibility is checked live on every call, not only at key creation time.

✅ Trial subscription (active)
✅ Ultimate / Scale subscription (active)
❌ Core, Growth, or any inactive subscription
❌ Expired, canceled, or past-due accounts

Endpoints

GET /api/v1/dot/{dotNumber}

Query a single DOT carrier record and receive structured JSON data including identity, safety, compliance, insurance, and risk scores.

Path Parameters

Parameter	Type	Description
`dotNumber`	string	USDOT number (4–9 digits)

Request & Response

Example Request

curl

curl -s -X GET "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY"

Pretty Printing with `jq`

Pipe any response through jq for formatted, color-coded output. The -s flag suppresses the progress meter for clean output.

Full response — pretty printed

curl -s "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY" | jq .

Risk scores only

curl -s "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY" | jq '.data.risk'

Compliance violations breakdown

curl -s "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY" | jq '.data.compliance'

Fleet summary (make, year, type)

curl -s "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY" | jq '.data.fleet[] | {make, year, type}'

Insurance signals

curl -s "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY" \
  | jq '.data.insurance | {stability_rating, bipd_on_file, cancellation_events_36mo, total_gap_days}'

Save full response to file

curl -s "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY" | jq . > dot_1234567.json

Example Response

JSON Response — 200 OK

{
  "success": true,
  "dot_number": "1234567",
  "requested_at": "2026-03-16T21:00:00Z",
  "data": {
    "identity": {
      "legal_name": "ABC TRUCKING INC",
      "dba_name": null,
      "dot_number": "1234567",
      "mc_number": "MC-987654",
      "entity_type": "CARRIER",
      "physical_city": "CHICAGO",
      "physical_state": "IL",
      "physical_zip": "60601",
      "power_units": 12,
      "drivers": 15,
      "auth_status": "Active",
      "operation_classification": "Interstate"
    },
    "safety": {
      "total_crashes_36mo": 2,
      "total_inspections_36mo": 18,
      "vehicle_oos_rate_pct": 11.1,
      "driver_oos_rate_pct": 5.6
    },
    "compliance": {
      "total_violations_36mo": 24,
      "out_of_service_order_count": 1
    },
    "insurance": {
      "active_policy_count": 2,
      "insurance_companies": ["Progressive", "Great West"]
    },
    "risk": {
      "composite_score": 68,
      "composite_label": "Medium",
      "safety_score": 72,
      "compliance_score": 61,
      "financial_score": 75
    }
  }
}

Error Codes

HTTP Status	error field	Meaning
400	`invalid_dot_number`	DOT number format invalid (must be 4–9 digits)
401	`missing_auth`	No Authorization header provided
401	`invalid_api_key`	Key is invalid, revoked, or does not exist
403	`subscription_required`	Account subscription is not active or not eligible
404	`not_found`	No FMCSA record found for this DOT number
429	`rate_limited`	Rate limit exceeded — see `Retry-After` header
500	`server_error`	Unexpected server error

Error Response Shape

Error JSON

{
  "success": false,
  "error": "subscription_required",
  "message": "API access requires an active Trial or Ultimate subscription"
}

Rate Limits

60 requests per minute · 500 requests per day · 10 requests per second burst

When a rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Every successful response includes rate limit headers:

Response Headers

X-RateLimit-Remaining: 42

If you anticipate needing higher limits, contact support@carriermetric.com.

Security Best Practices

Never commit your API key to source code or version control. Use environment variables or a secrets manager.
Never share your API key with any third party or expose it in client-side JavaScript.
Rotate your key immediately if you suspect it has been compromised. Old keys are invalidated instantly on rotation.
Use HTTPS only. The API does not respond to HTTP requests in production.
Revoke keys you no longer use — unused keys are still active until explicitly revoked.
Monitor your usage from Account Settings. Unexpected usage spikes may indicate key exposure.

🔒

Your API key is hashed on our servers. CarrierMetric does not store your raw API key. We store only a one-way hash. This means we also cannot recover your key — rotating it is the only way to regain access if you lose it.

curl Examples

Query a DOT record

bash

curl -X GET "https://carriermetric.com/api/v1/dot/1234567" \
  -H "Authorization: Bearer cm_live_YOUR_API_KEY"

With jq for pretty output