Create a Rate Request


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

Create Rate Request

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.

 

Each input request body differs based on which commodity for which the rate request is created.

  • All following snippet examples after the main input body example replace the commodity object unless stated otherwise.
  • The valid value types and data formats are in the API Reference beneath the commodity object snippets.

 

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 the user making the request. Use this header in conjunction with the third party ID (thirdPartyId) to tie the request to a unique identifier.

 

Request Body


The example below is the entire JSON input body for Cars & Light Trucks. To use the example in a request, replace the pick up and delivery dates so that they are at least one day ahead of the present date.

 

{
    "route": {
        "items": [
            {
                "address": {
                    "postalCode": "90210",
                    "country": "US"
                },
                "timeFrame": {
                    "earliestArrival": "2015/07/07",
                    "latestArrival": "2015/07/07",
                    "timeFrameType": "on"
                }
            },
            {
                "address": {
                    "postalCode": "78741",
                    "country": "US"
                },
                "timeFrame": {
                    "earliestArrival": "2015/08/09",
                    "latestArrival": "2015/08/15",
                    "timeFrameType": "between"
                }
            }
        ]
    },
    "items": [
        {
            "commodity": "CarsLightTrucks",
            "unitCount": 2,
            "vin": "1234570192384709AB",
            "makeName": "Honda",
            "modelName": "Pilot",
            "year": 2008,
            "isRunning": true,
            "isConvertible": false,
            "isModified": false
        }
    ],
    "thirdPartyId":  "String for Third Party Identifier"
}

 

Commodities


 

Cars & Light Trucks

..."items": [
   {
     "commodity": "CarsLightTrucks",
     "unitCount": 2,
     "makeName": "Honda",
     "modelName": "Pilot",
     "year": 2008,
     "isRunning": true,
     "isConvertible": false,
     "isModified": false
    }
]...

 

Reference

Field Type Description
unitCount
Integer The number of items in the rate request.
vin
String Optional 17-character vehicle identification number.
year
Integer The year the car or truck was made.
makeName
String The vehicle's manufacturer.
modelName
String The vehicle's model name. The make and model should match.
isRunning
Boolean
  • true - Yes, the vehicle is running or can be driven and in working order.
  • false - No, the vehicle is not running and cannot be driven or moved on its own.
isConvertible
Boolean
  • true - Yes, the vehicle has a top that can be put down.
  • false - No, the vehicle does not have a top that can be put down.
isModified
Boolean
  • true - Yes, the vehicle has been changed or upgraded from its original manufactured state.
  • false - No, the vehicle is in its original manufactured state.



Boats

..."items": [
   {
     "commodity": "PowerBoats",           
     "makeModel": "1989 Sea Ray Sundancer",
     "lengthInMeters": 3.123,
     "widthInMeters": 3.123,
     "heightInMeters": 3.123,
     "weightInGrams": 200200,
     "onTrailer": true
    }
]...

Furniture

..."items": [
    {
      "commodity": "Furniture",
      "unitCount": 2,
      "title": "Brief title for each item.", 
      "description": "Descriptive text about the furniture items.",  
      "widthInMeters": 3.524,
      "lengthInMeters": 3.397,
      "heightInMeters": 2.041,
      "weightInGrams": 38100,
         }
],... 

 

Reference

Field Type Description
unitCount
Integer The number of items in the rate request.
title
String Descriptive title of the items.
description
String Descriptive text about the items.
widthInMeters
Decimal The width of the furniture item in meters.
lengthInMeters
Decimal The length of the furniture item in meters.
heightInMeters
Decimal The height of the furniture item in meters.
weightInGrams
Decimal The total weight of the item in grams.

Less Than Truckload (LTL) Freight

See the Create an LTL Freight Rate Request reference.

 

Motorcycles and Mopeds

..."items": [
    {
      "commodity": "MotorcyclesMopeds",
      "unitCount": 2,
      "description": "Descriptive text about the motorcycle or moped.",  
      "year": 2011,
      "makeName": "Honda",
      "modelName": "Shadow RS",
      "hasSideCar": false,
      "isTrike": false,
      "isRunning": true,
      "isPalletized": true 
    }
  ],...

 

Reference

Field Type Description
commodity
String Specify "MotorcyclesMopeds" for rate requests.
unitCount
Integer Quantity. The number of units of this item.
description
String Descriptive text about the items.
year
Integer The year the motorcycle was made.
makeName
String The motorcycle's manufacturer.
modelName
String The motorcycle's model name. The make and model should match.
hasSideCar
Boolean
  • true - Yes, the motorcycle has an attached sidecar.
  • false - No, the motorcycle does not have a sidecar.
isPalletized
Boolean
  • true - Yes, the item is on a wooden or plastic pallet and can be moved by forklift.
  • false - No, the item is not on a pallet.
isTrike
Boolean
  • true - Yes, the motorcycle has three wheels.
  • false - No, the motorcycle is not a three-wheel bike.
isRunning
Boolean
  • true - Yes, the vehicle is running or can be driven and in working order.
  • false - No, the vehicle is not running and cannot be driven or moved on its own.

 

 

Pets

..."items": [
        {
            "commodity": "Dogs",
            "petsName": "Magnus",
            "breed": "Chihuahua",
            "weightInGrams": 2260,   
            "specialNeed": "Description.",
            "isTagged": true,
            "isVaccinated": true,
            "kennelSize": "small"
        }
    ],...

 

Reference

Field Type Description
commodity
String Specify either "Dogs" or "Cats" for rate requests.
petsName
String The pet's name.
breed
String The pet's characteristic or type according to how it is classified either officially or unofficially.
weightInGrams
Integer the total weight of the dog or cat in grams.
specialNeed
String Instructions for the Service Provider about how to care for the pet during transport.
isTagged
Boolean
  • true - Indicates that the pet is wearing its vaccination and identification tags such as on its collar.
  • false - Indicates that the pet is not wearing identification tags.
isVaccinated
Boolean The pet has vaccinations as well as official documentation pertaining to the shots received. 
  • true - The pet has vaccinations as well as official documentation pertaining to the shots received.
  • false - The pet is not vaccinated.
kennelSize
String

Description of the kennel size which should include room for the pet to stand up, turn around, and have enough clearance above their head or ears when standing.

Valid values:

  • "small"
  • "medium"
  • "large"
  • "extralarge"

 

 

Response

Success Status: 201 Created

Response Header

Location header

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

 

API Reference


Route Object

See Route Object Reference.

 

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. 

 

 

What can you do next?


Retrieve rates via

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