[ACTION REQUIRED: Create Token now requires JSON body credentials. Update by Sep 30 - see migration steps here:](https://help.genlogs.io/en/articles/15888388-updating-your-create-token-setup)

For the complete documentation index, see [llms.txt](https://docs.genlogs.io/llms.txt). This page is also available as [Markdown](https://docs.genlogs.io/carrier/carrier-profile.md).

# Carrier Profile Endpoint

Retrieve **FMCSA** details, **Equipment Pairings**, and **USDOT Sightings** for one or more carriers, with optional date filters for sightings.

## 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
The `external-api-carrier-profile` permission is required to access this endpoint.

## Endpoint
- **URL:** `https://api.genlogs.io/carrier/profile`
- **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_numbers** ( _string, required, max = 50_): One or more USDOT numbers, separated by commas; _e.g. "123456,987654"._
- **start_date** ( _string, optional_): Start date for filtering USDOT sightings (up to 3 years ago); _e.g. "2026-02-20"._
- **end_date** ( _string, optional_): End date for filtering USDOT sightings (cannot exceed the current date); _e.g. "2026-02-21"._

## Understanding carrier profile information
Responses are always grouped by **USDOT**, and within each USDOT you may find:
- **FMCSA Detail** – always present.
- **Equipment Pairings** – may be empty depending on the available information.
- **USDOT Sightings** – may be empty depending on the filters applied.

---

This means that while **FMCSA Detail** is guaranteed for every USDOT, the **Pairing Data** and **Sightings** sections may not return results if they do not match the requested filters.

**Carrier Profile returns three arrays per USDOT.**

### FMCSA Detail
- **usdot_number**: (string) The USDOT number for the carrier.
- **docket_number**: (string) The Motor Carrier number for carriers involved in interstate commerce.
- **legal_name**: (string) The official registered name of the carrier.
- **dba_name**: (string) The "Doing Business As" name, if applicable.
- **carrier_status**: (string) Indicates whether the carrier is active, inactive, or has a pending status.
- **entity_status**: (string) Refers to the legal standing of the carrier's business entity.
- **carrier_ein**: (string) Unique nine-digit number assigned by the IRS to identify the carrier for tax purposes.
- **dun_bradsheet_no**: (string) A unique identifier assigned by Dun & Bradstreet to businesses.
- **mcs150_date**: (string) The date when the carrier last updated their MCS-150 form (Motor Carrier Identification Report).
- **mcs150_mileage**: (string) Total mileage reported by the carrier on their MCS-150 form, typically for the previous year.
- **insurer_company_name**: (string) The name of the insurance company providing coverage for the carrier.
- **insurance_docket_number**: (string) A unique identifier for the insurance filing associated with the carrier.
- **insurance_policy_number**: (string) The policy number assigned by the insurer to the carrier's policy.
- **insurance_policy_type**: (string) Specifies the type of insurance policy (e.g., liability, cargo, etc.).
- **insurance_form_code**: (string) A code representing the type of insurance form filed (e.g., BMC-91 for liability insurance).
- **insurance_max_coverage_amount**: (string) The maximum coverage amount provided by the insurance policy.
- **insurance_underlying_limit_amount**: (string) The underlying limit amount, which is the base coverage before additional layers apply.
- **insurance_transaction_date**: (string) The date when the insurance transaction (e.g., filing or update) was processed.
- **insurance_effective_date**: (string) The start date of the insurance policy.
- **insurance_expiration_date**: (string) The end date of the insurance policy.
- **phy_street**: (string) The street address of the carrier's physical location.
- **phy_city**: (string) The city where the carrier's physical address is located.
- **phy_state**: (string) The state where the carrier's physical address is located.
- **phy_zip**: (string) The ZIP code for the carrier's physical address.
- **telephone**: (string) The carrier's primary contact phone number.
- **email_address**: (string) The carrier's email address for communication.
- **mailing_street**: (string) The street address of the carrier's mailing location.
- **mailing_city**: (string) The city where the carrier's mailing address is located.
- **mailing_state**: (string) The state where the carrier's mailing address is located.
- **mailing_zip**: (string) The ZIP code for the carrier's mailing address.
- **mailing_country**: (string) The country of the carrier's mailing address.
- **carrier_operation**: (string) Describes the type of operations the carrier is authorized to perform (e.g., interstate, intrastate, hazardous materials).
- **operation_classification**: (string) Specifies the classification of the carrier's operations, such as for-hire, private, exempt, or passenger.
- **authority_date**: (string) The date when the carrier's operating authority was granted.
- **authorized_for_common_date**: (string) The date when the carrier was authorized for common carrier operations.
- **authorized_for_contract_date**: (string) The date when the carrier was authorized for contract carrier operations.
- **carrier_total_drivers**: (string) The total number of drivers employed by the carrier.
- **carrier_total_power_units**: (string) The total number of power units (e.g., trucks, tractors) operated by the carrier.
- **carried_cargo**: (string) The types of cargo the carrier is authorized to transport (e.g., general freight, hazardous materials).
- **carrier_driver_insp**: (string) The total number of driver inspections conducted for the carrier.
- **carrier_driver_oos_insp**: (string) The number of driver inspections resulting in out-of-service (OOS) order.
- **carrier_driver_oos_rate**: (number) The percentage of driver inspections resulting in OOS order.
- **carrier_driver_oos_rate_national_avg**: (number) The national average OOS rate for drivers, used for comparison.
- **carrier_vehicle_insp**: (string) The total number of vehicle inspections conducted for the carrier.
- **carrier_vehicle_oos_insp**: (string) The number of vehicle inspections resulting in OOS order.
- **carrier_vehicle_oos_rate**: (number) The percentage of vehicle inspections resulting in OOS order.
- **carrier_vehicle_oos_rate_national_avg**: (number) The national average OOS rate for vehicles, used for comparison.
- **carrier_hazmat_insp**: (string) The total number of hazardous materials inspections conducted for the carrier.
- **carrier_hazmat_oos_insp**: (string) The number of hazardous materials inspections resulting in OOS order.
- **carrier_hazmat_oos_rate**: (number) The percentage of hazardous materials inspections resulting in OOS order.
- **carrier_hazmat_oos_rate_national_avg**: (number) The national average OOS rate for hazardous materials, used for comparison.
- **carrier_fatal_crash**: (string) The total number of fatal crashes involving the carrier.
- **carrier_inj_crash**: (string) The total number of crashes involving injuries for the carrier.
- **carrier_towaway_crash**: (string) The total number of crashes involving towaways for the carrier.
- **carrier_crash_total**: (string) The total number of crashes involving the carrier, including all types of crashes (fatal, injury, and towaway).
- **recordable_crash_rate**: (number) The rate of recordable crashes per million vehicle miles traveled (VMT). This metric helps assess the carrier's safety performance.
- **basic_unsafe_driving_total_violation**: (string) The total number of violations related to unsafe driving (e.g., speeding, reckless driving) recorded for the carrier.
- **basic_driver_fitness_total_violation**: (string) The total number of violations related to driver fitness (e.g., invalid licenses, medical qualifications).
- **basic_hos_total_violation**: (string) The total number of violations related to Hours of Service (HOS) compliance (e.g., exceeding driving time limits, falsifying logs).
- **basic_drugs_alcohol_total_violation**: (string) The total number of violations related to drugs and alcohol use by drivers.
- **basic_vehicle_maint_total_violation**: (string) The total number of violations related to vehicle maintenance (e.g., brake issues, lighting problems).
- **carrier_safety_rating_date**: (string) The date when the carrier's most recent safety rating was issued.
- **carrier_safety_rating**: (string) The carrier's safety rating, which can be one of the following:
  - **Satisfactory**: Meets safety standards.
  - **Conditional**: Does not meet all safety standards but is allowed to operate.
  - **Unsatisfactory**: Fails to meet safety standards and is not allowed to operate.
- **carrier_safety_review_date**: (string) The date when the carrier's most recent safety review was conducted.
- **carrier_safety_review_type**: (string) The type of safety review conducted (e.g., compliance review, safety audit).

### Equipment Pairings
- Equipment pairings for specified carriers, as observed by GenLogs:
  - name: Equipment type name
  - value_percent: Percentage score

### USDOT Sightings
- Retrieves USDOT sightings for specified carriers within a date range:
  - sighting_date: Date when the sighting occurred.
  - state_seen: U.S. state where the sighting was recorded.
  - location_zip: 3-digit ZIP code prefix representing the location of the sighting.
  - sightings: Amount of registered GenLogs sightings.
  - source: The source of the sighting (e.g. "detections").

## Response:
- **200 OK:** A JSON object containing 3 sets of carrier details.
- **400 Bad Request:** If required parameters are missing or invalid.
- **401 Unauthorized:** If the authentication credentials (Access-Token) are missing or incorrect.
- **403 Forbidden**: If the permission has not been added to your user.
- **500 Internal Server Error:** If there is an issue on the server that prevents processing the request.

## Response Body:
- Data (object of `CarrierProfile` objects): Set of carrier profiles grouped by `usdot_number`.

## Request Example:
```bash
curl --location 'https://api.genlogs.io/carrier/profile?usdot_number=2350084%2C10553&start_date=2025-09-01&end_date=2025-09-12' \
--header 'Access-Token: {your-user-token}' \
--header 'x-api-key: {your-x-api-key}'
```