Create Listing

Create a new listing on uShip

The Listing Create API enables you to create listings in the uShip marketplace or in a shipper's Private Network. Listings, also known as shipments, enable a Shipper to get matched with pricing and transport service. Once active, Shippers receive bids from Service Providers. Shippers evaluate the bids not just on the price, but also on the real feedback and ratings Providers received from completed prior shipments. 

After creating a listing, check the listing through the API by retrieving a list of all listings or by retrieving a specific listing. You can also check on www.uship.com to see the listing live. We require testing in our staging environment when integrating with this end point to ensure success and to avoid any accidental production interaction.

The Listing Create API is especially useful for businesses to automate high volume creation of real shipments. For example, say you are a car dealership and you serve a national network. You may need to create dozens to hundreds of listings on a daily basis.

Since the API is not dependent on the uShip user interface, developers can create and automate stable, custom functionality and interfaces that meet your business needs.



Request

Headers

Authorization

An "Authorization" header is required for all uShip API calls.  However, creating a listing requires a shipper context (e.g., the person responsible for the shipment).  Two forms of Authentication are available:

  1. Resource Owner Password Credentials - For when the integration is owned by the shipper and username & password can be secured.
  2. Authorization Code - For when the integration is a platform on which multiple shippers participate.

 

POST

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

Depending on the category (commodity) and item you're shipping, you must specify basic information such as the following:

 

Listing Object

Broad listing details, such as title, description, status, and service types.

Field Type Description Valid Sample Values 
title
 String Required. Brief descriptive name of the listing. "Bring Cars Home this Month" 
description
 String Longer explanation of the listing. "Bought several cars from out of state auction to bring home." 
status
 String Allows the listing to be created as "Saved".  Will later need to be activated in order to receive bids. "Saved", null 
serviceTypes
 Array The service types requested for this listing. See ServiceTypes table below. or use GET https://api.uship.com/v2/lookups/serviceTypes/. 
 "Driveaway",
"OpenTransport", "EnclosedTransport" 

 

Commodity Object

Item details including measurements where applicable.  For specifics, please visit corresponding API Reference pages.

  • Use "Boats" to create supported boat listings.
  • Use "CarsLightTrucks" to create car and light truck listings in the vehicle category.
  • Use "Furniture" to create furniture listings in the household good category.
  • Use "MotorcyclesPowerSports" to create motorcycle listings in the vehicle category.
  • Use "Pets" to create dog and cat listings.
  • And more coming soon!

 

Pricing Object

Optional. Specify pricing with a named price.  Omitting the price object creates a traditional open auction.

Field Type Description Valid Sample Values 
namedPrice
 Container Wrapper for the pricing fields - 
amount
 String How much will this/these vehicles be listed to ship? $2000 
currencyType
 Array The type indicated by the code that corresponds to the country and currency name. Currency Lookups has the most current list. "USD"

 

Route Origin and Destination Address Objects

Route information which includes pick up and delivery time frames and locations.  See Route Object reference.

  • The origin address is the first item in the route array.
  • The destination address is the last item in the route array.

 

 

Reference Enumerations

Service Types

Also available via a Lookup API call.

Service Type Value Description
Open Transport Service "OpenTransport" This service offering is the standard level of care for vehicle transport. The Service Provider will carefully load the vehicle onto an open trailer, generally along with other vehicles, and secure it for transport. The Service Provider will tow the trailer to the delivery location and unload the vehicle. "Top Load" placement protects the vehicle from road debris and leaks from other cars in transit. This placement and other upgrades may be available for an additional fee.
Enclosed Transport Service "EnclosedTransport" This service offering is a premium level of care for vehicle transport. The Service Provider will carefully load the vehicle onto an enclosed trailer that is protected from the elments and road debris. The Service Provider will tow the trailer to the delivery location and unload the vehicle. The premium service is commonly used for rare or high-value vehicles or for transport through extreme climates.
Driveaway Service "Driveaway" This service offering is the most basic level of vehicle transport service. The Service Provider drives the vehicle to the destination. No other equipment is used for the transport job, which keeps costs to a minimum. This service is a good option for customers that require affordable vehicle transport and do not mind the additional mileage on their vehicle.
Other "Other"

 

Response

 

Response

Status  201 Created
Body null

 

Response Header

Location https://api.uship.com/v2/listings/{listingId}

 

 

FAQ

Can I create a listing with multiple items?
Yes. You can create a listing with multiple items that are the same commodity type.

What happens if the vehicle I'm listing has a pre-1980 manufacture year?
Any make or model that is supplied and does not match will return "Other" when retrieving the created listing.

Can I list a custom boat, motorcycle or automobile? 
Yes. If there are modifications to the original vehicle, set isModified to true. Specify the vehicle dimensions as documented in the input listing model.

What happens if I don't know the year, make, or model of the boat, motorcycle or automobile? 
If any of these fields is left blank, the API will still process them to create the listing. If year is not populated, it will not return when you retrieve the listing. If make or model are left blank, the fields will return when you you retrieve the listing and the strings will be empty.

 

version 112 as of 2 years ago by uShip