Skip to main content

OTR Quote

Endpoint: POST /v1/otr/quote

Submit shipment details to receive carrier rates for LTL and/or Truckload transportation. The response includes a quoteNumber and a list of carrierQuotes, each with its own rateNumber.

Authentication required. All requests to this endpoint require a valid bearer token. See Authentication.

Request Body​

Core Fields​

These fields are required to submit a complete OTR quote request.

FieldTypeRequiredDescription
customerBsnstringYesBranch identifier for your organization. Retrieve from GET /v1/customers
originobjectYesShipment origin location
destinationobjectYesShipment destination location
UOMstringYesUnit of measure: "US" or "METRIC"
itemsarrayYesList of shipment items
accessorialsarrayYes (may be empty)Additional services requested for the shipment (liftgate, appointment, etc.). This field must always be included in the request body, even when no accessorials are provided. In those cases, send an empty array: [].
modesarrayYesTransportation modes: ["LTL"], ["Truckload"], or both
requestingUserstringYesEmail address of the user submitting the quote request

Origin / Destination Object​

{
  "country": "US",
  "state": "CA",
  "city": "Los Angeles",
  "postalCode": "90001"
}

Field Reference​

Modes​

"modes": ["LTL"]
"modes": ["LTL", "Truckload"]

Accessorials​

Retrieve valid values from GET /v1/tools/otr/accessorials.

Field in responseUse as
accessorialTypeaccessorialType in quote request
accessorialaccessorial in quote request
displayNameInformational only — do not send in request
"accessorials": [
  {
    "accessorial": "Liftgate",
    "accessorialType": "Pickup"
  }
]

LTL vs Truckload accessorial rules​

  • LTL: accessorialType must be "Pickup", "Delivery", or "Shipment"
  • Truckload: accessorialType can be null

This endpoint supports multiple transportation modes, PRIMO strongly recommends submitting requests with a single mode whenever possible to ensure more accurate accessorial validation.

Items​

Each item in the items array represents a commodity in the shipment.

FieldTypeRequiredDescription
itemNamestringYesItem description
packageTypeintegerYesPackage type ID from GET /v1/tools/otr/packages
quantityintegerYesNumber of identical units
weightnumberYesWeight per unit
lengthnumberConditionalRequired for booking; optional if volume is provided
widthnumberConditionalRequired for booking; optional if volume is provided
heightnumberConditionalRequired for booking; optional if volume is provided
volumenumberConditionalRequired when dimensions are omitted
freightClassstringYesFreight class (e.g., "50", "92.5")
levelsintegerYesStack levels (1 if not stackable; 2 or more if stackable)
isHazardousbooleanYesMark true for hazardous materials
isStackablebooleanYesWhether other items can be stacked on top

Quoting without dimensions: You can quote using volume + weight instead of explicit dimensions. However, dimensions are mandatory for booking. Plan accordingly.

Use POST /v1/density to derive freightClass and volume from dimensions.

Stacking rules:

isStackablelevels
falseMust be 1
trueMust be 2 or greater

Insurance (optional)​

"insurance": {
  "cargoValue": "1000",
  "goodsValue": "NEW",
  "isNewGoods": true,
  "addFreightCost": false,
  "addExtraCoverage": false,
  "insuredName": "Insurance1",
  "insuredCountry": "UNITED STATES"
}
FieldDescription
cargoValueTotal declared cargo value
goodsValue"NEW", "USED", or "PERISHABLE"
isNewGoodstrue when goodsValue = "NEW", otherwise, send false
addFreightCostInclude freight cost in insured value
addExtraCoverageAdd 10% extra coverage for lost profits

Equipments​

For Truckload (FTL) quotes the quote results will include the equipment types available for the selected rate. Please take this into account when requesting and reviewing Truckload (FTL) quotes.

Request Examples​

{
  "customerBsn": "YOUR_CUSTOMER_BSN",
  "origin": {
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "postalCode": "90001"
  },
  "destination": {
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "postalCode": "90001"
  },
  "UOM": "US",
  "items": [
    {
      "itemName": "Test Pallet",
      "packageType": 100,
      "quantity": 1,
      "length": 24,
      "width": 29,
      "height": 24,
      "weight": 1000,
      "freightClass": "92.5",
      "levels": 1,
      "isHazardous": false,
      "isStackable": false
    }
  ],
  "accessorials": [
    {
      "accessorial": "Liftgate",
      "accessorialType": "Pickup"
    }
  ],
  "modes": ["LTL"],
  "requestingUser": "joe@example.com"
}

Response​

{
  "data": {
    "quoteNumber": 89169865,
    "mileage": 1,
    "referenceQuoteNumber": "QUOTE_REF_NUMBER",
    "carrierQuotes": [
      {
        "rateNumber": 1525,
        "carrierNumber": 5863632,
        "carrierName": "Carrier Name",
        "transitDays": 1,
        "mode": "LTL",
        "service": "Standard",
        "serviceDescription": "Less than Truckload",
        "totalAmount": 222.30,
        "suggestedRate": 255.65,
        "quoteExpirationDate": "2026-05-18T12:14:13.86-05:00",
        "accessorials": [
          {
            "accessorial": "Liftgate",
            "accessorialType": "Pickup",
            "quantity": 1
          }
        ],
        "charges": [
          {
            "displayName": "Base",
            "chargeCode": 1000,
            "amount": 222.30,
            "isWaived": false
          }
        ]
      }
    ]
  },
  "errors": null
}

Key Response Fields​

FieldDescription
quoteNumberUnique quote ID — save this for booking
carrierQuotes[].rateNumberCarrier-specific rate ID — save this for booking
totalAmountBuy rate (actual carrier cost)
suggestedRateSuggested sell price
transitDaysEstimated transit time in days
quoteExpirationDateWhen the rate expires

Empty carrier quotes If carrierQuotes is empty on a 200 OK response, no carrier matched the lane. Contact PRIMO customer service to review coverage for your origin/destination.

Next Steps​

  • OTR Book → — Use your quoteNumber and rateNumber to create a booking