carrier fmcsa profile.md

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

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.
`external-api-genlogs-review-score`	The GenLogs review score fields — `risk_score`, `risk_tier`, and `risk_score_date` — on both the `oos` and `iss_basics` sections.	Those three fields are returned as `null` (no error entry).

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

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.

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

{
  "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.

{
  "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.