> For the complete documentation index, see [llms.txt](https://docs.genlogs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.genlogs.io/carrier/carrier-profile/carrier-fmcsa-scores.md). # 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. {% hint style="info" %} Need everything at once (FMCSA detail, equipment pairings, sightings, and all FI-aligned sections)? Use `GET /carrier/profile` instead ( [Carrier Profile](/carrier/carrier-profile.md#carrier-profile-endpoint) ) — it returns everything in one call, including `iss_score` and `basic_scores`. {% endhint %} ### **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 {% hint style="info" %} 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). {% endhint %} **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: ```json { "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 > 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).
```json {"openapi":"3.0.3","info":{"title":"Carrier Profile API","version":"1.0.0"},"tags":[{"name":"Carrier Profile","description":"Carrier profile endpoint"}],"servers":[{"url":"https://api.genlogs.io","description":"Production"}],"paths":{"/carrier/profile/fmcsa/scores":{"get":{"tags":["Carrier Profile"],"summary":"Get carrier FMCSA scores","description":"Retrieve standalone ISS score and BASIC scores (with history and violation summaries) for specified USDOT numbers, without pulling FMCSA detail, sightings, equipment, or insurance.\nRoles 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).\n","operationId":"getCarrierFmcsaScores","parameters":[{"in":"header","name":"Access-Token","required":true,"schema":{"type":"string"},"description":"Token for authentication"},{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"GenLogs generated API Key for authentication"},{"in":"query","name":"usdot_number","required":true,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"USDOT numbers to get FMCSA scores for"},{"in":"query","name":"start_date","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive start date (YYYY-MM-DD) for score_over_time windows. Omit for full history."},{"in":"query","name":"end_date","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive end date (YYYY-MM-DD) for score_over_time windows. Omit for full history."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FmcsaScoresItem"}}}}},"400":{"description":"Bad Request - invalid or missing usdot_number, or invalid start_date/end_date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – invalid token or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - none of the requested USDOT numbers exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"FmcsaScoresItem":{"type":"object","description":"Per-USDOT payload for `GET /carrier/profile/fmcsa/scores`.","properties":{"iss_score":{"nullable":true,"description":"Omitted entirely when the caller lacks the external-api-carrier-iss-score permission.","allOf":[{"$ref":"#/components/schemas/IssScore"}]},"basic_scores":{"$ref":"#/components/schemas/BasicScores"}},"required":["basic_scores"]},"IssScore":{"type":"object","properties":{"score":{"type":"integer","nullable":true},"score_over_time":{"type":"array","items":{"$ref":"#/components/schemas/ScoreOverTimePoint"}}}},"ScoreOverTimePoint":{"type":"object","description":"A single score observation. Arrays of these points are sorted ascending by date (oldest first).","properties":{"date":{"type":"string","format":"date","description":"Observation date (YYYY-MM-DD)."},"score":{"type":"integer","nullable":true,"description":"Score for that date. Null when a history row has a valid date but the underlying score (or BASIC percentile) is missing or unparseable."}},"required":["date"]},"BasicScores":{"type":"object","properties":{"unsafe_driving":{"$ref":"#/components/schemas/BasicScoreCategory"},"driver_fitness":{"$ref":"#/components/schemas/BasicScoreCategory"},"hos":{"$ref":"#/components/schemas/BasicScoreCategory"},"drugs_alcohol":{"$ref":"#/components/schemas/BasicScoreCategory"},"vehicle_maintenance":{"$ref":"#/components/schemas/BasicScoreCategory"}},"required":["unsafe_driving","driver_fitness","hos","drugs_alcohol","vehicle_maintenance"]},"BasicScoreCategory":{"type":"object","nullable":true,"properties":{"score":{"type":"integer","nullable":true},"score_over_time":{"type":"array","items":{"$ref":"#/components/schemas/ScoreOverTimePoint"}},"violation_summary":{"type":"array","items":{"$ref":"#/components/schemas/ViolationSummaryRow"}}}},"ViolationSummaryRow":{"type":"object","properties":{"weight":{"type":"integer","nullable":true,"description":"FMCSA severity weight for the violation category."},"category":{"type":"string","nullable":true,"description":"Violation category label."},"total":{"type":"integer","nullable":true,"description":"Total violations in this category."},"out_of_service":{"type":"integer","nullable":true,"description":"Count of out-of-service violations in this category."}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer","format":"int32"}},"required":["message","code"]}}}} ```