> 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-violations.md). # Carrier FMCSA Violations ### Carrier FMCSA Violations Endpoint Retrieve standalone **FMCSA violation history** (per-inspection violation rows) for one or more carriers, without pulling FMCSA detail, sightings, equipment, scores, 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. `basic_scores.*.violation_summary` there gives aggregated counts; this endpoint gives per-inspection detail. {% 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-violations` | Required to access this endpoint | ### **Endpoint** * **URL:** `https://api.genlogs.io/carrier/profile/fmcsa/violations` * **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 `inspection_date` filtering. Omit for full history. * **end\_date** (*string, optional*): Inclusive end date (YYYY-MM-DD) for `inspection_date` filtering. Omit for full history. ### Understanding FMCSA violations information {% hint style="info" %} Responses are grouped by **USDOT**. Each USDOT that exists in FMCSA data returns a `violations` array (empty if no violations in range); USDOTs that don't exist are omitted from the response entirely. Violations are sorted by `inspection_date` descending (most recent first). {% endhint %} **FMCSA Violations returns one object per USDOT:** * **violations** (array): One entry per inspection violation record. * **report\_number**: (string, nullable) The inspection report number. * **inspection\_date**: (string, nullable) Date of the inspection (YYYY-MM-DD). * **violation\_code**: (string, nullable) FMCSA violation code. * **description**: (string, nullable) Human-readable violation description. * **vins**: (array of string, nullable) VIN(s) associated with the violation. * **basic\_category**: (string, nullable) BASIC category the violation rolls up to (e.g. Unsafe Driving). * **basic\_severity\_weight**: (integer, nullable) FMCSA severity weight for the violation. * **oos**: (boolean, nullable) Whether the violation resulted in an out-of-service order. * **oos\_weight**: (integer, nullable) Out-of-service weight, if applicable. ### **Response:** * **200 OK:** A JSON object containing a `violations` array 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-violations` 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 `{ "violations": [...] }` objects grouped by `usdot_number`. ### Request Example: ``` curl --location 'https://api.genlogs.io/carrier/profile/fmcsa/violations?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": { "violations": [ { "report_number": "CA123456", "inspection_date": "2025-03-14", "violation_code": "392.2S", "description": "Speeding 6-10 mph over limit", "vins": ["1FUJA6CK67LX14816"], "basic_category": "Unsafe Driving", "basic_severity_weight": 5, "oos": false, "oos_weight": null } ] } } ``` ## Get carrier FMCSA violations > Retrieve standalone FMCSA violation history (per-inspection violation rows) for specified USDOT numbers, without pulling FMCSA detail, sightings, equipment, scores, or insurance. Violations are sorted by inspection\_date descending (most recent first).\ > Roles must include \`external-api-carrier-fmcsa-violations\`.
```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/violations":{"get":{"tags":["Carrier Profile"],"summary":"Get carrier FMCSA violations","description":"Retrieve standalone FMCSA violation history (per-inspection violation rows) for specified USDOT numbers, without pulling FMCSA detail, sightings, equipment, scores, or insurance. Violations are sorted by inspection_date descending (most recent first).\nRoles must include `external-api-carrier-fmcsa-violations`.\n","operationId":"getCarrierFmcsaViolations","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 violations for"},{"in":"query","name":"start_date","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive start date (YYYY-MM-DD) for inspection_date filtering. Omit for full history."},{"in":"query","name":"end_date","required":false,"schema":{"type":"string","format":"date"},"description":"Inclusive end date (YYYY-MM-DD) for inspection_date filtering. Omit for full history."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FmcsaViolationsItem"}}}}},"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":{"FmcsaViolationsItem":{"type":"object","description":"Per-USDOT payload for `GET /carrier/profile/fmcsa/violations`.","properties":{"violations":{"type":"array","description":"Sorted by inspection_date descending (most recent first).","items":{"$ref":"#/components/schemas/ViolationRecord"}}},"required":["violations"]},"ViolationRecord":{"type":"object","description":"A single per-inspection FMCSA violation row.","properties":{"report_number":{"type":"string","nullable":true,"description":"The inspection report number."},"inspection_date":{"type":"string","format":"date","nullable":true},"violation_code":{"type":"string","nullable":true,"description":"FMCSA violation code."},"description":{"type":"string","nullable":true,"description":"Human-readable violation description."},"vins":{"type":"array","nullable":true,"items":{"type":"string"},"description":"VIN(s) associated with the violation."},"basic_category":{"type":"string","nullable":true,"description":"BASIC category the violation rolls up to."},"basic_severity_weight":{"type":"integer","nullable":true,"description":"FMCSA severity weight for the violation."},"oos":{"type":"boolean","nullable":true,"description":"Whether the violation resulted in an out-of-service order."},"oos_weight":{"type":"integer","nullable":true,"description":"Out-of-service weight, if applicable."}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer","format":"int32"}},"required":["message","code"]}}}} ```