# Carrier Recommendations ### Carrier Recommendations Endpoint Retrieve a list of recommended carriers operating near an origin, destination, or on a specified lane. ### **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-recommendation` permission is required to access this endpoint. ### **Endpoint** * **URL:** `https://api.genlogs.io/carrier/recommendations` * **Method:** `GET` ### **Headers** * **Access-Token**: `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 ### **Query Parameters:** {% hint style="info" %} The GenLogs **`carrier_score`** indicates the likelihood of a carrier meeting the specific needs of a given search query. It is a composite score based on a blend of lane, equipment, and company match factors. * Lane Factors (lane\_score): Likelihood to be seen at an origin, destination, or along a lane (O/D pairing) * Equipment Factors (equipment\_type\_score): Likelihood to have the requested equipment type * Company factors (company\_score): compliance, safety, maintenance, and insurance metrics {% endhint %} * [**origin\_city** (string, optional): Name of the origin city. Note that townships and counties are not accepted.](#user-content-fn-1)[^1] * [**origin\_state** (string, optional): Full name or two-letter abbreviation of the origin state.](#user-content-fn-1)[^1] * [**destination\_city** (string, optional): Name of the destination city. Note that townships and counties are not accepted.](#user-content-fn-1)[^1] * [**destination\_state** (string, optional): Full name or two-letter abbreviation of the destination state.](#user-content-fn-1)[^1] * **origin\_radius** (int, optional): Radius (miles) around the origin location for carrier search - default 50 miles (max. 100 miles). * **destination\_radius** (int, optional): Radius (miles) around the destination location for carrier search - default 50 miles (max. 100 miles). * **carrier\_score\_min** (float, optional): Minimum acceptable carrier score - default to 0. * Accepts values between 0 and 1 * **carrier\_score\_max** (float, optional): Maximum acceptable carrier score - default to 1 * Accepts values between 0 and 1. Generally, we recommend omitting this parameter * **fleet\_size\_min** (number, optional): Minimum fleet size of carriers - default 0 power units * **fleet\_size\_max** (number, optional): Maximum fleet size of carriers - default 1000 power units * **preferred\_carriers:** (boolean, optional): Only return carriers that match your Onboarded Carrier list, as configured in the web application. * **auth\_months\_min** (number, optional, default=1): Minimum number of months a carrier has an active common or contract authority with FMCSA * **power\_only** (boolean, optional): Filters carriers that operate tractors without owning trailers. * **broker\_authority** (boolean, optional): Filters carriers that also have a brokerage arm. * **carried\_cargo** (string, optional): Type of cargo registered to carried., Possible values:
Carried Cargo options: * Passengers * Garbage/Refuse * Mobile Homes * Drive/Tow away * Water Well * Livestock * Utilities * Agricultural/Farm Supplies * General Freight * Household Goods * US Mail * Beverages * Paper Products * Fresh Produce * Meat * Refrigerated Food * Metal: sheets, coils rolls * Logs, Poles, Beams, Lumber * Building Materials * Machinery, Large Objects * Oilfield Equipment * Construction * Liquids/Gases * Chemicals * Motor Vehicles * Grain Feed Hay * Coal/Coke * Commodities Dry Bulk * Intermodal Cont.
* **equipment\_types** (case sensitive string, optional): A list of equipment types and subtypes used by the carrier. You may list multiple values using a pipe (“|”) delimiter. You can specify a subtype by naming the parent class and child class separated by a colon. The scheme is Type 1: Subtype 1 | Type 2: Subtype 2 | Type 3: Subtype 3. * Examples: * equipment\_types: Dry Van | Box Truck * equipment\_types: Dry Van: Double Pup | Box Truck | Flatbed: Step deck | Flatbed: Lowboy RGN
Equipment type options | Equipment Type | Subtype (Optional) | | -------------- | -------------------- | | Dry Van | Moffett | | Dry Van | Drop Frame | | Dry Van | Double Pup | | Reefer | Moffett | | Flatbed | Step Deck | | Flatbed | Moffett | | Flatbed | Lowboy RGN | | Flatbed | Logging | | Flatbed | Gooseneck | | Flatbed | Conestoga | | Flatbed | Air Ride | | Flatbed | 53 Ft Flatbed | | Box Truck | | | Car Hauler | Gooseneck | | Dry Bulk | Hopper | | Dry Bulk | Air Ride | | Dry Bulk | Agricultural | | Dump | Side Dump | | Dump | Open Top | | Dump | End Dump | | Dump | Belly Dump | | Intermodal | Gooseneck | | Power Unit | Sleeper Cab | | Power Unit | Day Cab | | Tanker | Vacuum Tank | | Tanker | Steel | | Tanker | Cryogenic | | Tanker | Compressed Gas | | Tanker | Chemical | | Tanker | Aluminum | | Other | Wrecker | | Other | Livestock Trailer | | Other | High Tonnage Trailer |
* **preferred\_carriers:** (boolean, optional): Only return carriers marked as preferred. * **auth\_months\_min** (float, optional, default=1.0): Minimum number of months a carrier has an active common or contract authority with FMCSA * **power\_only** (boolean, optional): Filters carriers that operate tractors without owning trailers. * **broker\_authority** (boolean, optional): Filters carriers that have an active broker authority or not. ### Search Tips #### **Perform and origin- or destination-only search** **Origin-only search** * Provide `origin_city` and `origin_state`. * You no longer need to include `destination_city` or `destination_state` as `null`. * You may omit `destination_radius` if it is not relevant. **Destination-only search** * Provide `destination_city` and `destination_state`. * You no longer need to include `origin_city` or `origin_state` as `null`. * You may omit `origin_radius` if it is not relevant. **General rule** Origin-only and destination-only searches are valid. You do **not** need to send all four parameters at the same time, and you no longer need to provide the unused city/state pair with `null` values. {% hint style="info" %} *Note: If you receive a bad request, make sure to omit the **origin\_radius** or **destination\_radius** field.* {% endhint %} #### Understanding contact information **Carrier Recommendations returns two sets of contact information: Onboarded Carrier fields and FMCSA fields.** * Onboarded Carrier fields: these values are provided by your Onboarded Carrier list, which admins can update in our UI. If no values are uploaded, they will be blank. * contact\_email * contact\_name * contact\_phone * FMCSA fields: these contact values are provided from the FMCSA. They are shown exactly as registered, including possible null values, multiple semicolon separated values, or values with typos. * telephone * email\_address ### **Response:** * **200 OK:** A JSON object containing recommendations and lane volume details. * **400 Bad Request:** If required parameters are missing or invalid. * **401 Unauthorized:** If the authentication credentials (email and password) are missing or incorrect. * **403 Forbidden**: Access to the requested resource is forbidden. * **500 Internal Server Error:** If there is an issue on the server that prevents processing the request. ### **Response Body:** * **recommendations** (array of `CarrierRecommendation` objects): List of recommended carriers. * **add\_date** (string): Date the recommendation was added. * **auth\_months** (number): Duration of the carrier’s authority in months. * **authorized\_for\_hire** (string): Indicates if the carrier is authorized for hire (Y/N). * **bipd\_insurance\_on\_file** (number): Amount of Bodily Injury and Property Damage insurance on file (in US dollars). * **broker\_authority\_status** (string): Indicates if the carrier has broker authority status * A = Holds Active Authority * I = Inactive Authority * N = No Authority * **cargo\_insurance\_on\_file** (number): Amount of cargo insurance on file (in US dollars). * **carried\_cargo** (string): Type of cargo carried by the carrier. * **carrier\_assessment** (string): Assessment or notes about the carrier. * **carrier\_driver\_oos\_rate** (number): Carrier’s driver Out-of-Service (OOS) rate. * **carrier\_driver\_oos\_rate\_national\_avg** (number): National average OOS rate for drivers. * **carrier\_ein** (number): Employer Identification Number (EIN) of the carrier. * **carrier\_score** (number): GenLogs proprietary carrier match score, incidating the likelihood of a carrier meeting the specific needs of a given search query. **Carrier\_score** is composed of **company\_score**, **equipment\_type\_score**, and **lane\_score**. * **carrier\_score\_scaled** (number): The carrier\_score on a scaled basis, with the best carrier for the lane scaling to 100%. Note that this is the score shown in our UI. * **carrier\_total\_power\_units** (number): Total power units operated by the carrier. * **carrier\_vehicle\_oos\_rate** (number): Carrier’s vehicle OOS rate. * **carrier\_vehicle\_oos\_rate\_national\_avg** (number): National average OOS rate for vehicles. * **classdef** (string): Classification of the carrier’s operation. * **company\_score** (number): Score representing the carrier’s company performance or reliability. * **confirmed\_email** (object): List of available emails. * ```json { "safety@zipzap-logistics.com": { "add_date": "2025-09-29" }, "safety2@zipzap-logistics.com": { "add_date": "2025-09-29" }, ... } ``` * **confirmed\_phone** (object): List of available phone numbers. * ```json { "1-619-963-1591": { "add_date": "2025-09-29" }, "1-123-456-7890": { "add_date": "2025-09-29" }, ... } ``` * **contact\_email** (string): Email address of the carrier, provided by your Onboarded Carrier upload. * **contact\_name** (string): Contact name of the carrier, provided by your Onboarded Carrier upload. * **contact\_phone** (string): Phone number of the carrier, provided by your Onboarded Carrier upload. * **dba\_name** (nullable string): Doing Business As (DBA) name of the carrier. * **dot\_number** (string): DOT number of the carrier. * **driver\_total** (number): Total number of drivers employed by the carrier. * **email\_address** (string): FMCSA listed email address. * **equipment\_type\_score** (number): Score representing the suitability of the carrier’s equipment types. * **equipment\_types** (string): Types of equipment operated by the carrier. * **exempt\_for\_hire** (string): Indicates if the carrier is exempt from for-hire regulations (Y/N). * **federal\_government** (string): Indicates if the carrier is a federal government entity (Y/N). * **indian\_tribe** (string): Indicates if the carrier is an Indian tribe entity (Y/N). * **is\_possible\_backhaul** (boolean): Indicates if the specified lane is a possible backhaul for the carrier based on their domicile address. * **is\_power\_only** (boolean): Carriers that operate tractors without owning trailers according to FMCSA records. * **is\_preferred** (boolean): Whether the carrier has been marked as preferred or not. * **is\_visually\_sighted** (boolean): Whether the carrier has been visually sighted. * **lane\_score** (number): Score representing the suitability of the carrier for a specific lane. * **lat** (nullable number): Latitude of the FMCSA registered address. * **legal\_name** (string): Legal name of the carrier. * **local\_government** (string): Indicates if the carrier is a local government entity (Y/N). * **lon** (nullable number): Longitude of the FMCSA registered address. * **mc\_number** (number): Motor Carrier (MC) number of the carrier. * **mcs150\_date** (string): Date of the carrier’s MCS-150 form submission. * **mcs150\_mileage** (number): Annual mileage reported on the carrier’s MCS-150 form. * **mcs150\_mileage\_year** (number): Year of the mileage reported on the carrier’s MCS-150 form. * **migrant** (string): Indicates if the carrier transports migrant workers (Y/N). * **name** (string): Name of the carrier, often matching the legal name. * **op\_other** (string): Indicates if the carrier has other operational classifications (Y/N). * **operation\_classification** (string): Classification of the carrier’s operational authority according to the FMCSA (e.g. AUTHORIZED FOR HIRE). * **phy\_city** (string): City of the carrier's domicile address. * **phy\_state** (string): State of the carrier's domicile address. * **phy\_street** (string): Street address of the carrier's domicile address. * **phy\_zip** (string): City of the carrier's domicile address. * **private\_only** (string): Carriers that are not for-hire, whose authority is solely for their own commercial enterprise, not available to the public at large (Y/N). * **private\_passenger\_business** (string): Indicates if the carrier transports private passengers for business (Y/N). * **private\_passenger\_nonbusiness** (string): Indicates if the carrier transports private passengers for non-business purposes (Y/N). * **private\_property** (string): Indicates if the carrier transports private property (Y/N). * **state\_government** (string): Indicates if the carrier is a state government entity (Y/N). * **telephone** (string): FMCSA listed telephone number. * **us\_mail** (string): Indicates if the carrier transports U.S. mail (Y/N). ### Request Example: ## GET /carrier/recommendations > Get carrier recommendations based on location ```json {"openapi":"3.0.2","info":{"title":"Carrier API","version":"1.0.1"},"servers":[{"url":"https://api.genlogs.io"}],"paths":{"/carrier/recommendations":{"get":{"parameters":[{"name":"accept","in":"header","required":true,"schema":{"type":"string","default":"application/json"},"description":"Specifies the format of the response."},{"name":"Access-Token","in":"header","required":true,"schema":{"type":"string"},"description":"Access Token for authentication"},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"API key for authentication"},{"in":"query","name":"origin_city","required":true,"schema":{"type":"string","default":"Nashville"},"description":"Origin city for the recommendation"},{"in":"query","name":"origin_state","required":true,"schema":{"type":"string","default":"TN"},"description":"Origin state for the recommendation"},{"in":"query","name":"destination_city","required":true,"schema":{"type":"string","default":"Dallas"},"description":"Destination city for the recommendation"},{"in":"query","name":"destination_state","required":true,"schema":{"type":"string","default":"TX"},"description":"Destination state for the recommendation"},{"default":50,"in":"query","name":"origin_radius","schema":{"type":"number","default":50},"description":"Search radius around the origin location in miles"},{"default":50,"in":"query","name":"destination_radius","schema":{"type":"number","default":50},"description":"Search radius around the destination location in miles"},{"default":0,"in":"query","name":"carrier_score_min","schema":{"type":"float","default":0},"description":"Minimum carrier score"},{"default":100,"in":"query","name":"carrier_score_max","schema":{"type":"float","default":1},"description":"Maximum carrier score"},{"default":"None","in":"query","name":"fleet_size_min","schema":{"type":"number"},"description":"Minimum fleet size"},{"default":"None","in":"query","name":"fleet_size_max","schema":{"type":"number"},"description":"Maximum fleet size"},{"in":"query","name":"carried_cargo","schema":{"type":"string","default":"general goods"},"description":"Type of cargo carried"},{"in":"query","name":"equipment_types","schema":{"type":"string","default":"flatbed"},"description":"Type of equipment used by carriers"},{"in":"query","name":"preferred_carriers","schema":{"type":"boolean","default":false},"description":"Filter for preferred carriers"},{"in":"query","name":"real_time","schema":{"type":"boolean","default":false},"description":"Request real-time data if available"},{"in":"query","name":"auth_months_min","schema":{"type":"number","default":1},"description":"Minimum number of months a carrier has an active common or contract authority with FMCSA"},{"in":"query","name":"power_only","schema":{"type":"boolean","default":false}},{"in":"query","name":"broker_authority","schema":{"type":"boolean","default":false}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarrierResponse"}}},"description":"The JSON response containing recommendations and lane volume"}},"summary":"Get carrier recommendations based on location"}}},"components":{"schemas":{"CarrierResponse":{"properties":{"real_time_locs":{"items":{"$ref":"#/components/schemas/CarrierRealTimeLocs"},"type":"array"},"recommendations":{"items":{"$ref":"#/components/schemas/CarrierRecommendation"},"type":"array"}},"required":["real_time_locs","recommendations"],"type":"object"},"CarrierRealTimeLocs":{"properties":{"current_lat":{"nullable":true,"type":"number"},"current_lon":{"nullable":true,"type":"number"},"dot_number":{"type":"string"},"is_inbound":{"type":"boolean"}},"required":["dot_number","is_inbound"],"type":"object"},"CarrierRecommendation":{"properties":{"add_date":{"type":"string"},"bipd_insurance_on_file":{"type":"number"},"cargo_insurance_on_file":{"type":"number"},"carried_cargo":{"type":"string"},"carrier_driver_oos_rate":{"type":"number"},"carrier_driver_oos_rate_national_avg":{"type":"number"},"carrier_score_scaled":{"type":"number"},"carrier_total_power_units":{"type":"number"},"carrier_vehicle_oos_rate":{"type":"number"},"carrier_vehicle_oos_rate_national_avg":{"type":"number"},"confirmed_email":{"type":"object","properties":{"":{"type":"object","properties":{"add_date":{"type":"string"}}}}},"confirmed_phone":{"type":"object","properties":{"":{"type":"object","properties":{"add_date":{"type":"string"}}}}},"dba_name":{"nullable":true,"type":"string"},"dot_number":{"type":"string"},"email_address":{"type":"string"},"is_inbound":{"type":"boolean"},"is_real_time":{"type":"boolean"},"is_visually_sighted":{"type":"boolean"},"is_possible_backhaul":{"type":"boolean"},"lat":{"nullable":true,"type":"number"},"legal_name":{"type":"string"},"lon":{"nullable":true,"type":"number"},"mc_number":{"type":"number"},"phy_city":{"type":"string"},"phy_state":{"type":"string"},"phy_street":{"type":"string"},"phy_zip":{"type":"string"},"telephone":{"type":"string"},"power_only":{"type":"boolean"},"broker_authority_status":{"type":"string"}},"required":["add_date","bipd_insurance_on_file","cargo_insurance_on_file","carried_cargo","carrier_driver_oos_rate","carrier_driver_oos_rate_national_avg","carrier_score_scaled","carrier_total_power_units","carrier_vehicle_oos_rate","carrier_vehicle_oos_rate_national_avg","confirmed_email","confirmed_phone","dot_number","email_address","is_inbound","is_real_time","is_visually_sighted","legal_name","mc_number","phy_city","phy_state","phy_street","phy_zip","telephone"],"type":"object"}}}} ``` [^1]: Requests can include all location parameters, but only one set is required. You may provide either **origin\_city** and **origin\_state**, or **destination\_city** and **destination\_state**. If neither set is included, the API will return a *400 Bad Request* error:\ `{"error": "At least one of origin or destination are required."}` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.genlogs.io/carrier/recommendations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.