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.

Need everything at once (FMCSA detail, equipment pairings, sightings, and all FI-aligned sections)? Use GET /carrier/profile instead ( Carrier Profile Endpoint ) — it returns everything in one call, including iss_score and basic_scores.

Authentication

• Include your Access-Token in the header of your requests.

• Include your x-api-key The API key provided by GenLogs. This header must be included in the request.

Permissions

Permission	Effect
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/scores

• Method: 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_time windows on both iss_score and basic_scores. Omit for full history.

• end_date (string, optional): Inclusive end date (YYYY-MM-DD) for score_over_time windows. Omit for full history.

Understanding FMCSA scores information

Responses are grouped by USDOT. USDOTs that don't exist in FMCSA data are omitted from the response entirely. Callers without external-api-carrier-iss-score will not see the iss_score key at all (it's omitted, not returned as null).

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) and basic_scores per requested USDOT.

• 400 Bad Request: If usdot_number is missing/empty, exceeds the allowed limit, or start_date/end_date is 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-scores permission 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 by usdot_number.

Request Example:

curl --location 'https://api.genlogs.io/carrier/profile/fmcsa/scores?usdot_number=10553&start_date=2025-01-01&end_date=2025-09-01' \
--header 'Access-Token: {your-user-token}' \
--header 'x-api-key: {your-x-api-key}'

Response Example:

{
  "10553": {
    "iss_score": {
      "score": 68,
      "score_over_time": [
        { "date": "2025-01-01", "score": 65 },
        { "date": "2025-02-01", "score": 68 }
      ]
    },
    "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
    }
  }
}

Get carrier FMCSA scores

get

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).

Query parameters

usdot_numberstring[]Required

USDOT numbers to get FMCSA scores for

start_datestring · dateOptional

Inclusive start date (YYYY-MM-DD) for score_over_time windows. Omit for full history.

end_datestring · dateOptional

Inclusive end date (YYYY-MM-DD) for score_over_time windows. Omit for full history.

Header parameters

Access-TokenstringRequired

Token for authentication

x-api-keystringRequired

GenLogs generated API Key for authentication

Responses

200

Successful response

application/json

400

Bad Request - invalid or missing usdot_number, or invalid start_date/end_date

application/json

401

Unauthorized – missing token

application/json

403

Forbidden – invalid token or insufficient permissions

application/json

404

Not Found - none of the requested USDOT numbers exist

application/json

500

Internal Server Error

application/json

get/carrier/profile/fmcsa/scores

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
    }
  }
}