Carrier FMCSA Scores
Carrier FMCSA Scores Endpoint
Retrieve standalone ISS score and BASIC scores (with history and violation summaries) for one or more carriers, without pulling FMCSA detail, sightings, equipment, or insurance.
Authentication
Include your
Access-Tokenin the header of your requests.Include your
x-api-keyThe API key provided by GenLogs. This header must be included in the request.
Permissions
external-api-carrier-fmcsa-scores
Required to access this endpoint
external-api-carrier-iss-score
Required for the iss_score section; omitted (not null) otherwise
Endpoint
URL:
https://api.genlogs.io/carrier/profile/fmcsa/scoresMethod:
GET
Headers
Access-Token: (string, required): Access token obtained from the "Create Access Token" endpoint.
x-api-key (string, required): The API key provided by GenLogs.
Query Parameters:
usdot_number (array of string, required): One or more USDOT numbers; repeat the parameter for multiple values, e.g.
?usdot_number=10553&usdot_number=2350084.start_date (string, optional): Inclusive start date (YYYY-MM-DD) for
score_over_timewindows on bothiss_scoreandbasic_scores. Omit for full history.end_date (string, optional): Inclusive end date (YYYY-MM-DD) for
score_over_timewindows. Omit for full history.
Understanding FMCSA scores information
FMCSA Scores returns one object per USDOT:
iss_score (object, nullable — only present with
external-api-carrier-iss-score):score: (integer, nullable) Current ISS score.
score_over_time: (array)
{ date, score }points, sorted ascending by date.
basic_scores (object): One entry per BASIC category —
unsafe_driving,driver_fitness,hos,drugs_alcohol,vehicle_maintenance. Each category (nullable if no data) has:score: (integer, nullable) Current BASIC percentile score.
score_over_time: (array)
{ date, score }points, sorted ascending by date.violation_summary: (array)
{ weight, category, total, out_of_service }— aggregated violation counts for that BASIC category.
Response:
200 OK: A JSON object containing
iss_score(if permitted) andbasic_scoresper requested USDOT.400 Bad Request: If
usdot_numberis missing/empty, exceeds the allowed limit, orstart_date/end_dateis not valid YYYY-MM-DD.401 Unauthorized: If the authentication credentials (Access-Token) is missing or incorrect.
403 Forbidden: If the
external-api-carrier-fmcsa-scorespermission has not been added to your user.404 Not Found: If none of the requested USDOT numbers exist.
500 Internal Server Error: If there is an issue on the server that prevents processing the request.
Response Body:
Data (object): Set of
{ "iss_score": {...}, "basic_scores": {...} }objects grouped byusdot_number.
Request Example:
Response Example:
Retrieve standalone ISS score and BASIC scores (with history and violation summaries) for specified USDOT numbers, without pulling FMCSA detail, sightings, equipment, or insurance. Roles must include external-api-carrier-fmcsa-scores. The iss_score key is additionally gated on external-api-carrier-iss-score; without it, iss_score is omitted entirely (not null).
USDOT numbers to get FMCSA scores for
Inclusive start date (YYYY-MM-DD) for score_over_time windows. Omit for full history.
Inclusive end date (YYYY-MM-DD) for score_over_time windows. Omit for full history.
Token for authentication
GenLogs generated API Key for authentication
Successful response
Bad Request - invalid or missing usdot_number, or invalid start_date/end_date
Unauthorized – missing token
Forbidden – invalid token or insufficient permissions
Not Found - none of the requested USDOT numbers exist
Internal Server Error
GET /carrier/profile/fmcsa/scores?usdot_number=text HTTP/1.1
Host: api.genlogs.io
Access-Token: text
x-api-key: text
Accept: */*
{
"10553": {
"iss_score": {
"score": 68,
"score_over_time": [
{
"date": "2025-01-01",
"score": 65
}
]
},
"basic_scores": {
"unsafe_driving": {
"score": 72,
"score_over_time": [
{
"date": "2025-02-01",
"score": 70
}
],
"violation_summary": [
{
"weight": 5,
"category": "Speeding",
"total": 8,
"out_of_service": 0
}
]
},
"driver_fitness": null,
"hos": null,
"drugs_alcohol": null,
"vehicle_maintenance": null
}
}
}Last updated