# Carrier Profile ### 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): One or more USDOT numbers, separated by commas. * **start\_date** (string, optional): Start date for filtering USDOT sightings (up to 3 years ago). * **end\_date** (string, optional): End date for filtering USDOT sightings (cannot exceed the current date). ### Understanding carrier profile information {% hint style="info" %} 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. {% endhint %} **Carrier Profile returns three arrays per USDOT.** * **FMCSA Detail**: FMCSA details with equipment pairings and USDOT sightings for specified carriers * **usdot\_number**: (string) The USDOT number for the carrier. * **docket\_numbe**r: (string) The Motor Carrier number for carriers involved in interstate. * **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) It is a unique nine-digit number assigned by the IRS to identify the carrier for tax purposes. * **dun\_bradstreet\_no**: (string) It is 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**)** The 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 insurance 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 of insurance 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\_classificiation**: (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 that resulted in an out-of-service (OOS) order. * **carrier\_driver\_oos\_rate**: (number) The percentage of driver inspections that resulted in an 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 that resulted in an OOS order. * **carrier\_vehicle\_oos\_rate**: (number) The percentage of vehicle inspections that resulted in an 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 that resulted in an OOS order. * **carrier\_hazmat\_oos\_rate**: (number) The percentage of hazardous materials inspections that resulted in an 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 drug 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) is 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: ``` 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}' ``` ## Get carrier profile details > Retrieve a comprehensive carrier profile details including FMCSA details, equipment pairings, and sightings data for specified USDOT numbers.
```json {"openapi":"3.0.3","info":{"title":"Carrier Profile API","version":"1.0.0"},"paths":{"carrier/profile":{"get":{"summary":"Get carrier profile details","description":"Retrieve a comprehensive carrier profile details including FMCSA details, equipment pairings, and sightings data for specified USDOT numbers.\n","operationId":"getCarrierProfileDetail","parameters":[{"in":"header","name":"Access-Token","required":true,"schema":{"type":"string"},"description":"Bearer token for authentication"},{"in":"query","name":"usdot_number","required":true,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"USDOT numbers to filter data for specific carriers"},{"in":"query","name":"start_date","required":false,"schema":{"type":"string","format":"date"},"description":"Start date for sightings in YYYY-MM-DD format"},{"in":"query","name":"end_date","required":false,"schema":{"type":"string","format":"date"},"description":"End date for sightings in YYYY-MM-DD format"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"fmcsa_detail":{"$ref":"#/components/schemas/FmcsaDetail"},"equipment_pairings":{"$ref":"#/components/schemas/EquipmentPairings"},"sightings":{"type":"array","items":{"$ref":"#/components/schemas/Sighting"}}}}}}}},"400":{"description":"Bad Request - invalid parameters","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"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"FmcsaDetail":{"type":"object","properties":{"usdot_number":{"type":"string"},"legal_name":{"type":"string"},"dba_name":{"type":"string"},"entity_type":{"type":"string"},"carrier_operation":{"type":"string"},"cargo_carried":{"type":"string"},"hazmat_authorized":{"type":"string"},"carrier_status":{"type":"string"},"out_of_service_date":{"type":"string"},"legal_address":{"type":"string"},"physical_address":{"type":"string"},"mailing_address":{"type":"string"},"telephone":{"type":"string"},"fax":{"type":"string"},"email":{"type":"string"},"mcs_150_form_date":{"type":"string","format":"date"},"mcs_150_mileage_year":{"type":"string"},"dot_number":{"type":"string"},"docket_number":{"type":"string"},"mc_mx_ff_number":{"type":"string"},"power_units":{"type":"string"},"drivers":{"type":"string"},"mcs_150_mileage":{"type":"string"}}},"EquipmentPairings":{"type":"object","properties":{"genlogs":{"type":"array","items":{}},"fmcsa":{"type":"array","items":{}}}},"Sighting":{"type":"object","description":"A single sighting record for a carrier location/date.","properties":{"sighting_date":{"type":"string","format":"date"},"state_seen":{"type":"string"},"location_zip":{"type":"string"},"sightings":{"type":"integer","description":"Count of sightings for this location/date."},"source":{"type":"string","description":"Data source of the sighting (e.g. visual, api)."}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer","format":"int32"}},"required":["message","code"]}}}} ```