curl -X POST https://api.dotlookup.dev/v1/carriers/2233855/risk-score \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{"min_bipd": 1000000, "min_cargo": 100000}'
import requests
resp = requests.post(
"https://api.dotlookup.dev/v1/carriers/2233855/risk-score",
headers={"X-API-Key": "your_api_key"},
json={"min_bipd": 1_000_000, "min_cargo": 100_000},
)
result = resp.json()
print(f"Score: {result['risk_score']['score']} ({result['risk_score']['grade']})")
const resp = await fetch("https://api.dotlookup.dev/v1/carriers/2233855/risk-score", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "your_api_key",
},
body: JSON.stringify({ min_bipd: 1_000_000, min_cargo: 100_000 }),
});
const { risk_score } = await resp.json();
{
"dot_number": "2233855",
"policy": {
"min_bipd": 1000000,
"min_cargo": 100000
},
"risk_score": {
"score": 72,
"grade": "C",
"tier": "Fair",
"confidence": "high",
"components": [
{ "name": "Compliance", "score": 95, "weight": 40 },
{ "name": "Safety", "score": 82, "weight": 35 },
{ "name": "Insurance", "score": 55, "weight": 25 }
],
"flags": [
{
"severity": "warning",
"code": "LOW_BIPD",
"message": "BIPD coverage below configured minimum ($1000000)"
}
]
}
}
Carriers
Policy-aware Risk Score
Compute a carrier risk score against caller-supplied policy thresholds
POST
/
v1
/
carriers
/
{dot_number}
/
risk-score
curl -X POST https://api.dotlookup.dev/v1/carriers/2233855/risk-score \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{"min_bipd": 1000000, "min_cargo": 100000}'
import requests
resp = requests.post(
"https://api.dotlookup.dev/v1/carriers/2233855/risk-score",
headers={"X-API-Key": "your_api_key"},
json={"min_bipd": 1_000_000, "min_cargo": 100_000},
)
result = resp.json()
print(f"Score: {result['risk_score']['score']} ({result['risk_score']['grade']})")
const resp = await fetch("https://api.dotlookup.dev/v1/carriers/2233855/risk-score", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "your_api_key",
},
body: JSON.stringify({ min_bipd: 1_000_000, min_cargo: 100_000 }),
});
const { risk_score } = await resp.json();
{
"dot_number": "2233855",
"policy": {
"min_bipd": 1000000,
"min_cargo": 100000
},
"risk_score": {
"score": 72,
"grade": "C",
"tier": "Fair",
"confidence": "high",
"components": [
{ "name": "Compliance", "score": 95, "weight": 40 },
{ "name": "Safety", "score": 82, "weight": 35 },
{ "name": "Insurance", "score": 55, "weight": 25 }
],
"flags": [
{
"severity": "warning",
"code": "LOW_BIPD",
"message": "BIPD coverage below configured minimum ($1000000)"
}
]
}
}
Computes a fresh risk score for a carrier against thresholds you supply. The default
GET /v1/carriers/{dot} response uses federal-minimum thresholds (BIPD ≥ $750k, no cargo minimum); this endpoint lets brokers and shippers score against stricter internal policies without DotLookup having to know who you are or what your policy is.
This endpoint requires an API key and is stateless — DotLookup never persists your policy. Each call is pure compute over
(carrier data) × (policy).Use
GET /v1/carriers/{dot} for the default-policy score (cached and free of auth). Use this endpoint when your underwriting policy differs from the federal defaults.string
required
The carrier’s USDOT number
integer
BIPD coverage floor in dollars. Carriers with active BIPD below this threshold get a
LOW_BIPD warning flag and a -25 insurance penalty. Default: 750000 (federal minimum).integer
Cargo coverage floor in dollars. Carriers with cargo coverage above zero but below this threshold get a
LOW_CARGO_INSURANCE warning flag and a -10 insurance penalty. Default: 0 (no minimum — only completely missing cargo is flagged).curl -X POST https://api.dotlookup.dev/v1/carriers/2233855/risk-score \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{"min_bipd": 1000000, "min_cargo": 100000}'
import requests
resp = requests.post(
"https://api.dotlookup.dev/v1/carriers/2233855/risk-score",
headers={"X-API-Key": "your_api_key"},
json={"min_bipd": 1_000_000, "min_cargo": 100_000},
)
result = resp.json()
print(f"Score: {result['risk_score']['score']} ({result['risk_score']['grade']})")
const resp = await fetch("https://api.dotlookup.dev/v1/carriers/2233855/risk-score", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "your_api_key",
},
body: JSON.stringify({ min_bipd: 1_000_000, min_cargo: 100_000 }),
});
const { risk_score } = await resp.json();
{
"dot_number": "2233855",
"policy": {
"min_bipd": 1000000,
"min_cargo": 100000
},
"risk_score": {
"score": 72,
"grade": "C",
"tier": "Fair",
"confidence": "high",
"components": [
{ "name": "Compliance", "score": 95, "weight": 40 },
{ "name": "Safety", "score": 82, "weight": 35 },
{ "name": "Insurance", "score": 55, "weight": 25 }
],
"flags": [
{
"severity": "warning",
"code": "LOW_BIPD",
"message": "BIPD coverage below configured minimum ($1000000)"
}
]
}
}
Behavior
- Empty body (or
{}) is valid — it returns the default-policy score, equivalent toGET /v1/carriers/{dot}but on a non-cached path that always recomputes from source data. - Partial overrides merge with the default — sending
{"min_bipd": 1000000}gives you a $1M BIPD threshold with the default cargo behavior. - Negative thresholds are rejected with
400 INVALID_PARAM. - Response stamps the effective policy — the
policyfield in the response is the merged policy that was actually applied. Stamp this on your evidence packet so the score can be reproduced later. - Chameleon-carrier signals are reused from the precomputed nightly snapshot — the cap behavior is identical to the default-policy score.
When stricter policies move the score
The most common deltas:| Scenario | Default policy | Stricter policy | Score effect |
|---|---|---|---|
| Carrier with $750k BIPD | OK (federal min) | min_bipd: 1000000 adds LOW_BIPD flag | -25 insurance, ~-6 overall |
| Carrier with $50k cargo | OK (cargo present) | min_cargo: 100000 adds LOW_CARGO_INSURANCE flag | -10 insurance, ~-3 overall |
| Carrier with $0 BIPD | NO_BIPD flag + hard cap at 35 | Same — min_bipd doesn’t change behavior when BIPD is zero | No incremental effect |
| Carrier with $0 cargo | NO_CARGO_INSURANCE flag (-15 insurance) | Same — min_cargo only flags below-threshold, not absent | No incremental effect |
Rate limit and auth
This endpoint counts against your account’s rate limit — the single shared limit used by every authenticated request, includingPOST /v1/carriers/bulk and ordinary carrier lookups. There is no separate bulk-API pool. It returns 401 UNAUTHORIZED without a valid X-API-Key header.