Bids


GET

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

Returns a read-only JSON body with the active Service Provider's bids.

 

Response

Localized examples are in the following language order (from left to right):

  1. US (English)
  2. FR (French)
  3. DE (German)

Bid Container

Field Type Description Sample Valid Values
totalCount
Integer The sum of bids with corresponding matched listings objects returned. 48, 133
items
Container Wrapper for the collection of matched bid/listings objects returned. -

 

Bid Object

Field Type Description

Sample Valid Values

bidId
Integer Identifier of the bid the Shipper accepted on the listing. 1234567
expirationDate
String When the bid expires (in UTC). "2015-12-29T19:35:45Z"
bidder
Container Wrapper for the fields that identify the winning or matched bid. -
userId
Integer Identifier for the Service Provider who bid on the listing. 12345678
displayName
String

The name that displays in the marketplace for the active user. Generally, this is the user's company name. If the account doesn't have a company name, the username appears.

"ABC Transport Company" | "Jane S."
imageUrl
String

The web address or server path where the Service Provider's profile image is stored.


feedback
Container Wrapper for the feedback fields that determine a user's marketplace ratings through uShip. -
count
Integer The total number of feedback entries available for this user. 15, 80, or 455
percentPositive
Decimal The percentage of positive ratings for this user out of 100%. 98.5
starRating
Decimal The average number of stars out of the total stars received for this user. One star being the lowest and five stars being the highest rating. 4.8  
links
Hypermedia Array The relevant hypermedia link(s) objects for the bid. A hypermedia link suggests what a user can do next in the relevant context or contexts. Here is an example where you can retrieve the bidder's profile. The number in the href is the userId of the bidder "/v2/users/{userId}/profile".
 {
   "rel": "Item",
   "verb": "GET",
   "href": "/v2/users/114114/profile",
   "title": "profile"
 }



Field Type Description

Sample Valid Values

pickupTimeframe
Container Wrapper for the shipment pick up time frame fields. -
deliveryTimeframe
Container Wrapper for shipment delivery time frame fields. -
delay
Integer

The number of days after the specified pick up or delivery date. Only appears with the "Relative" time frame type.

2, 3
timeFrameType
Container Wrapper for the pick up or delivery time frame type. -
value
String

The pick up and delivery time frame types for bids. Valid values are as follows:

  • Arrange - Shipping Customer and Service Provider will arrange the pick up or delivery time frame after booking.
  • Before - The pick up or delivery will be made before a specified time frame.
  • Between - The pick up or delivery will be made between specified time frames.
  • OnDate - The pick up or delivery will be made on a specified date.
  • Relative - The pick up or delivery will be a specified number of days before or after a specified time frame.
"Relative"
label
String The localized description of the time frame type. "Relative" | "Relatif" | "Relativ"
shortLabel
String Grouped with the time frame type data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable. "Relative" | "Relatif" | "Relativ"
timeZone
String Returns the pick up or delivery time zone. "America/Los_Angeles" or "America/Chicago"
label
 String

The localized description of the time frame for pick up or delivery.

Example Set 1

  • "Within 2 days of booking"
  • "Dans les 2 jours après la réservation"
  • "Innerhalb von 2 Tagen nach Buchung"

Example Set 2

  • "Within 3 days of pickup"
  • "Dans les 3 jours après enlèvement"
  • "Innerhalb von 2 Tagen nach Buchung"

shortLabel

 String

The localized string for the time zone data as shown on a mobile or touch device.

  • "Within 2 days of booking"
  • "Dans les 2 jours après la réservation"
  • "Innerhalb von 2 Tagen nach Buchung"

 

Field Type Description

Sample Valid Values

serviceType
 Container

 Wrapper for the service types that the listing would accept.

 -
value
 String Get-only, read-only. However, obtain the list of valid values from the GET Service Type Lookup API.  "OpenTransport"
label
 String The localized name of the service type the Service Provider can provide. "Open Transport" |  "Transport ouvert" | "Offener Transport"
shortLabel
 String Grouped with the service type data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable. "Open Transport" |  "Transport ouvert" | "Offener Transport"

 

Field Type Description

Sample Valid Values

transportMode
 Container  Wrapper for the transport mode that the Service Provider can provide.  -
value
 String The transport mode that the Service Provider provides.

Valid Values:

  • Trucking
  • Air
  • Rail
  • Ocean
  • Intermodal
  • Driveaway
"Intermodal"
label
 String The localized name for the transport mode. "Intermodal" 
shortLabel
 String Grouped with the transport mode data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable. "Intermodal"

 

Field Type Description

Sample Valid Values

vehicleType
Only appears for related commodity. Same value, label, shortLabel data set. "Car"
additionalInformation
 String Description about the bid that covers details not in the preceding fields. "The Service Provider can mention anything else to a Shipper about the bid made for a particular listing."
additionalPaymentTerms
String Description about payment details the Service Provider wants to communicate to the Shipping Customer. "The Service Provider can mention anything else to a Shipper about payment terms."
dateCreated
String The date and time in UTC when the Service Provider made the bid. "2013-01-16T00:10:07Z"
status
Container Wrapper for the bid status. -
value
String The bid status. 
  • Active
  • Accepted
  • Cancelled
  • Declined
  • Expired
  • Retracted
"Active"
label
String The localized name of the bid status. "Active" | "Actif" | "Aktif"
shortLabel
String Grouped with the bid status data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable. "Active" | "Actif" | "Aktif"
price
Container Wrapper for the bid price fields. -
value
Decimal The accepted bid price. 299.36
label
Decimal The localized version of the accepted bid price. This field is not affected by headers such as accept-language. The locale code is in the Preferences API. "$299.36" | "299,36 $"
shortLabel
Decimal Grouped with the bid price data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable. "$299.36" | "299,36 $"
locationTracking
Container Wrapper for how the Service Provider/Shipment location is tracked during transport from origin to destination. -
value
String

Types of location updates currently available to Service Providers.

Valid Values:

  • "FromGPS" - The Service Provider can provide location updates to the Shipper via GPS.
  • "FromUser"  - The Service Provider can provide manual location updates.
"FromUser"
label
String The localized name for the shipment location update type. "From GPS"
shortLabel
String Grouped with the location tracking data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable. "From GPS"
paymentMethods
Array List of payment method items. -
value
String

The payment methods that the Service Provider accepts from the Shipping Customer. 

  • Cash
  • CreditCard
  • Check
  • PayPal
  • MoneyOrder
  • Other 
  • uShipPayments - Service Provider selects to only accept uShip Payments. By default, as listed in the uShip User Agreement, all listings below a certain threshold can only use uShip Payments.
"uShipPayments"
label
String The localized names of the payment methods that the Service Provider accepts. "uShip Payments Only" | "Paiement uShip uniquement" | "Ausschließlich uShip Zahlungen"
shortLabel
String Grouped with the payment method data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable.
"uShip Payments Only" | "Paiement uShip uniquement" | "Ausschließlich uShip Zahlungen"
paymentTimes
Array List of payment time items. -
value
String The payment times that the Service Provider accepts from the Shipper. "AtDelivery"
label
String The localized name of the accepted payment time. "At Delivery" | "À la livraison" | "Bei Lieferung"
shortLabel
String Grouped with the payment  time data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable. "At Delivery" | "À la livraison" | "Bei Lieferung"

 

Listing Object

Field Type Description

Sample Valid Values

listing
Container Wrapper for the listing object that matched the corresponding bid object. -
listingId
Integer Unique identifier for the listing. 123456789
title
String The descriptive name of the listing. "Auction Created by Name on Date"
imageUrl
String The web address or server path where the listing image is stored.

route
 Container Wrapper for physical transport route details.  -
distance
 Container Wrapper for the total distance traveled for the route.  -
kilometers
 Decimal The total number of kilometers traveled for the listing route.  2290.0908
label
 String The localized string description of the distance traveled for the listing route.  "1423 mi."
shortLabel
 String The localized string for the route distance as shown on a mobile or touch device.  "1423 mi."

Listing Route

See Route Object reference.

 

Additional Bid Objects

Field Type Description Sample Valid Values
expiresOn
 String  The date and time when the bid expires (in UTC). "2013-01-21T00:09:24Z"
commodity
 String The category where the listing appears on uShip. Obtain from the GET Commodities Lookup API. "Cars & Light Trucks" | "Voitures et camionnettes" | "Autos"
parentCommodity
 String The main category where the sub-commodity category belongs. Vehicles | "Véhicules" | "Fahrzeuge"
totalBidsPlaced
 Integer The total number of bids placed on this listing.  5
isReadyforPickup
Boolean
  • true - The shipment is ready for the Service Provider to pick up from the origin location.
  • false - The shipment is not ready for the Service Provider to pick up.
"true" or "false"

 

Pricing

Field Type Description
isAuction
  • true - The bid is tied to an auction.
  • false - The bid is not tied to an auction.
"true" or "false"

 

Field Type Description
auctionMaxPrice
Container Wrapper for the fields that describe the highest auction price.
value
Integer The maximum auction price. Example: 4000
label
String The localized string for the maximum auction price. Example:"$4,000.00"
shortLabel
String The localized string for the maximum auction price as shown on a mobile or touch device.



Field Type Description
auctionTargetPrice
Container The Shipper's desired optimal price where they want to accept an auction bid.
value
Integer The target auction price. Example: 3000
label
String The localized string for the target auction price. Example: "$3,000.00"
shortLabel
String The localized string for the target auction price as shown on a mobile or touch device.

 

Field Type Description
lowestBidPrice
Container Wrapper for the fields that describe the lowest bid price.
value
String The lowest bid price. Example: 800
label
String The localized version of the lowest bid price amount. Example: "$800.00"
shortLabel
String The localized string for the lowest bid price amount for the mobile or touch device.

 

Hypermedia Links

Field Type Description Sample Valid Values
links
Array Wrapper for the hypermedia links following a bid. 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.  "Item"
verb
String

This field is the HTTP 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.
"GET"
href
String This hypermedia reference attribute specifies the URL of the page link destination. This reference link suggests what actions are possible.  "/v2/listings/{listingId}"
title
String The descriptive name of the possible action. "listing"