# 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."}`