Introduction

Create a Less Than Truckload (LTL) shipment to be tracked in project44's network. The shipment must be created by you or the customer before you can send tracking updates.

As you get started, here are some best practices to keep in mind:

Each API Request must be preceded by this line: Authorization: Bearer access_token
Build for future customers by not hard-coding the Customer ID.
Keep your client application continually authorized by having your client application’s receipt of the 401 Invalid or missing credentials HTTP status code in the API Response generate a request for a new access token using its client credentials.

Once you reach out to project44 to start the implementation, there is a configuration task that must be performed on the project44 side that takes at least two weeks to complete. You will not be able to test the functionality of the API until this is process is complete.

Create a LTL Shipment

Create a LTL shipment to be tracked when a customer has not or is unable to create the shipment.

Requirements

Have the following information:

Customer Account ID
Carrier ID: SCAC
Shipment ID: PRO, BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, PURCHASE_ORDER, or EXTERNAL. If there is more than one shipment ID with the same type, include the primaryForType field.
Shipment stop information including the stop type, stop number, address, contact, and appointment window.

Workflow

Prepare a PUT request to /api/v4/capacityproviders/ltl/shipments. Include all required information list above. For example:

JSON

{ 
  "customerAccount": {
    "accountIdentifier": "Customer 1"
  },
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "PRO",
      "value": "123-45678C",
      "primaryForType": true
    },
    {
      "type": "BILL_OF_LADING",
      "value": "1234567890",
      "primaryForType": true
    }
  ],
  "shipmentStops": [
    {
      "stopType": "ORIGIN",
      "stopNumber": 1,
      "location": {
        "address": {
          "postalCode": "60654",
          "addressLines": [
            "222 W Merchandise Mart Plaza"
          ],
          "city": "Chicago",
          "state": "IL",
          "country": "US"
        },
        "contact": {
          "companyName": "project44 Chicago"
        }
      },
      "appointmentWindow": {
        "startDateTime": "2021-09-01T08:00:00",
        "endDateTime": "2021-09-01T22:00:00",
        "localTimeZoneIdentifier": "America/Chicago"
      }
     },
    {
      "stopType": "DESTINATION",
      "stopNumber": 2,
      "location": {
        "address": {
          "postalCode": "78756",
          "addressLines": [
            "3800 N Lamar Blvd"
          ],
          "city": "Austin",
          "state": "TX",
          "country": "US"
        },
        "contact": {
          "companyName": "project44 Austin"
        }
      },
      "appointmentWindow": {
        "startDateTime": "2021-09-10T08:00:00",
        "endDateTime": "2021-09-10T11:00:00",
        "localTimeZoneIdentifier": "America/Austin"
      }
    }
  ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.” below the JSON sample.

Send the request.

Expected System

The request is successfully submitted and confirmed when a 202 Accepted response is received. Errors

If there was a problem with your request, you will receive one of the following error codes:

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Fields and Objects

The table below describes only the minimum relevant fields necessary for creating a LTL shipment. These are also the same fields returned in the API Response 202 Accepted.

Field	Description
`customerAccount`	An object of the account information for the customer of the shipment.
`customerAccount.accountIdentifier`	The account identifier for the customer of the shipment. This is used to identify the customer in project44's system.
`carrierIdentifier`	An object that includes your capacity provider identifier information.
`carrierIdentifier.type`	The type of your capacity identifier. `SCAC` is the only type accepted in this API.
`carrierIdentifier.value`	The value of your identifier.
`shipmentIdentifiers`	This array includes the list if shipment IDs that are used to track the shipment.
`shipmentIdentifiers.type`	The type of the shipment ID. At least one identifier in this array must be a PRO Number (`shipmentIdentifiers.type` = `PRO`). Other valid values include: `BILL_OF_LADING`, `CUSTOMER_REFERENCE`, `PICKUP`, `PURCHASE_ORDER`, or `EXTERNAL`.
`shipmentIdentifiers.value`	The value of the shipment ID.
`shipmentIdentifiers.primaryForType`	This field indicates if the shipment ID is the primary shipment ID for that type. The primary shipment ID will always be attempted before other identifiers of the same type.
`shipmentStops`	This array includes the shipment stop information.
`shipmentStops.stopType`	The type of stop. User-defined stops will always have the customer locations `ORIGIN` and `DESTINATION`. `TERMINAL` stops types are capacity provider redistribution centers and will be inserted dynamically as you return them. The `TERMINAL` stop types will be ignored during shipment creation.
`shipmentStops.stopNumber`	The stop number, where the `ORIGIN` is `1` and the `DESTINATION` has the largest number. Any stops in between are numbered in order of appointment time. You can leave this field empty during shipment creation. The `DESTINATION` stop number will change dynamically as terminals are discovered along the shipment route from `ORIGIN` to `DESTINATION`. The `stopType` is the most useful field for easily and reliably identifying the `ORIGIN` and `DESTINATION`.
`shipmentStops.location`	This array contains data about the stop's location, including address and contact information. Full address and contact information should be included during shipment creation. Terminals may or may not have complete address and contact information.
`shipmentStops.location.address`	This array contains the stop's address information.
`shipmentStops.location.address.postalCode`	The ZIP or postal code of the stop location.
`shipmentStops.location.address.addressLines`	An array of strings with address information that includes the street name, number, direction, PO Box, etc. for the stop location. NOTE: Currently, only three address lines are permitted.
`shipmentStops.location.address.city`	The name of the city or town of the stop location.
`shipmentStops.location.address.state`	The abbreviation of the state, province, district, etc. of the stop location. This is only applicable to locations in North America. For locations outside of North America, leave this blank.
`shipmentStops.location.address.country`	The abbreviation of the country (using ISO 3166 standards) of the stop location. The default is `US`.
`shipmentStops.location.contact`	This array contains the contact information for the stop.
`shipmentsStops.location.contact.companyName`	The company name of the contact at the stop.
`shipmentStops.appointmentWindow`	An array with information about the shipment's expected window of arrival at this stop. This information may be used to report whether a shipment is on time to a stop. It may also be used to match and look up shipments with the capacity provider (for example, by comparing pickup dates). Note that the start and end times are required for `appointmentWindow`; the default start time does not apply to this field. On responses, the time zone identifier (for example, `America/Chicago`) for this date time window is determined by project44 when possible based on the stop's address.
`shipmentStops.appointmentWindow.startDateTime`	Start date and time of the stop window in the applicable time zone, formatted `yyyy-MM-dd'T'HH:mm:ss`. The default is the current date.
`shipmentStops.appointmentWindow.endDateTime`	End date and time of the stop window in the applicable time zone, formatted `yyyy-MM-dd'T'HH:mm:ss`.
`shipmentStops.appointmentWindow.localTimeZoneIdentifier`	The time zone identifier for the appointment window. For example: `America/Chicago` or `Europe/Berlin`