Create an LTL Rate Request


This method is part of the Shipping Customer's Published Rates flow. A Shipping Customer creates a rate request (documented on this page) which kicks off the corresponding notification to eligible, qualified Service Providers.

 

POST

https://api.uship.com/v2/raterequests/

 

  • Provide specific and accurate rate request information for Service Providers to provide the most accurate rates.
  • Service Providers respond to the notification with bookable rates.

 

Create LTL Rate Request

 

Request Headers

For additional authorization headers, see the Authentication page.

Header Value Description
X-Affiliate {affiliate's user Id} Set the affiliate ID using this header. If none is provided, the affiliate ID becomes the ID of ther user making the request. Use this header in conjunction with the third party ID (thirdPartyId) to tie the request to a unique identifier.

Sample Request Body


Each input request body differs based on which commodity for which the rate request is created. The example below is a complete JSON input body for Less than Truckload or LTL Freight categories. To use this example request, replace the pick up date so that it is at least one day ahead of the present date. 

{
    "route": {
        "Items": [
            {
                "address": {
                    "streetAddress": "1000 Main Street",
                    "alternateStreetAddress": "Bldg 8, Suite 300",
                    "majorMunicipality": "Santa Barbara",
                    "postalCode": "93108",
                    "stateProvince": "CA",
                    "country": "US",
                    "type": "BusinessWithLoadingDockOrForklift"
                },
                "timeFrame": {
                    "earliestArrival": "2014/10/20",
                    "latestArrival": "2014/10/20",
                    "timeFrameType": "on"
                },
                "attributes": {
                    "inside": true,
                    "liftgateRequired": false            
                },
                "contact": {
                    "name": "JaneSmith",
                    "companyName": "CommercialGoodsGalore",
                    "phoneNumber": 1234567890
                }
            },
            {
                "address": {
                    "postalCode": "78741",
                    "country": "US",
                    "type": "BusinessWithLoadingDockOrForklift"
                },
                "attributes": {
                    "inside": false,
                    "liftgateRequired": false,
                    "callBeforeArrival": true,
                    "appointmentRequired": true
                },
                "contact": {
                    "name": "JaneSmith",
                    "companyName": "CommercialGoodsGalore",
                    "phoneNumber": 1234567890
                }
            }
        ]
    },
    "items": [
        {
            "Commodity": "NewCommercialGoods",
            "unitCount": 1,
            "packaging": "Pallets",
            "weightInGrams": 226796,
            "freightClass": 77.5,
            "stackable": true,
            "hazardous": false,
            "handlingUnit": "Pallets48x40Inches" 
        }
    ],
    "attributes": {
        "protectfromFreezing": false,
        "sortandSegregate": false,
        "blindShipmentCoordination": false
    },
    "thirdPartyId": "String for Third Party Identifier" 
}

Response

Success Status: 201 Created

Response Header

Location header

https://api.uship.com/v2/raterequests/{rateRequestID}/rates

 

API Reference


Route Object

Visit the Route Object reference. Follow this list of LTL-specific requirements:

  • The "streetAddress" is required.
  • If no address type is specified, the default is "Residence" where the "companyName" field is not required in the contact object.
  • The pick up time frame is the only one available and is required. Do not specify the delivery time frame.
  • The only time frame type you can specify for pick up is "on" where the time frame dates must match exactly.
  • Either specify the zip codes or the latitude and longitude for both pick up and delivery addresses.

Commodity Object

Either provide the freight class and weight or the dimensions and the weight. Once you choose either freight class or dimensions for one item, you must stay with the same parameters for the rest of the items in the rate request.

Field Type Description
commodity
String

Specify the LTL Freight commodity found in the reference enumeration section below Commodity Codes. Required.

unitCount
Integer

If no value is provided, the default is set to one (1).

handlingUnit
String The method in which the unit is handled by a carrier during transport. If a number of packages have been secured to a single pallet and cannot be separated during transport, the quantity is referred to as (1) handling unit. Required. Dimensions: Include pallets and other packaging materials.

Example: A shipment containing 10 boxes stretch-wrapped to a single pallet should be described as (1) handling unit. A shipment containing 10 un-palletized “loose” boxes should be described as (10) handling units.

Valid example string for a handling unit "Pallets48x40Inches". A lookup will be available to get all valid values. For now, see table below.

stackable
Boolean

The item has flat surfaces and can sustain the weight of another object. 

  • true - Item is stackable.
  • false - Item is not stackable. (Default)
lengthInMeters
Decimal The length of the item or unit in meters. Required unless freight class is supplied.
heightInMeters
Decimal The height of the item or unit in meters. Required unless freight class is supplied.
weightInGrams
Integer The total weight of the item or unit in grams. Required unless freight class is supplied.
freightClass
Decimal

Carriers use freight classes to calculate shipping costs. They are defined in the National Motor Freight Classification Guide. If you are unsure of your shipment's freight class, simply enter the dimensions and weight for a rate request. A lookup will be available to get all valid values.

Freight class is determined by four factors:

  • density
  • value
  • stowability
  • handling characteristics
hazardous
Boolean

A substance or material may be classified as hazardous if the transportation of the material in a particular amount and form poses an unreasonable risk to health and safety or property. Hazardous materials are defined by the U.S. Department of Transportation in accordance with the Federal Hazardous Material Law and require special handling and documentation. For more general information, go to the U.S. DOT website at http://www.phmsa.dot.gov/hazmat.

  • true - Provide rate for a shipment containing hazardous materials.
  • false - Rate does not account for hazardous materials. (Default)

 

Pickup / Delivery Accessorials

Field Type Description
inside

Boolean

Inside pickup/delivery

  • true - If the driver is required to go inside (beyond the front door or loading dock) to pick up or deliver the shipment instead of remaining at the dock or truck, additional fees will be charged.
  • false - Rate does not account for inside pick up or delivery. (Default)
liftgateRequired
Boolean

Liftgate service at pickup/delivery.  If a liftgate is required for the shipment, it must be specified especially when the address type is “Residence” or “BusinessWithoutLoadingDock”. Providing the service requires extra charge.

  • true - When the shipping or receiving address does not have a loading dock or forklift, manual loading or unloading is necessary. A liftgate is a hydraulic platform attached to the back of specially equipped trucks that can raise and lower a shipment from the truck to the ground and vice versa. 
  • false - Rate does not account for a liftgate.
callBeforeArrival
Boolean The Shipping Customer requires the Service Provider to call the specified contact at the delivery address before arriving at the location. Providing this notice requires extra charge.
  • true - Calculate the rate to include a Service Provider calling the destination location before arriving on site.
  • false - Rate does not account for calling before arriving at the destination. (Default)
appointmentRequired
Boolean The Shipping Customer requires the Service Provider to set an appointment for when to deliver. Providing this service requires extra charge.
  • true - Calculate the rate to include a Service Provider setting up an appointment with the Shipping Customer.
  • false - Rate does not account for setting an appointment. (Default)

 

Additional Services Accessorials

Field Type Description
protectFromFreezing
Boolean

Protect from freezing

  • true - Choose this option if your shipment includes temperature sensitive items that need to be protected from reaching below 32° F/0° C.
  • false - Rate does not account for protection from freezing. (Default)
blindShipmentCoordination
Boolean

Blind shipment coordination

  • true - Blind shipping service should be requested if you do not want the shipper and/or consignee to know the other’s identity. This is typically requested when a third party controls the freight.
  • false - Rate does not account for blind pick up or delivery coordination. (Default)
sortandSegregate
Boolean

Sort & segregate

  • true - Upon request, a carrier will sort through and segregate a load by marks, brands, sizes, or other distinguishing characteristics.
  • false - Rate does not account for a Service Provider organizing and marking the freight items. (Default)

 

ThirdPartyId

Optional unique string identifier used in conjunction with the X-Affiliate header to tie the request to a unique identifier. Useful for uShip API consumers and third parties to identify rate requests in their own applications and systems. 

 

Reference Enumerations


Commodity Codes

A GET /v2/lookup will be available to programmatically retrieve this information. 

Business and Industrial Goods Categories

String
WoodPaperProducts
LiquidsGasesChemicals
StoneMetalsMinerals
CommoditiesDryBulk
GeneralFreight
MixedFreight
Utilities
PharmaceuticalProducts
Fertilizers
PlasticsRubber
TextilesLeather
MiscellaneousManufacturedProducts
OtherBusinessIndustrialGoods
PaperProducts
LogsandOtherWoodintheRough
WoodProducts
PaperorPaperboardArticles
PrintedProducts
LiquidsGases
Chemicals
CrudePetroleumOil
WaterWell
GasolineandAviationTurbineFuel
FuelOils
ChemicalProductsandPreparationsnec
BuildingMaterials
MachineryLargeObjects
ElectronicandOtherElectricalEquipmentandComponentsandOfficeEquipment
PrecisionInstrumentsandApparatus
CoalorCoke
MonumentalorBuildingStone
NaturalSands
GravelandCrushedStone
NonMetallicMineralsnec
MetallicOresandConcentrates
CoalandPetroleumProductsnec
NonMetallicMineralProducts
Metalsheetscoilsrolls
BaseMetalinPrimaryorSemiFinishedFormsandinFinishedBasic
ArticlesofBaseMetal

Vehicle, Boat, Food & Agricultural Goods Categories

String
VehicleParts
BoatParts
RefrigeratedFood
MeatFishSeafood
CerealGrainsincludingseed
AnimalFeedProductsofAnimalOrigin
MilledGrainProductsPreparationsandBakeryProducts
Beverages
AlcoholicBeverages
OtherPreparedFoodstuffsandFatsandOils
TobaccoProducts
OtherFoodAgriculture

LTL Freight Categories

String
NewCommercialGoods
UsedCommercialGoods
WineLiquorBeerSpirits
NonPerishableFoodsBeverages
OtherLessthanTruckloadGoods

Handling Units

Valid String Values

Boxes
Cartons
Crates
Drums
Bags
Bales
Bundles
Cans
Carboys
Carpets
Cases
Coils
Cylinders
Loose
NoPackagingRequired
PackagingHelpRequired
Pallets48X40Inches
Pails
Reels
Rolls
TubesPipes
Other

 

What can you do next?


Retrieve rates via

GET https://api.uship.com/raterequests/{rateRequestID}/rates