Creating Bookings

This guide walks you through creating shipment bookings. After a booking is successfully created, a background process will transmit shipment details to the appropriate carrier and return labels and/or a bill of lading. Use Get Bookings to retreive the generated tracking numbers and labels. One or more bookings can be created in a batch.


JUSDA uses API keys for authentication. At this time API keys are assigned by JUSDA's Technology Team. To obtain a key, contact your JUSDA Sales representative.

Once you have an API key, to authenticate, it will be necessary to pass the key in the HTTP header of each call you make. For the header key pass x-api-key. Pass your key as the value. For example: x-api-key=34A81032-979E-4EFC-9A6F-87E2973F3E20

If there is any problem authenticating your key, the API will respond with an HTTP 401 code.


JUSDA may provide you an API key that is set to our test environment. Rates returned by the test key may not be rates you'll get in production. If instead you have a production API key, it's possible to use the test environment on any API call by including an environment attribute in the endpoint's query string. For example:

API Endpoint

The URL for JUSDA Rate APIs is:

Use an HTTP POST with the approprate payload as described below.

Post Bookings Payload

Craft a JSON payload as shown below. Note that this endpoint expects an array of one or more bookings to be provided. Key properties of the payload:

  • bookingIdentifier: (optional) Your internal reference number. Will be stored in JUSDA's system and returned in the response payload
  • rateResponseId: (optional) Reference a specific rate that was quoted on the Rate API for this booking
  • quoteId: (optional) Reference a specific quoteId that has been provided by JUSDA
  • mode: (required) Parcel or LTL
  • shipperName: (required) Character limits: UPS(35), FedEx(35)
  • shipperAddress1: (required) Character limits: UPS(35), FedEx(35)
  • shipperAddress2: (optional) Character limits: UPS(35), FedEx(35)
  • shipperCity: (required)
  • shipperStateProvince: (required)
  • shipperPostalCode: (required) ZIP code or postal code
  • shipperCountry: (required) 2 digit ISO country code like US or CN
  • shipperTelNo: (optional) 310-875-9124
  • shipToName: (required) Character limits: UPS(35), FedEx(35)
  • shipToAddress1: (required) Character limits: UPS(35), FedEx(35)
  • shipToAddress2: (optional) Character limits: UPS(35), FedEx(35)
  • shipToCity: (required)
  • shipToStateProvince: (required)
  • shipToPostalCode: (required) ZIP code or postal code
  • shipToCountry: (required) 2 digit ISO country code like US or CN
  • shipToTelNo: (optional) 847-439-2727
  • residential: (optional) boolean, default value is false
  • carrierName: (required) Carrier to book with such as FEDEX or UPS
  • serviceLevel: (required) Service to book with such as FedEx Ground or UPS UPS 2nd Day Air. For a list of supported service levels, check with JUSDA
  • pickupRemarks: (optional) Free text remarks related to pickup. Used for LTL.
  • deliverRemarks: (optional) Free text remarks related to delivery. Used for LTL.
  • goodsDescription: (optional) Max length 100.
  • shipperReferenceNo: (optional) Any shipment reference number to be provided to carrier. For UPS, only valid if the origin-destination pair is not US-US or PR-PR. FedEx does not support.
  • shipperReferenceNo2: (optional) Additional reference number. Only certain carriers support this. UPS and FedEx do not support.
  • labelMethod: (optional) Url (default) or Bytes. Url will return a pointer to the label file. Bytes will embedd the label image in the Json response. Using Bytes could significantly reduce response time
  • items: (required) An array containing one item for each package being shipped
  • description: (optional) item description
  • pieces: (optional) number of pieces for this item
  • weight: (required) Gross weight of package
  • weightUnit: (required) LB or KG
  • length: (required) Length of package
  • width: (required) Width of package
  • height: (required) Height of package
  • dimensionUnit: (required) IN or CM
  • hazardous: (optional) default false
  • declaredValue: (optional) Declared value of the items being shipped
  • declaredValueCurrencyCode: (optional) 3 digit currency code like USD, EUR, or JPY
  • packageIdentifier: (optional) Your internal reference number for the package
  • packageReferenceNo: (optional) For UPS, max length 35. For FedEx, max length 40.
  • packageReferenceNo2: (optional) For UPS, max length 35. FedEx does not support.

Sample Request

                "BookingIdentifier" : "11001",
                "Mode" : "Parcel",
                "CarrierName" : "UPS",
                "ServiceLevel" : "UPS Ground",
                "ShipperName" : "Test Shipper",
                "ShipperAddress1" : "5031 Halison Street",
                "ShipperCity" : "Torrance",
                "ShipperStateProvince" : "CA",
                "ShipperPostalCode" : "90503",
                "ShipperCountry" : "US",
                "ShipToName" : "Test Consignee",
                "ShipToAddress1" : "847 Spring Creek Court",
                "ShipToCity" : "Elk Grove Village",
                "ShipToStateProvince" : "IL",
                "ShipToPostalCode" : "60007",
                "ShipToCountry" : "US",
                "ShipperReferenceNo" : "REF1",
                "ShipperReferenceNo2" : "REF2",
                "Items": [
                        "Weight": 5,
                        "WeightUnit": "LB",
                        "Length": 2,
                        "Width": 7,
                        "Height": 3,
                        "DimensionUnit": "IN",
                        "PackageIdentifier" : "P10001"

Post Bookings Response Payload

The response payload will an array of tracking numbers and labels that have been assigned by the carrier.

  • bookingId: JUSDA assigned identifier for each individual Booking Request.
  • bookingIdentifier: Your reference which was provided in the Booking Request. Can be used to get booking results
  • carrierTrackingNo: Tracking number generated by the carrier
  • labelUri: The location of the label image. Download for printing.

Sample Response

                "bookingId": "0d91881f-84d6-4bc1-bc2f-15fe2ee6aece",
                "bookingIdentifier": "11001",
                    "labels": [
                        "carrierTrackingNo": "1ZE373200397508234",
                        "labelUri": ""

API Documentation

For more details about the Bookings API endpoint, see JUSDA's API Documentation.