Complete API reference for LTL Direct freight shipping, including rate requests, listing management, Bill of Lading, and tracking.


Getting Started

Base URLs

Environment URL Description
Sandbox https://api.ushipsandbox.com Test environment for development
Production https://api.uship.com Live production environment

Note: Sandbox and production environments require separate API keys.


Authentication

All API requests require Bearer token authentication.

Obtaining Your API Key

  1. Navigate to API Key Generation Page
  2. Generate your API key (specify sandbox or production)
  3. Include in all requests:
Authorization: Bearer <your_api_key>

Integration Guides

Guide Description
Sandbox Testing Guide Comprehensive sandbox testing documentation
uShip DeveloperHub Integration guides and tutorials

Support

For questions or assistance, contact: apisupport@uship.com

Server
https://api.uship.com

Production

https://api.ushipsandbox.com

Sandbox (Testing)

Server Variables

Self-serve Bearer token provided to you at https://www.uship.com/api-key-generation

Rate Requests

Create and manage rate requests. A rate request initiates the process of getting shipping quotes from carriers.

Get list of available rates for a rate request

Auth
Headers
Authorizationstring

Required. Required Authorization header containing access token

Path Params
idstring

Required. The rate request ID

Query String
developmentstring
GET /v2/raterequests/{id}/rates
Copy
Responses
200

200 response

v2RateRequestsRatesGet200Responseobject
totalCountnumber
items17 fieldsarray[object]

List of rates

401

Unauthorized

403

Forbidden

500

Internal server error

Response
Copy

Create a rate request

Auth
Headers
Authorizationstring

Required. Required Authorization header containing access token

Query String
developmentstring
Request Body
v2RateRequestsPostRequestobject
route1 fieldobject

Required. route

referenceNumbersarray[object]

Identifiers and numbers by which one can refer to this shipment or its cargo in some external system

numberstring

Required. The value of the reference number

typestring

Required. The type of reference number

Enum: Pickup,Delivery,Invoice,PurchaseOrder,SalesOrder,Other,Lot,Release,ThirdPartyTracking,PriceCorrelationId,ThirdPartyOrderNumber,VIN,SKU

items12 fieldsarray[object]

Required. LTL Items

integratorIdstring

The integrator id for the request. This is required to receive webhooks and custom rates

accessorialsarray[string]

Collection of service accessorials for this shipment

Enum: ProtectFromFreezing,BlindShipmentCoordination,SortAndSegregate,ExcessiveLength

POST /v2/raterequests
Copy
Responses
201

201 response

Headers
Locationstring

URL containing the rate request ID

400

Bad Request

401

Unauthorized

500

Internal server error

Response
Copy

Rates

Retrieve and select shipping rates. Rates represent pricing quotes from carriers for your shipment.

Accept a rate

Allows a shipper or an integrator on a shipper's behalf to accept a rate

Auth
Headers
Authorizationstring

Required. Required Authorization header containing access token

Path Params
idstring

Required. The rate ID to accept

Request Body
v2RatesAcceptancePostRequestobject
insurance1 fieldobject

Required. Insurance

paymentMethodIdstring

Required. Payment method ID

POST /v2/rates/{id}/acceptance
Copy
Responses
202

202 response

Headers
Locationstring

GET acceptance status endpoint

Body
v2RatesAcceptancePost202Responseobject
messagestring

Accepted message

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal server error

Response
Copy

Retrieves the status of a rate acceptance request

Auth
Headers
Authorizationstring

Required. Required Authorization header containing access token

Path Params
executionIdstring

Required. The execution ID returned from the rate acceptance request

idstring

Required. The rate ID

GET /v2/rates/{id}/acceptance/status/{executionId}
Copy
Responses
200

200 response

v2RatesAcceptanceStatusGet200Responseobject
responsestring

Stringified JSON response of the rate acceptance request

statusCodenumber

The API response status code of the rate acceptance request

201

201 response

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

Response
Copy

Listings

Manage freight listings. Listings represent shipments in the uShip marketplace.

Retrieves a listing from the uShip Marketplace by listingId

Allows integrator to retrieve listing information by listing ID

Auth
Path Params
listingIdinteger

Required. listingId of the listing that is to be returned

GET /v2/listings/{listingId}
Copy
Responses
200

OK

objectobject
status3 fieldsobject

Details of an enum that can be translated

paymentStatus3 fieldsobject

Details of an enum that can be translated

transitStatus3 fieldsobject

Details of an enum that can be translated

cancellationStatus3 fieldsobject

Details of an enum that can be translated

hasPendingBookingRequestboolean
galleryarray[string]
isCharitableboolean
isAuctionboolean
isDutchAuctionboolean
autoAcceptPrice4 fieldsobject

The details of a price and recommended formatting

auctionTargetPrice4 fieldsobject

The details of a price and recommended formatting

auctionMaxPrice4 fieldsobject

The details of a price and recommended formatting

namedPrice4 fieldsobject

Required. named price

offerPrice5 fieldsobject

The details of an offer

lowestBidPrice4 fieldsobject

The details of a price and recommended formatting

acceptedBidPrice4 fieldsobject

The details of a price and recommended formatting

totalCost4 fieldsobject

The details of a price and recommended formatting

bookingDeposit4 fieldsobject

The details of a price and recommended formatting

amountDueToServiceProvider4 fieldsobject

The details of a price and recommended formatting

amountToMe4 fieldsobject

The details of a price and recommended formatting

priceDetails1 fieldobject

An aggregate of line items of a transaction

commoditystring
parentCommoditystring
topLevelCommoditystring
expiresOndate-time
questionsAskedint32
activeBidsPlacedint32
totalBidsPlacedint32
imageUrlstring
isDefaultImageboolean
checksumstring
isWatchedboolean
createdOndate-time
activatedOndate-time
lastUpdatedOndate-time
isBrokeredboolean
bookedOndate-time
completedOndate-time
cancelledOndate-time
archivedOndate-time
serviceProvider22 fieldsobject

Public representation of a user

assignedDriver22 fieldsobject

Public representation of a user

isReadyForPickupboolean
billOfLadingNumberint32
uShipPayments2 fieldsobject
minimumBidAmount4 fieldsobject

The details of a price and recommended formatting

privateNetworkstring
cancellationLinkstring

A link to the cancellation process web page

quoteRequestIdstring

ID that was used for quote request (only for published rates)

commodityType3 fieldsobject

Details of an enum that can be translated

parentCommodityType3 fieldsobject

Details of an enum that can be translated

topLevelCommodityType3 fieldsobject

Details of an enum that can be translated

isItineraryMandatoryboolean
thirdParty6 fieldsobject

Some Listings created in uShip are the direct result of data in some external system. For example, a Shipper may have their own TMS, which contains the authoritative, definitive information the cargo, timeframe, pickup, and dropoff associated with a uShip Shipment or Listing. This object stores specifies the provenance, identity, and revision/change information of a uShip Shipment or Listing created from such an external source.

serviceTypes3 fieldsarray[object]

required services for this Shipment's cargo (e.g., blanket wrapping is required)

isExclusiveListingboolean

A flag to indicate whether or not a listing is exclusive to any network

listingIdint32

Required. unique, public, numeric identifier of this Shipment

titlestring

Required. free text, ASCII, maximum of 50 characters

descriptionstring

free text, ASCII; maximum of 5000 characters may be empty or absent if none was specified

route2 fieldsobject

Container for route destinations and other route information

lister22 fieldsobject

Public representation of a user

items4 fieldsarray[object]

details of the cargo(s) to be transported

accessorialsarray

accessorials required by the Shipper; e.g., the cargo must not be allowed to freeze

totalWeightInGrams3 fieldsobject

Weight of an item in grams

attributesobject
nextTransitStatus3 fieldsobject

Details of an enum that can be translated

previousTransitStatus3 fieldsobject

Details of an enum that can be translated

availableTransitStatusesarray
referenceNumbers3 fieldsarray[object]

These are identifiers and numbers by which refer to this Shipment or its cargo in some external system. If this Shipment is "owned" by an external system, prefer the ThirdParty property, as those fields are searchable and affect some uShip behavior.

importSourcestring
links4 fieldsarray[object]

Required. The resource's links

Response
Copy

Listings Attachments

Manage attachments associated with listings, such as photos or documents.

Retrieves listing attachment information

Allows integrator to retrieve listing attachments by listing ID

Auth
Path Params
listingIdinteger

Required. listingId

attachmentIdinteger

Required. attachmentId

GET /v2/listings/{listingId}/attachments/{attachmentId}
Responses
200

OK

objectobject
attachmentIdstring
uristring
fileNamestring
fileTypestring
fileSizeint64
dateCreateddate-time
uploaderIdint64
attachmentType3 fieldsobject

Details of an enum that can be translated

notesstring
links4 fieldsarray[object]

Required. The resource's links

Response

Payment Methods

Manage payment methods for booking shipments.

Get All User's Payment Methods

Auth
Headers
Authorizationstring

Required. Required Authorization header containing access token

Query String
topLevelCommoditystring

Required. Required top level commodity

GET /v2/paymentmethods
Responses
200

Successfully retrieved payment methods

v2PaymentMethodsGet200Responseobject
totalCountnumber
items
objectobject

Credit Card

lastFourstring

Last four digits of credit card number

isPrimaryboolean

Indicates if default card or not

activeboolean

Indicates whether account is active or not

expirationobject
monthnumber

Expiration month

yearnumber

Expiration year

idstring

Unique ID

typeobject
valuestring

Type of payment method

Enum: creditcard,bankaccount,payonterms

issuerstring

Issuing institution

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal server error

501

Top level commodity not implemented yet

Response

Tracking

Track shipment status and location updates.

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
Authorizationstring

Required. Bearer {your password grant bearer token}

Path Params
listingIdinteger

Required. listingId

GET /v2/listings/{listingId}/track
Responses
200

OK

objectobject
listingGeneratedIdinteger

The ID for your listing

listingTitlestring

The title of your listing

commodityCodestring

Displays CarsLightTrucks

shipmentTrackingSummaryModel5 fieldsobject
carrierContactModel4 fieldsobject

The contact information for the carrier

shipmentTrackingStatuses3 fieldsarray[object]

The list of tracking statuses and when they were set

mostRecentLocation3 fieldsarray[object]

The last recorded location of your shipment.

mostRecentAddress4 fieldsarray[object]

The last recorded location reverse geo-coded to an address. Will not be returned if not available.

Response

Bill Of Lading

Retrieve Bill of Lading documents. The BOL is the official shipping contract between shipper and carrier.

Get the preSigned url for bill of lading

Auth
Headers
Authorizationstring

Required. Required Authorization header containing access token

Path Params
idstring

Required. The listing ID

GET /v2/listings/{id}/billoflading
Responses
200

200 response

v2ListingBillofLadingGet200Responseobject
billOfLadingNumbernumber
documentobject

pre-signed url to access the bill of lading

hrefstring

pre-signed url

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

Response

listing booked webhook

webhook sent when a listing is booked through an integration

Request Body

Information about the booked listing

objectobject
specversionstring

The version of the CloudEvents specification which the event uses. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#specversion

Enum: 1.0

sourcestring

Identifies the context in which an event happened. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

iduuid

Identifies the event. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#id

timedate-time

Timestamp of when the occurrence happened in ISO-8601 format. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time

typestring

Type of event related to the originating occurrence. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type

Enum: Listing.Booked/v1

data4 fieldsobject
POST ListingBooked
Responses
200

Return a 200 status to indicate that the data was received successfully

No response body
Response

transit status changed webhook

Request Body

Information about the booked transit status change

objectobject
specversionstring

The version of the CloudEvents specification which the event uses. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#specversion

Enum: 1.0

sourcestring

Identifies the context in which an event happened. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

iduuid

Identifies the event. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#id

timedate-time

Timestamp of when the occurrence happened in ISO-8601 format. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time

typestring

Type of event related to the originating occurrence. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type

Enum: Shipment.TransitStatusChanged/v1

data4 fieldsobject
POST ShipmentTransitStatusChanged
Responses
200

Return a 200 status to indicate that the data was received successfully

No response body
Response

listing reference number added webhook

Request Body

Information about the reference number

objectobject
specversionstring

The version of the CloudEvents specification which the event uses. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#specversion

Enum: 1.0

sourcestring

Identifies the context in which an event happened. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

iduuid

Identifies the event. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#id

timedate-time

Timestamp of when the occurrence happened in ISO-8601 format. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time

typestring

Type of event related to the originating occurrence. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type

Enum: Listing.ReferenceNumberAdded/v1

data4 fieldsobject
POST ListingReferenceNumberAdded
Responses
200

Return a 200 status to indicate that the data was received successfully

No response body
Response

listing status changed webhook

Request Body

Information about the status change

objectobject
specversionstring

The version of the CloudEvents specification which the event uses. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#specversion

Enum: 1.0

sourcestring

Identifies the context in which an event happened. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

iduuid

Identifies the event. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#id

timedate-time

Timestamp of when the occurrence happened in ISO-8601 format. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time

typestring

Type of event related to the originating occurrence. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type

Enum: Listing.StatusChanged/v1

data3 fieldsobject
POST ListingStatusChanged
Responses
200

Return a 200 status to indicate that the data was received successfully

No response body
Response

shipment delivery timeframe updated webhook

Request Body

Information about the delivery timeframe

objectobject
specversionstring

The version of the CloudEvents specification which the event uses. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#specversion

Enum: 1.0

sourcestring

Identifies the context in which an event happened. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

iduuid

Identifies the event. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#id

timedate-time

Timestamp of when the occurrence happened in ISO-8601 format. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time

typestring

Type of event related to the originating occurrence. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type

Enum: Shipment.DeliveryTimeFrameUpdated/v1

data3 fieldsobject
POST ShipmentDeliveryTimeFrameUpdated
Responses
200

Return a 200 status to indicate that the data was received successfully

No response body
Response

listing attachment added webhook

Request Body

Information about the attachment

objectobject
specversionstring

The version of the CloudEvents specification which the event uses. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#specversion

Enum: 1.0

sourcestring

Identifies the context in which an event happened. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

iduuid

Identifies the event. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#id

timedate-time

Timestamp of when the occurrence happened in ISO-8601 format. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time

typestring

Type of event related to the originating occurrence. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type

Enum: Listing.Attachment.AttachmentAdded/v1

data8 fieldsobject
POST ListingAttachmentAdded
Responses
200

Return a 200 status to indicate that the data was received successfully

No response body
Response

listing price details updated webhook

Request Body

Information about the price details

objectobject
specversionstring

The version of the CloudEvents specification which the event uses. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#specversion

Enum: 1.0

sourcestring

Identifies the context in which an event happened. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

iduuid

Identifies the event. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#id

timedate-time

Timestamp of when the occurrence happened in ISO-8601 format. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time

typestring

Type of event related to the originating occurrence. See https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#type

Enum: Listing.PriceDetailsUpdated/v1

data4 fieldsobject
POST ListingPriceDetailsUpdated
Responses
200

Return a 200 status to indicate that the data was received successfully

No response body
Response