Retrieve Listing


GET URI https://api.uship.com/v2/listings/{listingsId}/

Retrieve a single listing by specifying the listing ID. Obtain a listing ID from the GET listings API (https://api.uship.com/v2/listings/).

What is a listing?

A listing is the object that a Shipper or Broker creates for a load or shipment indicating the need for shipping services.

  • If a listing is booked, the collection of information about the Service Provider who booked the listing is included.
  • Once a shipment has been booked, the shipment status will include the transit status.

Use Cases

  • the ability to view the listing. 
  • corresponding hypermedia links return based on permissions and shipment status.

Localization

Localized examples are in the following language order, when provided EN (English) | FR (French) | DE (German). The examples are separated by the | vertical bar. The uShip API supports language values in the Accept-Language request header.

Authentication

uShip.com endpoints that contain /v2/ in the URI require OAuth 2.

Response

Returns the read-only JSON body of a single listing.


Status

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

Field Type Description
value

String

The current display status of the listing. Example: "Active"

label
String The localized name of the listing status. Example: "Active" | "Actif" | "Aktif"
shortLabel
String

This field appears with all current value/label pairs. Intended for mobile application and mobile responsive consumers.

The shortened labels display on smaller screens and default to "label" with shortened content if the "shortLabel" is unavailable. 

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 current transit status of the listing. Example: "ReadyForDispatch"

label
String The localized name of the transit status. Example: "Booked"
shortLabel
String

This field appears with all current value/label pairs. Intended for mobile application and mobile responsive consumers.

The shortened labels display on smaller screens and default to "label" with shortened content if the "shortLabel" is unavailable. 



Pricing

See Pricing Object description.

 

Route

See Route Object description.


Lister

See Lister Objects description.

 

Listing

Field Type Description
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
  • true - The shipment is ready for the Service Provider to pick up from the origin location when the listing is created.
  • false - The shipment is not ready for the Service Provider to pick up immediately.
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/).

Example: "Cars & Light Trucks"

parentCommodity
String

The parent-level/main category the listing appears on uShip.

Example: "Vehicles"

topLevelCommodity
String This field is the parentCommodity. 
listingId
Integer Unique identifier for the listing.
title
String The descriptive name of the listing.
description
String Overall description for the listing (which can contain several items).
activeBidsPlaced
Integer The number of active bids placed on this listing. An active bid is one where the Service Provider is eligible to bid on the listing and the bid has not expired.
totalBidsPlaced
Integer The total number of bids placed on the listing before the listing expired.
imageUrl
String The web address or server path where the listing image is stored.
createdOn
String The date and time in UTC when the Lister first created the listing.
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" or "Completed".
expiresOn
String The date and time in UTC when the listing expires. Example: "2015-02-18T20:05:03Z"
completedOn
String The date and time in UTC when the listing was completed. This field only returns when the listing status is "Completed" and the transit status is "Delivered".
checksum
String The checksum verifies that the listing has not changed since it was originally created. The verification is a unique string identifier that changes any time a user or the system updates relevant data that affects pricing. 



Listing Items

See the Listing Items Object description

 

Service Provider

See the Service Provider Object description.

 

 

Assigned Driver

See the Assigned Driver Object description.

 

 

Hypermedia Links


If the user and permissions allow, the related hypermedia links appear to suggest what can be done. For example, a mobile developer uses these links to show the button associated with the action. We recommend and encourage developers to focus on the “rel” and “title” fields to relate links to specific actions. 

 

Field Type Description Sample Valid Value
Links
Array

Wrapper for the hypermedia links that create the desired object. Hypermedia links suggest what a user can do next in the relevant context.

-

Rel
String This field describes which object the link is related to such as the ability to complete a function in a certain context. This reference is one of the possible actions that can be done. “Create”
Verb
String This field is the REST verb associated with the possible action that can be done.
  • GET - Retrieve an object or array of objects.
  • PUT - Update an existing object or array of objects.
  • POST - Create a new instance of an object or array of objects.
  • DELETE - Remove an object or array of objects.
“POST”
Href
String This hypertext reference attribute specifies the URL of the page link destination. This reference link suggests what actions are possible. “/v2/listings/listingId/bids”,
Tile
String The descriptive name of the possible action. “bidAtNamedPrice”

Sample Hypermedia Link Array

Example of a set of hypermedia links that return for a booked listing that is ready for dispatch.

"links": [{
        "rel": "Create",
        "verb": "POST",
        "href": "/v2/listings/123456789/feedback",
        "title": "feedback"
    }, {
        "rel": "Create",
        "verb": "POST",
        "href": "/v2/listings/123456789/delivered",
        "title": "delivered"
    }, {
        "rel": "Create",
        "verb": "POST",
        "href": "/v2/listings/123456789/dispatched",
        "title": "dispatched"
    }, {
        "rel": "Create",
        "verb": "POST",
        "href": "/v2/listings/123456789/pickedup",
        "title": "pickedUp"
    }, {
        "rel": "Item",
        "verb": "GET",
        "href": "/v2/listings/123456789/bids/8765432",
        "title": "acceptedBid"
    }, {
        "rel": "List",
        "verb": "GET",
        "href": "/v2/listings/123456789/bids",
        "title": "bids"
    }, {
        "rel": "Item",
        "verb": "GET",
        "href": "/v2/listings/123456789/contacts",
        "title": "contacts"
    }, {
        "rel": "List",
        "verb": "GET",
        "href": "/v2/listings/123456789/conversations",
        "title": "listingconversations"
    }, {
        "rel": "Item",
        "verb": "GET",
        "href": "/v2/listings/123456789/transitstatuses",
        "title": "transitstatus"
    }]