Get All 7 BASIC Percentiles Programmatically
FMCSA scores every carrier across seven BASIC categories — but displays only five publicly, updates them monthly, and offers no API. CarrierOk returns all seven percentiles in the profile response, including Crash Indicator and Hazmat Compliance, which it computes in-house from the public inspection and crash data.
Fetch the profile
All BASIC data rides along with the standard profile lookup — no separate endpoint:
curl "https://api.carrierok.com/v2/profile?dot_number=1234567" \
-H "Authorization: Bearer YOUR_API_KEY"{
"items": [
{
"dot_number": "1234567",
"basic_measure_unsafe_driving": "0",
"basic_measure_crash_indicator": 0.152,
"basic_percentile_crash_indicator": 0.19,
"intervention_threshold_crash_indicator": 0.65,
"basic_alert_unsafe_driving": false,
"basic_alert_crash_indicator": false,
"basic_roadside_alert_crash_indicator": false,
"basic_ac_indicator_vehicle_maintence": false,
"...": "the same six families exist for all 7 categories"
}
],
"total_count": 1
}Know the six field families
Each of the seven categories exposes the same six fields. Category suffixes are the API's real spellings — copy them exactly: unsafe_driving, hours_of_service, driver_fitness, controlled_substance, vehicle_maintence, hazardous_materials, and crash_indicator.
| Field | Meaning |
|---|---|
basic_measure_{category} | Raw BASIC measure (violation severity over exposure). Present for all 7 categories. |
basic_percentile_{category} | Peer-group percentile, 0–1 scale, higher = worse. Present only when FMCSA data sufficiency is met. |
intervention_threshold_{category} | FMCSA's intervention threshold for this carrier's segment (e.g. 0.65 Unsafe Driving). Populated alongside a computed percentile; 0 otherwise. |
basic_alert_{category} | True when the percentile exceeds the intervention threshold — FMCSA's alert condition. |
basic_roadside_alert_{category} | True when a roadside-inspection alert (elevated risk) is active. |
basic_ac_indicator_{category} | True when an acute/critical violation indicator exists from investigations (6 categories; not computed for crash_indicator). |
vehicle_maintence is not a typo in your code
vehicle_maintence, and Controlled Substances is singular (controlled_substance). Writing the dictionary-correct spellings will silently read nothing — the response omits unknown keys and .get() hides the miss.Interpret the scale and data sufficiency
Percentiles are on a 0–1 scale, higher = worse relative to the carrier's peer group. Multiply by 100 to match the percentages on FMCSA's SMS site: 0.19is the 19th percentile. A category's basic_alert_* flips true when the percentile crosses the segment-specific FMCSA threshold served in intervention_threshold_* (0.65 for the crash-predictive BASICs in most segments, 0.80 for the rest).
Two sparsity rules to code for: a percentile field is omitted entirely (not null) when the carrier lacks FMCSA data sufficiency in that category, and intervention_threshold_* is populated only alongside a computed percentile (it reads 0 otherwise). The raw basic_measure_* is present either way.
Track trends over time
The basic_history array carries dated snapshots of measures, percentiles, and inspection counts — enough to chart whether a carrier is drifting toward a threshold before the alert fires. For continuous coverage, put the carrier on the Monitoring API and receive BASIC-alert changes as they land.
FAQ
Why doesn't FMCSA show the Crash Indicator and Hazmat Compliance BASICs publicly?
FMCSA withholds these two percentiles from SAFER and public SMS views due to long-running debates about crash accountability methodology. The underlying inspection and crash data is public, and FMCSA uses both BASICs internally for enforcement targeting. CarrierOk computes both percentiles from the public source data, so the API returns all seven.
What scale are CarrierOk's BASIC percentiles on?
0–1, where higher is worse relative to the peer group. Multiply by 100 to compare with the percentages FMCSA shows on the SMS website — basic_percentile_unsafe_driving of 0.72 is the 72nd percentile. The matching FMCSA intervention threshold is served per category in intervention_threshold_* (e.g. 0.65 for Unsafe Driving).
Why is a basic_percentile_* field missing from a carrier's response?
FMCSA only computes a percentile when the carrier meets data-sufficiency requirements (enough relevant inspections/violations in the measurement window) — and the CarrierOk API omits fields that have no value rather than returning null. The basic_measure_* raw measure is still present, and intervention_threshold_* is populated only alongside a computed percentile.
How often do BASIC percentiles update?
FMCSA recomputes SMS monthly. CarrierOk ingests each release and refreshes profiles four times daily, so new SMS runs and the inspection/violation data feeding the two computed BASICs appear without waiting on a manual download.