VioCodes Partner API — Documentation

Evaluation keys run against a sandbox that mirrors the live FMCSA SMS methodology, but is rate-limited and meant for integration testing — not production traffic. A production key and endpoint are issued on agreement.

Base URL & conventions

https://viocodes.yuriance.net/api/v1

All responses are JSON — including errors and rate-limit rejections. Carrier data is composed live from free, current FMCSA public sources (Company Census, Licensing & Insurance, the latest SMS run, MCMIS inspections & crashes, and the QCMobile safety-rating API). Every value is a public record; VioCodes resells nothing.

Every endpoint requires a valid API key — including the self-describing index at GET /. The single exception is GET /ping, a bare health check that returns no data. Requests without a key (or with an invalid one) get 401, and a per-IP throttle guards against key-guessing before auth even runs.

Authentication

Every protected endpoint requires your API key as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

Calls are server-to-server — your backend holds the key and calls VioCodes. Never expose it in a browser or mobile client. Missing or invalid keys return 401.

Rate limits

The sandbox allows 300 requests per minute per key. Every response includes:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix time when the window resets

Exceeding the limit returns 429 with a Retry-After header. Carrier endpoints fan out to several upstream sources per call, so cache responses on your side where you can.

Violations & scoring

GET/violations/searchauth

Typeahead search across violation code, description, and group — ranked so the best code/prefix matches surface first. Ideal for "type and pick one" UIs. Dash/paren/space-tolerant.

Query param	Req	Description
`q`	yes	Search text (min 2 chars)
`basic`	no	Filter to one BASIC category
`limit`	no	Results per page (1–50, default 20)
`page`	no	Page number (default 1)

curl "https://viocodes.yuriance.net/api/v1/violations/search?q=brake&limit=5" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

→ 200
{ "query":"brake", "total":180, "page":1, "limit":5, "totalPages":36,
  "items":[ { "code":"393.48A", "description":"Inoperative brakes", "basic":"Vehicle Maintenance",
    "severityWeight":4, "oosIndicator":true, "usedInSms":true, "violationGroup":"Brakes" } ] }

GET/violations/lookupauth

Look up a single FMCSA violation code. Matching is tolerant — 392.2(d)IM, 392.2DIM, and 392.2dim all resolve. Unknown codes return 404 with the echoed code.

Query param	Req	Description
`code`	yes	The FMCSA violation code to look up

curl "https://viocodes.yuriance.net/api/v1/violations/lookup?code=392.3" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

→ 200
{
  "code": "392.3",
  "description": "Operating a CMV while ill or fatigued",
  "basic": "Hours-of-Service Compliance",
  "severityWeight": 10,
  "oosIndicator": false,
  "usedInSms": true,
  "violationGroup": "Jumping OOS/Driving Fatigued",
  "regulationSection": "392.3"
}

POST/inspections/scoreauth

The CSA calculator. Score a full inspection (one or many violations) and get the total CSA points, a per-BASIC rollup, and a per-violation breakdown — severity weight, out-of-service bonus, the time-weight tier (3× / 2× / 1× by recency), and final points. Scoring tracks the FMCSA SMS methodology and is kept current as the tables change.

Body field	Req	Description
`inspectionDate`	yes	Date of the inspection (`YYYY-MM-DD`)
`asOfDate`	no	Date to calculate against; defaults to today
`violations[]`	yes	Array of `{ code, outOfService }`; at least one

curl -X POST "https://viocodes.yuriance.net/api/v1/inspections/score" \
  -H "Authorization: Bearer <YOUR_API_KEY>" -H "Content-Type: application/json" \
  -d '{ "inspectionDate":"2026-04-01", "asOfDate":"2026-06-09",
       "violations":[ {"code":"392.3"}, {"code":"392.63","outOfService":true} ] }'

→ 200
{
  "inspectionDate":"2026-04-01T00:00:00.000Z", "asOfDate":"2026-06-09T00:00:00.000Z",
  "totalPoints":66,
  "basicImpacts":[
    { "basic":"Vehicle Maintenance", "points":36, "violationCount":1 },
    { "basic":"Hours-of-Service Compliance", "points":30, "violationCount":1 } ],
  "perViolation":[
    { "code":"392.63", "basic":"Vehicle Maintenance", "severityWeight":10,
      "oosBonus":2, "effectiveSeverity":12, "timeWeight":3,
      "timeTier":"0–6 months", "points":36, "inSms":true } ],
  "notFound": []
}

Codes not in the SMS table (e.g. dimension-only citations) return inSms:false and contribute 0 points — even when cited out-of-service — exactly as SMS scores them. Unresolvable codes come back in a notFound array so nothing fails silently.

Carrier intelligence

Everything the VioCodes carrier page shows — served as JSON. A {usdot} path segment is the numeric USDOT number; non-digits are stripped.

GET/carriers/searchauth

Find carriers by name, USDOT (all digits), or MC/MX/FF docket (with prefix). The response kind tells you which match path was used.

Query param	Req	Description
`q`	yes	Name, USDOT, or MC/MX/FF number (min 2 chars)
`limit`	no	Max results (1–25, default 10)

curl "https://viocodes.yuriance.net/api/v1/carriers/search?q=MC-146894" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

→ 200
{ "query":"MC-146894", "kind":"docket", "count":1,
  "results":[ { "usdot":"76600", "legal_name":"SCHNEIDER NATIONAL CARRIERS INC",
    "dba_name":null, "location":"GREEN BAY, WI", "operating_status":"Active",
    "officer":"..." } ] }

GET/carriers/{usdot}auth

The full carrier safety snapshot: identity, docket, operating status, addresses & phone, fleet size, US inspection performance (vehicle/driver, with national averages), crash totals, operation classification, and the FMCSA safety rating. Returns 404 if the USDOT isn't in FMCSA records.

curl "https://viocodes.yuriance.net/api/v1/carriers/76600" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

→ 200  (abridged)
{
  "usdot":"76600", "legal_name":"SCHNEIDER NATIONAL CARRIERS INC", "dba_name":null,
  "mc_mx_ff_numbers":"MC-146894", "entity_type":"CARRIER",
  "operating_status":"AUTHORIZED FOR Property",
  "physical_address":"...", "phone":"(920) ...",
  "power_units":9200, "drivers":10400,
  "united_states_inspections":{
    "vehicle":{ "inspections":20173, "out_of_service":1710,
      "out_of_service_percent":"8.5", "national_average":"22" },
    "driver":{ /* … */ }, "hazmat":null },
  "united_states_crashes":{ "total":.., "fatal":.., "injury":.., "tow":.. },
  "safety_rating":"Satisfactory", "safety_rating_date":"...",
  "latest_update":"Aug 2026"
}

GET/carriers/{usdot}/riskauth

The decision layer: a 0–100 risk score (higher = safer), a red/amber/green level, the exact factors behind it, the vetting booleans (authority, insurance, OOS order, revocation, reincarnation), and a metric summary. This is the single call to answer "should I worry about this carrier?"

curl "https://viocodes.yuriance.net/api/v1/carriers/1916638/risk" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

→ 200
{
  "usdot":"1916638", "legalName":"BEST WAY LOGISTICS 1 INC",
  "operatingStatus":"ACTIVE",
  "risk":{ "level":"amber", "score":65,
    "reasons":[ { "level":"amber", "text":"Authority revocation pending" } ] },
  "vetting":{ "authorityActive":true, "revocationPending":true, "liabilityOnFile":true,
    "bipdOnFile":750000, "underOosOrder":false, "reincarnation":false },
  "metrics":{ "inspections":462, "crashes":15, "fatal":0,
    "vehicleOosPct":21.3, "driverOosPct":3.2, "powerUnits":176, "bipdOnFile":750000 }
}

GET/carriers/{usdot}/csaauth

CSA / SMS breakdown: inspection & violation counts, this carrier's top violation codes ranked by count × severity, a per-BASIC rollup, inspections by state, and any acute/critical findings.

→ 200  (abridged)
{
  "counts":{ "totalInspections":462, "totalViolations":29,
    "totalOosViolations":2, "oosInspectionRate":7, "distinctViolationCodes":10 },
  "topViolations":[ { "code":"395.8E-HOSPD", "description":"HOS – false report…",
    "basic":"Hours-of-Service Compliance", "severityWeight":7,
    "count":2, "oosCount":0, "score":14 } ],
  "violationsByBasic":[ /* per-BASIC counts */ ],
  "inspectionsByState":[ /* state → count */ ],
  "acuteCritical":[ /* … */ ]
}

GET/carriers/{usdot}/trendsauth

24-month trajectory of each BASIC measure, out-of-service rate, and inspection volume. Measures are reconstructed from the carrier's dated roadside record using the SMS formula (time weight × severity, normalized by relevant-inspection time weight), then calibrated so the latest point equals FMCSA's published measure. Each series is a monthly rolling-24-month window — ideal for charting a carrier's direction or reading its profile "as of" a past date.

→ 200  (abridged)
{
  "window":24, "smsRun":"Aug 2026", "latestInspection":"2026-09-01",
  "newSinceRun":5, "postAccidentSinceRun":1, "projected":true,
  "runIndex":22,   // months[runIndex] = last point at/ before the run; after = projected
  "months":["Sep 24", … 25 labels … "Sep 26"],
  "basics":{
    "Vehicle Maintenance":{ "kind":"vehicle",
      "official":4.05,        // FMCSA's published measure (this run)
      "projectedNext":4.2,     // our projection for the next run
      "projDelta":0.15, "direction":"up",
      "series":[2.55, …, 4.2], "source":"fmcsa-anchored" } /* +others */ },
  "volume":[237, …, 447],
  "oos":{ "vehicle":[26.3, …, 20.1], "driver":[…], "vehicleNat":22, "driverNat":6.7 }
}

official is FMCSA's published measure for the current run; projectedNext recomputes the SMS formula over inspections on record now (including the newSinceRun added since the run) to estimate the next monthly run. direction:"up" means worsening. runIndex marks the actual/projected boundary in series — points after it aren't in an official run yet. postAccidentSinceRun counts post-accident inspections among the new ones: FMCSA excludes crash-attributed violations (that flag isn't in public data), so when it's > 0 the projection may read high and self-corrects at the next run. Percentiles aren't published in bulk — measures + direction only; the projection is an estimate, not an official FMCSA figure.

GET/carriers/{usdot}/improvement-planauth

A recency-focused read of the last 90 days: a summary, the trend vs the prior 90, which BASICs the violations concentrate in, ranked focus areas with their worst codes and prevention actions, and the repeat offenders (same code cited multiple times).

→ 200  (abridged)
{
  "windowDays":90, "hasActivity":true,
  "summary":{ "inspections":27, "violations":34, "oos":1, "cleanInspections":13 },
  "trend":{ "direction":"up", "recentPerInspection":1.26, "priorPerInspection":1.1 },
  "byBasic":[ { "basic":"Vehicle Maintenance", "violations":20, "oos":7, "share":59 } … ],
  "focusAreas":[ { "basic":"Vehicle Maintenance", "violations":20, "share":59,
    "topIssues":[ { "code":"393.75A3-TAOL", "count":3, "oos":1 } ],
    "actions":[ "Gauge/thump every tire…" ] } ],
  "recurring":[ { "code":"393.75A3-TAOL", "count":3, "oos":1 } ]
}

GET/carriers/{usdot}/basic-improvementauth

Per-BASIC "how to improve this category" with real numbers: how many clean inspections would dilute the measure by 10 / 25 / 50%, where it drifts from pure aging if no new violations are added (in 3 and 6 months), and the top contest targets (each violation's share of the BASIC). The SMS measure is N ÷ D and a fresh clean inspection adds 3 to D, so the reductions are exact.

→ 200  (abridged)
{ "basics":{
  "Vehicle Maintenance":{
    "measure":4.05, "relevantInspections":169, "violations":150, "oos":43,
    "cleanToReduce":[ { "pct":25, "inspections":31, "newMeasure":3.037 } … ],
    "decay":{ "in90":4.419, "in180":3.842 },
    "topContributors":[ { "code":"393.75A3-TAOL", "share":3, "oos":true } ] } } }

Estimates from the SMS formula on public data — not official FMCSA figures. Percentiles aren't published in bulk, so this works in measures.

GET/carriers/{usdot}/inspectionsauth

The full roadside-inspection & crash history — every inspection with its violations, and each violation enriched with its BASIC, severity, out-of-service flag, and computed CSA points (severity × time-weight). Includes fleet-wide totals and per-state counts. This is the carrier's raw violation data.

→ 200  (abridged)
{
  "totals":{ "inspections":645, "violations":589, "oos":94,
    "points":2028, "crashes":87, "states":44 },
  "inspections":[ {
    "id":"88838825", "date":"2026-08-28", "state":"IA", "level":"I — Full",
    "violTotal":4, "oosTotal":0, "timeWeight":3, "points":48,
    "violations":[ { "code":"396.3A1-ALBV", "desc":"Air Brake – any leak…",
      "basic":"Vehicle Maintenance", "severity":4, "points":12, "oos":false } ] } ],
  "crashes":[ { "date":"…", "state":"…", "fatalities":0, "injuries":1, "tow":true } ]
}

Supports a period focus in-app; the API returns full history so you can window it yourself.

GET/carriers/{usdot}/connectionsauth

The identity/fleet-transfer graph: other carriers sharing a VIN, physical or mailing address, phone, email, or company officer with this one — each scored by connection strength — plus a predecessor when a newer active carrier is tied to an older inactive one (the reincarnation / "chameleon" signal).

→ 200  (abridged)
{
  "counts":{ "vin":0, "address":0, "phone":0, "email":0, "officer":2 },
  "connections":[ {
    "usdot":"3687915", "name":"THUNDER EXPEDITED LOGISTICS LLC",
    "active":true, "status":"Active", "city":"DES MOINES", "state":"IA",
    "links":["officer"], "sharedVins":[], "vinCount":0, "strength":"strong" } ],
  "predecessor": null
}

GET/carriers/{usdot}/authorityauth

Operating authority (common/contract/broker status & pending actions, authorized types, BIPD requirement) and the full insurance picture — active policies with insurer, policy number, coverage, and effective/cancel dates, plus filing history and rejected filings.

→ 200  (abridged)
{
  "available":true,
  "authority":{ "docket":"…", "common":{"tone":"ok"}, "contract":{…},
    "broker":{…}, "pending":{…}, "types":["Property"], "insuranceReq":{…} },
  "policies":[ { "form":"91X", "label":"Liability (BIPD) — BMC-91X",
    "insurer":"MS Transverse Insurance Company", "policyNo":"TINCA7951504",
    "maxCov":750000, "effective":"06/02/2026", "cancelDate":null,
    "ended":false, "onFile":true } ],
  "insuranceHistory":[ /* … */ ], "rejected":[ /* … */ ]
}

GET/carriers/{usdot}/equipmentauth

Distinct vehicles seen in this carrier's roadside inspections — VIN, plate, times seen, and the year/make/model/type decoded via the free NHTSA vPIC database.

→ 200  (abridged)
{ "available":true, "count":96,
  "units":[ { "vin":"4V4NC9EH2RN641705", "plate":"P1194831", "plateState":"IL",
    "seen":3, "year":"2024", "make":"VOLVO TRUCK", "model":"VNL", "type":"TRUCK" } ] }

POST/carriers/screenauth

Bulk-screen many carriers in one call. Send up to 50 USDOTs and get each back risk-ranked with an approve / review / reject verdict, a 0–100 score, and the flags that fired — against the default policy or your own.

Body field	Req	Description
`usdots`	yes	Array of USDOTs, or a string with any separators. Capped at 50 (`truncated:true` if longer)
`rules[]`	no	Policy overrides: `{ id, enabled, action, threshold }`. Omit to use the default policy

Rule ids: underOos, authorityInactive, noLiability, fatalCrash, revocationPending, reincarnation, basicAlerts, vehicleOos, driverOos, crashes, minInspections. action is "review" or "reject". Verdict = any reject-hit → reject, else any review-hit → review, else approve.

curl -X POST "https://viocodes.yuriance.net/api/v1/carriers/screen" \
  -H "Authorization: Bearer <YOUR_API_KEY>" -H "Content-Type: application/json" \
  -d '{ "usdots":["1916638","2407268"],
       "rules":[ {"id":"vehicleOos","action":"reject","threshold":25} ] }'

→ 200
{
  "count":2, "truncated":false, "max":50,
  "summary":{ "reject":1, "review":1, "approve":0, "error":0 },
  "results":[ {
    "usdot":"2407268", "found":true, "legalName":"ZAK TRUCKING LLC",
    "operatingStatus":"INACTIVE", "verdict":"reject", "score":0, "riskLevel":"red",
    "triggered":[ { "id":"authorityInactive", "action":"reject",
      "detail":"Authority not active" } ],
    "dataGaps":[], "metrics":{ /* inspections, crashes, OOS … */ } } ]
}

A carrier whose facts can't be determined never gets silently rejected — the missing checks are listed in dataGaps, and unresolvable USDOTs come back with verdict:"error".

Errors

All errors return JSON with an error message. Standard status codes:

Status	Meaning
`400`	Invalid input (bad JSON, missing/invalid fields)
`401`	Missing or invalid API key
`404`	Resource, carrier, code, or endpoint not found
`429`	Rate limit exceeded
`502`	Upstream FMCSA data source error (retry shortly)
`500`	Server error

Getting started

Request an API key and tell us what you're building.
Confirm connectivity with GET /ping, then explore GET / for the live endpoint list.
Try /violations/lookup and /carriers/{usdot}/risk with a code and USDOT you know.
Wire /inspections/score into your inspection-save flow, and /carriers/screen into your onboarding/load-assignment flow to show a verdict in-app.