> 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-fmcsa-profile.md). # Carrier FMCSA Profile ## Carrier Profile (FMCSA) Endpoint Retrieve a complete FMCSA carrier profile for a single carrier in one request. The endpoint aggregates operating status, authority history, safety (OOS / ISS / BASIC scores), insurance, violations, crashes, and fleet & driver summaries into a single carrier-level payload, with optional VIN-level detail. ### 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. * **`Access-Token`** (string, required): The access token obtained from the "Create Access Token" endpoint. * **`x-api-key`** (string, required): The API key provided by GenLogs. This header must be included in the request. ### Permissions No special permission is required to call this endpoint. A valid External API token returns the full base profile (operating status, authority history, safety/OOS, insurance, violations, crashes, and fleet & drivers). Two **optional** permissions unlock additional data. They are independent — a token may hold either, both, or neither. | Permission | Unlocks | Behavior when absent | | -------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `external-api-carrier-iss-score` | The detailed `iss_basics` section (ISS score detail + BASIC breakdown). | `iss_basics` is `null` and an `errors.iss_basics` entry of type `PermissionError` is returned. | > **Note on the ISS score.** The summary ISS score (`oos.iss_score`) is **always** included in the response and is **not** gated. The `external-api-carrier-iss-score` permission only controls the detailed `iss_basics` breakdown section. ### Endpoint **URL:** `https://api.genlogs.io/carrier/profile/fmcsa` **Method:** `GET` #### Headers | Header | Required | Description | | -------------- | -------- | ------------------------------------------------------------------ | | `Access-Token` | Yes | The access token obtained from the "Create Access Token" endpoint. | | `x-api-key` | Yes | The API key provided by GenLogs. | #### Query Parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `usdot_number` | string | Yes | Carrier USDOT number. If missing or empty, the request returns `400`. | | `vin` | string | No | A vehicle VIN. When supplied, the `vin_details` section is populated with inspection, crash, and violation history for that VIN. When omitted, `vin_details` is `null` (no eager fetch). | #### Request Example ```bash curl --location \ "https://api.genlogs.io/carrier/profile/fmcsa?usdot_number=445219" \ --header "x-api-key: YOUR_API_KEY" \ --header "Access-Token: YOUR_ACCESS_TOKEN" ``` ### Response * **200 OK:** A JSON object containing the aggregated carrier profile. A `200` is returned even when some sections fail — see Partial failures. * **400 Bad Request:** `usdot_number` is missing or empty. * **401 Unauthorized:** The `Access-Token` is missing or invalid. * **403 Forbidden:** The `Access-Token` is expired. * **500 Internal Server Error:** An unexpected error occurred while assembling the profile. #### Response Body The top-level object is a `CarrierFMCSAProfile`. Each section resolves independently; a section that fails or is permission-gated is `null`, with details in `errors`. | Field | Type | Description | | ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `dot_number` | string | The carrier USDOT number the profile was built for. | | `operating_status` | object | DOT status & safety rating, FMCSA authorizations (common / contract / broker), MCS-150 details, and active certifications. | | `authority_history` | object | Carrier history snapshots (power units, drivers, mileage over time) and authority action history. | | `oos` | object | Full safety payload: summary ISS score, BASIC scores, major/severe violation counts, crash summary, and OOS rates. See `oos`. | | `insurance` | object | Active insurance (BIPD, cargo, bond) and insurance-history summary. | | `iss_basics` | object | Detailed ISS + BASIC breakdown (header, tab summary, time-series chart, violation summary & history). Permission-gated. See `iss_basics`. | | `violations` | object | Violation counts by severity bucket and per-violation rows. | | `crashes` | object | Crash counts by severity and per-crash rows. | | `fleet_and_drivers` | object | Fleet overview (tractors / trailers), driver summary, cargo carried, and fleet age. | | `vin_details` | object | VIN-level inspection, crash, and violation history. Only present when the `vin` query parameter is supplied; otherwise `null`. | | `errors` | object | Map of section name → `{ message, type }` for any section that failed or was permission-gated. `null` when no section errored. | **`oos`** The safety section. The summary `iss_score` is always present; `risk_score`, `risk_tier`, and `risk_score_date` require `external-api-genlogs-review-score`. | Field | Type | Description | | ----------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iss_score` | number | Summary Inspection Selection System (ISS) score. Always returned. | | `basic_scores` | object | The seven FMCSA BASIC categories (`unsafe_driving`, `hours_of_service`, `driver_fitness`, `controlled_substances`, `vehicle_maintenance`, `hazmat_related`, `crash_indicator`), each with `score`, `measure`, and `is_escalate`. | | `major_and_severe_violations` | object | `{ most_severe_violations_count, major_violations_count }`. | | `crash_information` | object | `{ crash_count, injuries, fatalities }`. | | `oos_scores` | object | Out-of-service rates: `overall`, `driver`, `vehicle`, and `hazmat`. Each detail entry has `percent_oos`, `total_oos`, `total_inspected`, and `national_avg`. | | `risk_score` | number \| null | GenLogs review score. Requires `external-api-genlogs-review-score`. | | `risk_tier` | string \| null | GenLogs review-score tier. Requires `external-api-genlogs-review-score`. | | `risk_score_date` | string \| null | Date the review score was computed. Requires `external-api-genlogs-review-score`. | **`iss_basics`** The detailed ISS + BASIC section. Present only when the token holds `external-api-carrier-iss-score`. | Field | Type | Description | | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `header` | object | `{ score, status, measure, recommendation, show_score }` — the headline ISS figure and recommendation. | | `tab_summary` | array | Per-BASIC summary rows: `{ category, title, percentage, measure, status, is_escalate }`. | | `chart` | object | ISS time series: `data`, `labels`, `date_range`, `group_median`, `may_measure`, `point_classifications`, `has_established_median`. | | `violation_summary` | array | Violation summary rows: `{ weight, category, total, out_of_service }`. | | `violation_history` | array | Individual violation entries (date, code, description, weights, etc.). | | `current_fleet_vins` | array | Normalized VINs currently in the carrier's fleet. | | `risk_score` | number \| null | GenLogs review score. Requires `external-api-genlogs-review-score`. | | `risk_tier` | string \| null | GenLogs review-score tier. Requires `external-api-genlogs-review-score`. | | `risk_score_date` | string \| null | Date the review score was computed. Requires `external-api-genlogs-review-score`. | #### Example Response > Illustrative example for `usdot_number=445219`, using a token that holds both `external-api-carrier-iss-score` and `external-api-genlogs-review-score`. Values are representative. ```json { "dot_number": "445219", "operating_status": { "dot_status": { "rating_date": "2021-08-12", "dot_status": "ACTIVE", "dot_safety_rating": "SATISFACTORY" }, "authorization": { "common_authority": "ACTIVE", "common_authority_date": "2009-03-01", "contract_authority": "ACTIVE", "contract_authority_date": "2009-03-01", "broker_authority": "NONE", "broker_authority_date": null }, "mc_150_details": { "last_update": "2024-11-02", "operations_classification": ["AUTHORIZED FOR HIRE"], "transport_hazmat": "N" }, "mc_150_carrier_history": { "last_snapshot_date": "2025-05-01" }, "active_certifications": { "active_certifications": ["Common", "Contract"] } }, "authority_history": { "carrier_history": [ { "snapshot_date": "2025-05-01", "mcs150_date": "2024-11-02", "power_units": 42, "drivers": 40, "mileage": 5120000, "power_units_change_pct": 5.0, "drivers_change_pct": 2.6, "mileage_change_pct": 3.1 } ], "authority_history": [ { "authority_type": "Common", "original_action": "GRANTED", "action_date": "2009-03-01", "disposition_action": null, "disposition_date": null } ], "authority_history_count": 1 }, "oos": { "iss_score": 62, "basic_scores": { "unsafe_driving": { "score": 35, "measure": 1.2, "is_escalate": false }, "hours_of_service": { "score": 48, "measure": 2.0, "is_escalate": false }, "driver_fitness": { "score": 12, "measure": 0.3, "is_escalate": false }, "controlled_substances": { "score": 0, "measure": 0.0, "is_escalate": false }, "vehicle_maintenance": { "score": 71, "measure": 3.4, "is_escalate": true }, "hazmat_related": { "score": null, "measure": null, "is_escalate": null }, "crash_indicator": { "score": 22, "measure": 0.8, "is_escalate": false } }, "major_and_severe_violations": { "most_severe_violations_count": 3, "major_violations_count": 11 }, "crash_information": { "crash_count": 2, "injuries": 1, "fatalities": 0 }, "oos_scores": { "overall": { "percent_oos": 18.5, "total_oos": 12, "total_inspected": 65 }, "driver": { "percent_oos": 4.1, "total_oos": 2, "total_inspected": 49, "national_avg": 5.5 }, "vehicle": { "percent_oos": 24.3, "total_oos": 10, "total_inspected": 41, "national_avg": 22.0 }, "hazmat": { "percent_oos": 0.0, "total_oos": 0, "total_inspected": 0, "national_avg": 4.5 } }, "risk_score": 0.73, "risk_tier": "Medium", "risk_score_date": "2025-05-01" }, "insurance": { "active_insurance": { "boc_3_filing_company_name": "Acme Process Agents LLC", "bipd_primary_status": "ACTIVE", "bipd_primary_insurance_on_file": "1000000", "cargo_status": "ACTIVE", "cargo_insurance_on_file": "100000", "bond_status": "NONE", "bond_insurance_on_file": null }, "insurance_history": { "same_carrier_3plus_years": true, "count": 4 } }, "iss_basics": { "header": { "score": "62", "status": "Optional", "measure": "ISS-2", "recommendation": "Optional", "show_score": true }, "tab_summary": [ { "category": "vehicle_maintenance", "title": "Vehicle Maintenance", "percentage": "71%", "measure": "3.40", "status": "Alert", "is_escalate": true } ], "chart": { "data": [58.0, 60.0, 62.0], "labels": ["2025-03", "2025-04", "2025-05"], "date_range": { "start_date": "2025-03-01", "end_date": "2025-05-01" }, "group_median": [55.0, 56.0, 57.0], "may_measure": 62.0, "point_classifications": null, "has_established_median": true }, "violation_summary": [ { "weight": "7", "category": "Vehicle Maint.", "total": "10", "out_of_service": "10" } ], "violation_history": [], "current_fleet_vins": ["1FUJGLDR8CSBP1234", "3AKJGLDR8CSBP5678"], "risk_score": 0.73, "risk_tier": "Medium", "risk_score_date": "2025-05-01" }, "violations": { "major_violations_count": 11, "most_severe_violations_count": 3, "less_severe_violations_count": 27, "rows": [ { "date": "2025-02-14", "number": "INS123456", "vin": "1FUJGLDR8CSBP1234", "violation_description": "Brake hose/tubing chafing and/or kinking", "state": "OH", "plate_number": "PXY1234", "plate_state": "OH", "severity_weight": 4, "severity_bucket": "major" } ] }, "crashes": { "major_crashes_count": 2, "most_severe_crashes_count": 0, "rows": [ { "date": "2024-09-03", "report_number": "OH20240903", "vin": "1FUJGLDR8CSBP1234", "location": "I-70 MM 110", "state": "OH", "plate_number": "PXY1234", "plate_state": "OH", "fatalities": 0, "injury": 1, "towaway": "Y", "preventable": "U", "severity_weight": 2, "severity_bucket": "major" } ] }, "fleet_and_drivers": { "fleet_overview": { "total_fleet": 64, "tractors": { "total_count": 42, "owned_count": 38, "leased_count": 4 }, "trailers": { "total_count": 22, "owned_count": 20, "leased_count": 2 } }, "drivers": { "driver_count": 40, "cdl_total_miles": 5120000 }, "cargo_carried": ["General Freight", "Building Materials"], "fleet_age": { "total_tractor_count": 42, "avg_age_years": 6, "oldest_unit_year": 2012, "newest_unit_year": 2024 } }, "vin_details": null, "errors": null } ``` ### Partial failures Each section is resolved independently and concurrently. If a section fails, its field is set to `null` and a structured entry is added to the `errors` map; the request still returns `200`. The `type` reflects the cause (for example `TimeoutError`, `NotFoundError`, or `PermissionError`). ```json { "dot_number": "445219", "operating_status": { "...": "..." }, "insurance": null, "errors": { "insurance": { "message": "timeout", "type": "TimeoutError" } } } ``` #### Permission-gated example When the token lacks `external-api-carrier-iss-score`, the `iss_basics` section is withheld and reported in `errors`. The summary `oos.iss_score` is still returned. ```json { "dot_number": "445219", "oos": { "iss_score": 62, "...": "..." }, "iss_basics": null, "errors": { "iss_basics": { "message": "Missing required permission: external-api-carrier-iss-score", "type": "PermissionError" } } } ``` When the token lacks `external-api-genlogs-review-score`, the `risk_score`, `risk_tier`, and `risk_score_date` fields are returned as `null` on both `oos` and `iss_basics`; no `errors` entry is added. ### Status codes | Code | Meaning | | ----- | ------------------------------------------------------------------------------------ | | `200` | Success — including partial responses where some sections are `null` (see `errors`). | | `400` | `usdot_number` is missing or empty. | | `401` | `Access-Token` is missing or invalid. | | `403` | `Access-Token` is expired. | | `500` | Unexpected error while assembling the profile. |