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.

Authentication

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.

Testing

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:

https://services.jusdausa.com/api/v1/Rates?environment=Test

API Endpoint

The URL for JUSDA Rate APIs is:

https://services.jusdausa.com/api/v1/Bookings

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": "https://jusda.blob.core.windows.net/upslabel/1ZE373200397508234.jpg?st=2021-01-15T20%3A32%3A41Z&se=2022-01-15T20%3A33%3A41Z&sp=r&spr=https&sv=2019-02-02&sr=b&sig=BzNUyPp8k9ibwRlOQhndlTx6DJ8UJ24tBRFm3QSG6wk%3D"
                    }
                ]
            }

API Documentation

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