Retrieve Listings


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

  • Retrieves listings by specifying a user type.
  • Filters the listings by listing status and/or transit status.

If the user has permission, display all of the listings...

  • for the particular user type.
  • with specific listing status(es).
  • with particular transit status(es).

 

Query Parameters

Parameter Description
userType

Specifies whether to return listings when the user is the Shipper or the Service Provider. If the user is either only a Shipper or a ServiceProvider role, then specifying the userType is not required.

Shipper - The customer with a shipping need. Specifying this value in the filter will limit listing results to listings that the user created as a Shipper.

ServiceProvider - A broker or carrier who provides shipping services. Specifying this value in the filter will limit listing results to listings that the user successfully booked and committed to transporting. Listings with pending bids will not return.

In case of a driver network, if a listing has been assigned to a driver, it can be retrieved by the driver or the dispatcher with the serviceProvider userType. 

status

Filter the listings by choosing the listing status. Only listings with the specified listing statuses return. When none are specified, the API returns listings for all statuses.

See Listing Statuses for resulting listing display status. Use one or more of the following valid values:

  • Active
  • Booked
  • Closed
  • Completed
  • Deleted
  • Saved
  • Archived
  • OnHold
transitStatus

Filter the listings by choosing the transit status. Only listings returned with the specified transit statuses return. A listing with transit statuses will only return if it has an accepted bid.

See Tracking Overview and Tracking Reference for the resulting display status. Use one or more of the following valid values:

  • ReadyForDispatch
  • Dispatched
  • PickedUp
  • Delivered

Pagination

Use to organize the response for a collection of items. We currently only support the following oData query string parameters.

Parameter Type Description
$orderby
String

Sort results by the following properties:

Query parameter value | Corresponding output model property

  • DateUpdated | lastUpdatedOn
  • AcceptedBid / DateAccepted | bookedOn
  • DateCreated | createdOn
  • ExpiresOn
$skip
Integer Positive integer for the number of previous entries to pass over before returning results.
$top
Integer Positive integer that specifies how many total items to return from the collection following any skipped entries.


Response

Returns a read-only array of listings.


totalCount The total number of listings returned in the request expressed as a positive whole integer.

Listing Items

Pricing

Not all fields will return in the response body. 

Field Type Description
isAuction
Boolean
  • true - A Service Provider can place a bid on the listing if the listing is active and available.
  • false - The listing is not tied to an auction. This field will not appear in the response body.
isDutchAuction
Boolean Only available for certain commodities. uShip Internal. Will not return with isAuction.
  • true - The listing is tied to a dutch auction.
  • false - The listing is not tied to a dutch auction.

 

Field Type Description
acceptedBidPrice
Container Wrapper for the fields describing the bid price the Shipping Customer accepted on the listing.
value
Decimal The accepted bid amount.
label
String The localized string for the accepted bid amount.
shortLabel
String The localized string for the accepted bid amount optimized for a mobile or touch device screen.

 

Field Type Description
autoAcceptPrice
Container

Wrapper for the fields describing the automatically accepted bid price on this listing.

  • If this field is present in the returned body, indicates the listing is a brokered listing with a Book It Now bid price.
  • If absent, the listing is not a Book It Now bid price.
value
Decimal The automatically accepted Book It Now bid price.
label
String The localized string for the automatically accepted bid price.
shortLabel
String The localized string for the automatically accepted bid price optimized for a mobile or touch device screen.

 

Field Type Description
offerPrice/namedPrice
Container

Wrapper for the fields describing the offerPrice accepted on the listing. 

The offer price occurs when the listing has a set price and only bids at that price are accepted or rejected. When a bid is received, the listing is given an "onHold" status (not visible or bookable on uShip).

This status gives the Shipper the opportunity to accept or decline the Service Provider's bid and enter in their payment information to confirm.

value
Decimal The offer or named price.
label
String The localized string for the offer or named price.
shortLabel
String The localized string for the offer or named price optimized for a mobile or touch device screen.

 


Lister

See Lister Objects description.

 

Assigned Driver

See the Assigned Driver Object description.

 

Status

Describes the current listing status. See Listing Statuses for resulting listing display status.

Field Type Description
value
String The listing status.
label
String The localized string description of the listing status.
shortLabel
String The localized string for the listing status as shown on a mobile or touch device.

 

Transit Status

Describes the listing transit status. A listing will only have a transit status if the listing has been booked by a Service Provider. See Tracking Reference.

Field Type Description
value
String The listing transit status.
label
String The localized string description of the listing transit status.
shortLabel
String The localized string for the listing transit status as shown on a mobile or touch device.

 

Listing Items

Field Type Description
createdOn
String The date and time in UTC when the Lister first created the listing.
expiresOn
String The date and time in UTC when the listing expires.
lastUpdatedOn
String The most recent date and time in UTC when the Lister changed or updated the listing.
bookedOn
String
The date and time in UTC when the Shipping Customer booked the listing. This field only returns when the listing status is "Booked" and the transit status is "ReadyForDispatch".
completedOn
String
The date and time in UTC when the Service Provider delivered the listing. This field only returns when the listing status is "Completed" and the transit status is "Delivered".
listingId
Integer Unique identifier for the listing.
title
String The descriptive name of the listing.
imageUrl
String The web address or server path where the listing image is stored.

 

Route

See Route Object for reference.


Additional Listing Items

Field Type Description
commodity
String

The category where the listing appears on uShip. The subCommodities value from its associated parent-level category appears.

A list of valid values can be obtained from the GET Commodities Lookup API (https://api.uship.com/v2/lookups/commodities/).

Consult with api-support@uship.com if you have questions about the category or subcategory that returns.

parentCommodity
String The parent-level/main category where the listing appears on uShip. 
totalBidsPlaced
Integer The total number of bids placed on the listing before the listing expired.
isBrokered
Boolean
  • true - A broker created the listing.
  • false - A broker did not create the listing. This field will not appear in the response body.
isReadyForPickup
Boolean This field returns as “true”  when the shipment is ready for pick up upon listing. Otherwise, it is not returned.
topLevelCommodity
String This field is the parentCommodity.
links
Hypermedia links This array will only return if there is more than 25 entries to allow an application to fetch the next set of listings.
{
  "rel": "Next",
  "verb": "GET",
  "href": "/v2/listings?userType=ServiceProvider&access_token={token}&$skip=25",
  "title": "listings"
}