### 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:

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.

- **origin_city** (string, optional): Name of the origin city. Note that townships and counties are not accepted.
- **origin_state** (string, optional): Full name or two-letter abbreviation of the origin state.
- **destination_city** (string, optional): Name of the destination city. Note that townships and counties are not accepted.
- **destination_state** (string, optional): Full name or two-letter abbreviation of the destination state.
- **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.
- **carrier_score_max** (float, optional): Maximum acceptable carrier score - default to 1.
- **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.
- **auth_months_min** (number, optional): 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.
- **is_possible_backhaul** (boolean, optional): Filters to only return carriers where the specified lane is a possible backhaul.
- **carried_cargo** (string, optional): Type of cargo registered to carried.

Carried Cargo options:
- Passengers
- Garbage/Refuse
- Mobile Homes
- Drive/Tow away
- Water Well
- Livestock
- Utilities
- Agricultural/Farm Supplies
- General Freight

Examples of equipment types: 
- **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.

### Search Tips

**Perform an origin- or destination-only search**

- **Origin-only search**: Provide `origin_city` and `origin_state`.
- **Destination-only search**: Provide `destination_city` and `destination_state`.

### 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 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.
  - **email_address** (string): FMCSA listed email address.
  - **telephone** (string): FMCSA listed telephone number.
  - **carrier_score** (number): GenLogs proprietary carrier match score.

### Request Example:

```
GET /carrier/recommendations?origin_city=Tennessee+City&origin_state=Tennessee&destination_city=Tascosa&destination_state=Texas HTTP/1.1
Host: api.genlogs.io
accept: application/json
Access-Token: [Token]
x-api-key: [x-api-key]
```