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.