Cars and Light Trucks API Reference 2.0.0

Our vehicle shipping API package gives shippers the tools to instantly get shipping costs, booking information and tracking data from the comfort of their user interface. For more details, order of operations, and FAQ, please see our Cars and Light Trucks API Guide.

Server

www.uship.com

Authentication

POST

/oauth/token

POST

/oauth/token_authenticated

Bearer token for searching and rates

Auth

Headers

grant_type	string	Enter 'client_credentials'
client_id	string	The unique ID provided to you by uShip for integrating
client_secret	string	The unique ID secret provided alongside your client ID by uShip

POST /oauth/token

xxxxxxxxxx
 
curl --request POST \ --url 'https://www.uship.com/oauth/token' \ --header 'grant_type: {grant_type}' \ --header 'client_id: {client_id}' \ --header 'client_secret: {client_secret}'
Copy

Responses N/A

200

Successfully authenticated

object	object
access_token	string	example value "3z8co7d86ytn65h567vdzyfb"
token_type	string	bearer
expires_in	integer	The number of seconds the token is valid for. Sets to 600
refresh_token	string	example value "3c8od7y86hold65d567enbrla"

Response

xxxxxxxxxx
 
{ "access_token": "{string}", "token_type": "{string}", "expires_in": "{integer}", "refresh_token": "{string}"}
Copy

Bearer token for booking, tracking, listing

Auth

Headers

grant_type	string	Enter 'password'
username	string	Your uShip user name
password	string	The password for your uShip account
client_id	string	The unique ID provided to you by uShip for integrating
client_secret	string	The unique ID secret provided alongside your client ID by uShip

POST /oauth/token_authenticated

xxxxxxxxxx
 
curl --request POST \ --url 'https://www.uship.com/oauth/token_authenticated' \ --header 'grant_type: {grant_type}' \ --header 'username: {username}' \ --header 'password: {password}' \ --header 'client_id: {client_id}' \ --header 'client_secret: {client_secret}'
Copy

Responses N/A

200

Successfully authenticated

object	object
access_token	string	example value "3z8co7d86ytn65h567vdzyfb"
token_type	string	bearer
expires_in	integer	The number of seconds the token is valid for. Sets to 600
refresh_token	string	example value "3c8od7y86hold65d567enbrla"

Response

xxxxxxxxxx
 
{ "access_token": "{string}", "token_type": "{string}", "expires_in": "{integer}", "refresh_token": "{string}"}
Copy

Lookup Values

GET

/v2/lookups/vehicles/CarsLightTrucks/year/make

Lookup values for car

Returns valid models. Omit the make to return valid makes and omit the year to return valid years. Cars are supported from 1981 to the current year. Use if not leveraging VIN for year, make and model rate retrieval.

Auth

Headers

Accept	string	application/json
Authorization	string	Bearer {your bearer token}
Content-Type	string	application/json

GET /v2/lookups/vehicles/CarsLightTrucks/year/make

xxxxxxxxxx
 
curl --get \ --url 'https://www.uship.com/v2/lookups/vehicles/CarsLightTrucks/year/make' \ --header 'Accept: {Accept}' \ --header 'Authorization: {Authorization}' \ --header 'Content-Type: {Content-Type}'
Copy

Responses application/json

200

200 OK

object	object
items	object
model	string	Elantra Wagon
value	string	elantra-wagon

Response

xxxxxxxxxx
 
{ "items": {  "model": "{string}",  "value": "{string}" }}
Copy

Rate Retrieval

POST

/integration/rates/{integrator}

Receive uShip Logistics rates

Auth

Headers

x-api-key

string

The unique string provided for each integrator by uShip.

Path Params

integrator

string

Name of the client making the request. This parameter value will be supplied by uShip prior to your integration.

Request Body application/json

object	object
items	array[object]
item	object
commodity	string	Currently we only support 'CarsLightTrucks'
year	string	The year of the vehicle being shipped. Only required if VIN is not included as reference number.
makeName	string	The make name of the vehicle being shipped. Only required if VIN is not included as reference number.
modelName	string	The model name of the vehicle being shipped. Only required if VIN is not included as reference number.
referenceNumbers	array[object]
number	string	Caller system reference number. This number can be used to search in uShip. For example, if you select 'Vin' as type, enter the Vin number here to link it to your listing. Use VIN to transfer make, model and year for rate retrieval. If VIN is not supplied, you must include year, make and model in the request.
type	string	Type of reference number. Valid types are { Invoice, SalesOrder, Release, ThirdPartyTracking, Vin, Other, Lot, ThirdPartyOrderNumber }
earliestPickupDate	date-time	The earliest date that the vehicle can be picked up by the carrier.
latestDeliveryDate	date-time	The latest date that the vehicle can be picked up by the carrier.
originAddress	object
postalCode	string	Currently, we only support zip codes within the continental United States (excluding Alaska and Hawaii)
country	string	Currently, we only support addresses within the continental United States (excluding Alaska and Hawaii)
majorMunicipality	string	Origin city name
stateProvince	string	Origin state abbreviation
streetAddress	string	Origin street name and number
destinationAddress	object
postalCode	string	Currently, we only support zip codes within the continental United States (excluding Alaska and Hawaii)
country	string	Currently, we only support addresses within the continental United States (excluding Alaska and Hawaii)
majorMunicipality	string	Destination city name
stateProvince	string	Destination state abbreviation
streetAddress	string	Destinatiuon street name and number

Expand

POST /integration/rates/{integrator}

xxxxxxxxxx
 
curl --request POST \ --url 'https://www.uship.com/integration/rates/%7Bintegrator%7D' \ --header 'x-api-key: {x-api-key}' \ --data '{  "items": [    {      "item": {        "commodity": "CarsLightTrucks",        "year": "2011",        "makeName": "Acura",        "modelName": "MDX",        "referenceNumbers": [          {            "number": "{string}",            "type": "{string}"          }        ],        "earliestPickupDate": "2019-10-30T00:00:00-05:00",        "latestDeliveryDate": "2019-11-05T00:00:00-05:00"      },      "originAddress": {        "postalCode": "78739",        "country": "US",        "majorMunicipality": "Austin",        "stateProvince": "TX",        "streetAddress": "123 Congress St."      },      "destinationAddress": {        "postalCode": "30329",        "country": "US",        "majorMunicipality": "Austin",        "stateProvince": "TX",        "streetAddress": "123 Congress St."      }    }  ]}'
Copy

Responses application/json

200

array	array[object]
referenceNumbers	array[object]
number	string	Caller system reference number. This number can used to search in uShip. For example, if you select 'Vin' as type, enter the Vin number here to link it to your listing. Multiple values can be added as an array.
type	string	Type of reference number valid types are { Invoice, SalesOrder, Release, ThirdPartyTracking, Vin, Other, Lot, ThirdPartyOrderNumber }
price	object
value	number	The price for shipping the vehicle.
label	string	Currency with dollars and cents
shortLabel	string	Currency rounded to the nearest dollar
currencyType	object
value	string	The currency code. We currently only support USD for this value.
label	string	The currency label. We currently only support US Dollar for this value.
shortLabel	string	The abbreviated currency label. We currently only support US Dollar for this value.
checkoutUrl	string	This URL can be delivered to the consumer and will bring them directly to the checkout page for their shipment.
quoteID	string	This is the ID you can use to book this rate via our Booking Acceptance endpoint

Response

xxxxxxxxxx
 
[ {  "referenceNumbers": [   {    "number": "{string}",    "type": "{string}"   }  ],  "price": {   "value": 1359.97,   "label": "$1359.97",   "shortLabel": "$1,359",   "currencyType": {    "value": "USD",    "label": "US Dollar",    "shortLabel": "US Dollar"   }  },  "checkoutUrl": "https://www.uship.com/quotes/checkout.aspx?qrid=653ea7bc628e01854d5f99c&qid=5d9e1a7ddf65730190f1673e&view=0",  "quoteID": "5e28co759d1y037848c273od" }]
Copy

Booking

POST

/v2/rates/{rateId}/acceptance

Allows booking of a rate

Auth

Headers

authorization	string	Required for every call after initial authorization. The "Bearer" label is case sensitive. There must be a space between this authorization label and the access token string i.e Bearer {access token}.
content-type	string	Set this value to application/json

Path Params

rateId

string

The id received when obtaining your rate request

Query String

checksum string

Request Body application/json

object	object	The input model for booking your rate
payOnTerms	boolean	Indicates whether the user is on Pay on Terms. Set to 'true' or 'false'
insurance	object	Insurance information for accepting the rate
coverage	string	The amount of insurance coverage for the shipment

POST /v2/rates/{rateId}/acceptance

xxxxxxxxxx
 
curl --request POST \ --url 'https://www.uship.com/v2/rates/%7BrateId%7D/acceptance' \ --header 'authorization: {authorization}' \ --header 'content-type: {content-type}' \ --data checksum={checksum} \ --data '{  "payOnTerms": "{boolean}",  "insurance": {    "coverage": "{string}"  }}'
Copy

Responses N/A

201

Your rate has been booked.

No response body

Response

xxxxxxxxxx
 
No response
Copy

Tracking

GET

/v2/listings/{listingId}/track

Retrieve tracking info

This endpoint allows you to retrieve latitude/longitude values, transit status, and the most recent location or address. If a recent location is not provided, these will be absent from the response.

Auth

Headers

client_id	string	The unique ID provided to you by uShip for integrating
client_secret	string	The unique ID secret provided alongside your client ID by uShip
Authorization	string	Bearer {your bearer token}

Path Params

listingId integer

GET /v2/listings/{listingId}/track

xxxxxxxxxx
 
curl --get \ --url 'https://www.uship.com/v2/listings/%7BlistingId%7D/track' \ --header 'client_id: {client_id}' \ --header 'client_secret: {client_secret}' \ --header 'Authorization: {Authorization}'
Copy

Responses N/A

200

200 OK

object	object
listingGeneratedId	integer	The ID for your listing
listingTitle	string	The title of your listing
commodityCode	string	Displays CarsLightTrucks
shipmentTrackingSummaryModel	object
originAddress	object	The origin location reverse geo-coded to an address.
latitude	number	The latitude recorded to two decimal places.
longitude	number	The longitude recorded to two decimal places.
label	string	A location label created from the coordinates
shortLabel	string	A shortened location label created from the coordinates
destinationAddress	object	The destination location reverse geo-coded to an address.
latitude	number	The latitude recorded to two decimal places.
longitude	number	The longitude recorded to two decimal places.
label	string	A location label created from the coordinates
shortLabel	string	A shortened location label created from the coordinates
pickupTimeframe	object	The timeframe for picking up the shipment.
date1	date-time	The first date in the pickup timeframe.
date2	date-time	The last date in the pickup timeframe.
date1Offset	date-time	The date offset for the first date.
date2Offset	date-time	The date offset for the second date.
timeFrameType	object	The type of timeframe
value	string	The value of timeframe type.
label	string	The label for the type of timeframe.
shortLabel	string	The label for the type of timeframe.
timeZone	string	The string representation of the timezone.
label	string	The full timeframe label with day, month, and year.
shortLabel	string	The timeframe with only the month and day.
shortLabelWithYear	string	The timeframe with the month, day, and year.
deliveryTimeframe	object	The timeframe for deliverying the shipment.
date1	date-time	The first date in the delivery timeframe.
date2	date-time	The last date in the delivery timeframe.
date1Offset	date-time	The date offset for the first date.
date2Offset	date-time	The date offset for the second date.
timeFrameType	object	The type of timeframe
value	string	The value of timeframe type.
label	string	The label for the type of timeframe.
shortLabel	string	The label for the type of timeframe.
timeZone	string	The string representation of the timezone.
label	string	The full timeframe label with day, month, and year.
shortLabel	string	The timeframe with only the month and day.
shortLabelWithYear	string	The timeframe with the month, day, and year.
currentTransitStatus	object	The current transit status of the listing.
value	string	The value for the current transit status
label	string	The label for the transit status
shortLabel	string	The label for the transit status
carrierContactModel	object	The contact information for the carrier
name	string	The name of the carrier
companyName	string	The carrier's company name.
username	string	The carrier's username.
user	object	Information about the carrier.
userId	integer	The carrier's user ID.
displayName	string	The name to display for the carrier
imageUrl	string	The url to the carrier's profile image.
profileUrl	string	The url to the carrier's profile.
feedback	object	The feedback scores for the carrier
count	integer	The number of reviews
percentPositive	number	The positive score to one decmial place.
starRating	number	The overall score from all reviews based on a five star score. The value is to one decimal place.
aboutMe	string	The about statement from the carrier's profile.
dateCreated	string	The creation date of the carrier account.
companyLocation	object	The location of the carrier's company.
majorMunicipality	string	The city near the carrier's company.
stateProvince	string	The state or province the carrier's company is located.
directoryCategories	array[object]	The list of categories the carrier handles.
value	string	The value of the category.
label	string	The label for the category.
shortLabel	string	The label for the category.
links	array[object]	The list of available links associated with the carrier.
verb	string	HTTP method associated with the link.
href	string	The url for the link
title	string	label for the link
shipmentTrackingStatuses	array[object]	The list of tracking statuses and when they were set
status	string	The tracking status.
punctuality	object	Whether the status was set by the agreed date.
value	string	The value for the punctuality.
label	string	The label for the punctuality.
shortLabel	string	The shortened label for the punctuality.
recorded	string	The date/time when the status was recorded.
mostRecentLocation	array[object]	The last recorded location of your shipment.
recorded	string	The time the location was noted
latitude	number	The latitude recorded to two decimal points
longitude	number	The longitude recorded to two decimal points
mostRecentAddress	array[object]	The last recorded location reverse geo-coded to an address. Will not be returned if not available.
latitude	number	The latitude recorded to two decimal points
longitude	number	The longitude recorded to two decimal points
label	string	A location label created from the coordinates
shortLabel	string	A shortened location label created from the coordinates

Expand

Response

xxxxxxxxxx
 
{
 "listingGeneratedId": "{integer}", "listingTitle": "{string}", "commodityCode": "{string}", "shipmentTrackingSummaryModel": {...},
 "carrierContactModel": {...},
 "shipmentTrackingStatuses": [...],
 "mostRecentLocation": [...],
 "mostRecentAddress": [...]
}
Copy