API reference

Base URL: https://carriervet.dev. Send Authorization: Bearer cv_live_... on every /v1 route except signup, login, and the Stripe webhook.

Disclaimer. Carrier data is compiled from FMCSA public records. It is provided as-is, may be delayed or incomplete, and is not a consumer report under the Fair Credit Reporting Act. Do not use it to evaluate a natural person for credit, insurance, employment, or any other purpose covered by the FCRA.

POST/v1/signup

Create a free account. Returns the API key once.

curl -s -X POST https://carriervet.dev/v1/signup \
  -H 'content-type: application/json' \
  -d '{"email":"desk@example.com","password":"a-long-password"}'

POST/v1/login

Mint another key from email and password. The previous key cannot be retrieved; only its hash is stored.

curl -s -X POST https://carriervet.dev/v1/login \
  -H 'content-type: application/json' \
  -d '{"email":"broker@example.com","password":"local-demo-password"}'

GET/v1/account

Account, plan, webhook signing secret, and key prefixes.

curl -s https://carriervet.dev/v1/account -H "authorization: Bearer $KEY"

POST/v1/keys

Create a named key. The secret is returned once. Maximum 10 active keys.

curl -s -X POST https://carriervet.dev/v1/keys \
  -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"name":"tms-prod"}'

POST/v1/keys/{id}/rotate

Revoke the named key and return a replacement.

curl -s -X POST https://carriervet.dev/v1/keys/key_demo_business/rotate -H "authorization: Bearer $KEY"

DELETE/v1/keys/{id}

Revoke a key. The last active key cannot be revoked.

curl -s -X DELETE https://carriervet.dev/v1/keys/key_demo_business -H "authorization: Bearer $KEY"

GET/v1/carriers/{dot}

Full profile. Counts as one lookup, including a not-found response.

curl -s https://carriervet.dev/v1/carriers/9900001 -H "authorization: Bearer $KEY"

GET/v1/carriers/mc/{mc}

Profile by MC, FF, or MX number. Authority status is the matched docket.

curl -s https://carriervet.dev/v1/carriers/mc/MC9900001 -H "authorization: Bearer $KEY"

GET/v1/carriers/{dot}/risk

Score from 0 to 100 plus reason codes. Weights live in the risk config.

curl -s https://carriervet.dev/v1/carriers/9900003/risk -H "authorization: Bearer $KEY"

GET/v1/carriers/{dot}/history

Field changes recorded by the daily diff.

curl -s https://carriervet.dev/v1/carriers/9900011/history -H "authorization: Bearer $KEY"

POST/v1/carriers/batch

Up to 500 DOT or MC numbers. Pro and Business. Duplicate ids are billed once.

curl -s -X POST https://carriervet.dev/v1/carriers/batch \
  -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"identifiers":["9900001","MC9900002"]}'

GET/v1/search?name=

Name search over the indexed snapshot. Minimum 2 characters.

curl -s "https://carriervet.dev/v1/search?name=Northline" -H "authorization: Bearer $KEY"

POST/v1/monitors

Watch a carrier. Free cannot monitor. Starter is email only. Pro and Business can set a webhook.

curl -s -X POST https://carriervet.dev/v1/monitors \
  -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"dot_number":"9900001","alert_email":"ops@example.com","webhook_url":"https://example.com/hooks/carriervet"}'

GET/v1/monitors

List monitors for the calling account.

curl -s https://carriervet.dev/v1/monitors -H "authorization: Bearer $KEY"

DELETE/v1/monitors/{dot}

Stop monitoring a USDOT number.

curl -s -X DELETE https://carriervet.dev/v1/monitors/9900001 -H "authorization: Bearer $KEY"

GET/v1/export/monitors.csv

Business plan. One row per monitored carrier.

curl -s https://carriervet.dev/v1/export/monitors.csv -H "authorization: Bearer $KEY"

GET/v1/usage

Lookups used this UTC month, monitor count, and plan limits.

curl -s https://carriervet.dev/v1/usage -H "authorization: Bearer $KEY"

POST/v1/billing/checkout

Stripe Checkout for starter, pro, or business. Interval is month or year. Returns the Stripe Checkout URL to redirect to.

curl -s -X POST https://carriervet.dev/v1/billing/checkout \
  -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"plan":"starter","interval":"month"}'

POST/v1/billing/portal

Stripe Customer Portal. Requires a customer id from a completed checkout.

curl -s -X POST https://carriervet.dev/v1/billing/portal -H "authorization: Bearer $KEY"

POST/v1/stripe/webhook

Stripe subscription webhook. Rejects requests without a valid Stripe-Signature.

curl -s -X POST https://carriervet.dev/v1/stripe/webhook \
  -H 'content-type: application/json' \
  -d '{"id":"evt_demo","type":"checkout.session.completed"}'

Webhook signatures

Alert posts include X-CarrierVet-Signature: t=<unix>,v1=<hex>. The hex is HMAC-SHA256 of t + "." + rawBody using the account webhook secret from GET /v1/account.

Risk reason codes

authority_under_90_days, recent_address_change, recent_phone_change, recent_email_change, shared_phone, shared_email, shared_address, insurance_lapsed, insurance_missing, revoked_authority, inactive_authority, pending_authority, out_of_service, prior_revocation, undeliverable_mail.

Set RISK_CONFIG_JSON to override points, windows, and shared-contact thresholds. Unknown JSON is ignored and the built-in config is used.