Skip to main content

OTR Book

Endpoint: POST /v1/otr/book

Create a binding transportation booking using a carrier rate from a previous OTR quote. You must supply the quoteNumber and rateNumber returned by the quote endpoint.

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

Prerequisites​

Before booking, you need:

  • A quoteNumber from a successful POST /v1/otr/quote response
  • A rateNumber from the selected carrier rate in that response
// From quote response:
{
  "quoteNumber": 8916989,
  "carrierQuotes": [
    { "rateNumber": 1525, "carrierName": "Carrier A" },
    { "rateNumber": 1550, "carrierName": "Carrier B" }
  ]
}

// To book Carrier A:
{ "quoteNumber": 8916989, "rateNumber": 1525 }

Request Body​

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

FieldTypeRequiredDescription
quoteNumberintegerYesFrom the quote response
rateNumberintegerYesSelected carrier rate from the quote response
customerBsnintegerYesCustomer BSN — must match the value used in the quote
customerNumberintegerYesBusiness identifier for your customer. Retrieve from GET /v1/customers
freightDirectionstring/integerYesShipment direction (see below)
movementobjectYesShipment execution details
isInsuredbooleanYesWhether the shipment includes insurance coverage

customerBsn and customerNumber​

Both values are retrieved from the GET /v1/customers endpoint. Use results[].customerNumber for customerNumber and results[].bsns[].customerBsn for customerBsn. They must match exactly what was used during the quote request.

Freight Direction​

ValueNameDescription
1InboundShipment arriving at the customer
OutboundOutboundShipment departing from the customer
ThirdPartyThirdPartyCustomer is neither shipper nor consignee

Movement Object​

FieldDescription
quote.uomUnit of measure (must match the quote)
estimatedPickupDatePickup datetime format
commoditiesArray of items (must match the quote exactly)
pickupAddressFull pickup address
deliveryAddressFull delivery address (must match quote origin/destination)
pickupInformation.contactContact at pickup location
deliveryInformation.contactContact at delivery location
hazardousContactRequired, when any item has isHazardous: true otherwise isHazardous: false

Commodities​

Commodities must match the items submitted in the quote request. Any discrepancy will return an error.

Dimensions are required for booking Even if you submitted a quote without dimensions (using volume), you must provide length, width, and height in the booking request.

Contact Object​

{
  "name": "John Doe",
  "phone": "+15551234567",
  "email": "john.doe@example.com"
}

Addresses​

pickupAddress and deliveryAddress must match the origin and destination used during the quote.

{
  "name": "Location Name",
  "addressLine1": "456 Market Street",
  "addressLine2": "",
  "city": "Los Angeles",
  "state": "CA",
  "zipcode": "90001",
  "country": "US"
}

Request Examples​

{
  "quoteNumber": 8916989,
  "rateNumber": 1525,
  "customerBsn": "YOUR_CUSTOMER_BSN",
  "customerNumber": "YOUR_CUSTOMER_NUMBER",
  "freightDirection": 1,
  "movement": {
    "quote": {
      "uom": "US"
    },
    "estimatedPickupDate": "2026-05-12T10:00:00Z",
    "commodities": [
      {
        "description": "Test Pallet",
        "freightClass": "92.5",
        "quantity": 1,
        "weight": 1000,
        "packageType": 100,
        "length": 24,
        "width": 29,
        "height": 24,
        "isHazardous": false,
        "isStackable": false,
        "levels": 1
      }
    ],
    "pickupAddress": {
      "name": "Origin Location",
      "addressLine1": "456 Market Street",
      "addressLine2": "",
      "city": "Los Angeles",
      "state": "CA",
      "zipcode": "90001",
      "country": "US"
    },
    "deliveryAddress": {
      "name": "Destination Location",
      "addressLine1": "456 Market Street",
      "addressLine2": "",
      "city": "Los Angeles",
      "state": "CA",
      "zipcode": "90001",
      "country": "US"
    },
    "pickupInformation": {
      "contact": {
        "name": "John Doe",
        "phone": "+15551234567",
        "email": "john.doe@example.com"
      }
    },
    "deliveryInformation": {
      "contact": {
        "name": "John Doe",
        "phone": "+15551234567",
        "email": "john.doe@example.com"
      }
    }
  },
  "isInsured": false
}

Hazardous material lookup. To retrieve specific UN number information, use: GET https://api.primofabric.com/portal/v1/flow/hazmat/search?value={UNNumber}

Response​

{
  "data": {
    "orderNumber": 20021775,
    "bolNumber": "1354724",
    "documents": [
      {
        "docType": "BillOfLading",
        "url": "https://dev.shipprimus.com/Documents/BOL_1354724.pdf",
        "fileName": "BOL_1354724.pdf",
        "extension": ".pdf",
        "contentType": "application/x-download"
      },
      {
        "docType": "ShippingLabel",
        "url": "https://dev.shipprimus.com/Documents/LABEL_1354724.pdf",
        "fileName": "LABEL_1354724.pdf",
        "extension": ".pdf",
        "contentType": "application/x-download"
      }
    ]
  },
  "errors": null
}

Key Response Fields​

FieldDescription
orderNumberUnique identifier for the created booking order
bolNumberBill of Lading number
documentsArray of generated shipping documents (BOL, Label, Quotation)
documents[].docTypeDocument type: "BillOfLading", "ShippingLabel", "Other"
documents[].urlURL to download or access the document

Next Steps​