Create a Shipment

Create a FTL shipment by using an API endpoint to add the shipment to project44's network and send tracking information about the shipment.

Create a FTL Shipment

Create a FTL shipment to be tracked in project44's network. This step is necessary before tracking of a Truckload shipment can start.

Requirements

Have the following information:

Carrier Identifier (SCAC, MC_NUMBER, DOT_NUMBER, SYSTEM, or P44_EU)
Shipment Identifier (BILL_OF_LADING or ORDER)
At least two shipment stops with stop information including
- Stop number
- Appointment windows (start and end dates and times)
- Location (using either an address or geocoordinates)
Equipment Identifier (MOBILE_PHONE, VEHICLE_ID, LICENSE_PLATE, SENSITECH_DEVICE, or TIVE_DEVICE_ID)

note

Depending on the carrier connection type, an equipment ID might not be required. This is an infrequent occurrence, so we recommend always sending an equipment ID. If any vehicle IDs are in question, use the following endpoints to validate equipment identifiers or return a list of assets for a given carrier.

Get a List of Assets for a Given Carrier - ADD LINK
Validate Equipment Identifiers - ADD LINK :::

Workflow

Complete these steps:

Prepare a POST request to [ADD ENDPOINT].
Add the required information to the request schema. For an example that uses addresses for the stop locations,

Copy

Copied

{
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "shipmentStops": [
    {
      "stopNumber": 0,
      "appointmentWindow": {
        "startDateTime": "2019-08-24T14:15:22",
        "endDateTime": "2019-08-24T14:15:22",
        "localTimeZoneIdentifier": "string"
      },
      "location": {
        "address": {
          "postalCode": "string",
          "addressLines": [
            "string"
          ],
          "city": "string",
          "state": "string",
          "country": "US"
        }
      }
    }
  ],
  "equipmentIdentifiers": [
    {
      "type": "MOBILE_PHONE_NUMBER",
      "value": "string",
      "shouldDelete": false
    }
  ]
}

[Make this into a sample.]

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation. :::

Send the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the minimum response schema:

Copy

Copied

{
  "shipment": {
    "carrierIdentifier": {
      "type": "SCAC",
      "value": "string"
    },
    "shipmentIdentifiers": [
      {
        "type": "BILL_OF_LADING",
        "value": "string"
      }
    ],
    "shipmentStops": [
      {
        "stopNumber": 0,
        "appointmentWindow": {
          "startDateTime": "2019-08-24T14:15:22",
          "endDateTime": "2019-08-24T14:15:22",
          "localTimeZoneIdentifier": "string"
        },
        "location": {
          "address": {
            "postalCode": "string",
            "addressLines": [
              "string"
            ],
            "city": "string",
            "state": "string",
            "country": "US"
          }
        }
      }
    ],
    "equipmentIdentifiers": [
      {
        "type": "MOBILE_PHONE_NUMBER",
        "value": "string",
        "shouldDelete": false
      }
    ],
    "id": 0
  },
  "infoMessages": [
    {
      "severity": "ERROR",
      "message": "string",
      "diagnostic": "string",
      "source": "SYSTEM"
    }
  ]
}

note

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.

A unique project44 ID is returned in the response after shipment creation. Store this ID to use in future API calls.

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 of the API Request to create a shipment for tracking and the fields returned with the API Response 200 OK.

Field	Description
`carrierIdentifier`	This array contains your carrier identifier information.
`carrierIdentifier.type`	The carrier identifier type. Valid values include `SCAC`, `MC_NUMBER`, `DOT_NUMBER`, `SYSTEM`, or `P44_EU`.
`carrierIdentifier.value`	The value of the carrier identifier.
`shipmentIdentifiers`	The shipment identifiers that are unique to this shipment and carrier identifier. These may be used in subsequent API calls along with the carrier identifier to reference a shipment. They may also be used by project44 to track the shipment. Only one shipment identifier of each time may be provided.
`shipmentIdentifiers.type`	The type of the shipment identifier. Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The value of the shipment identifier.
`shipmentStops`	An array that includes information for each stop.
`shipmentStops.stopNumber`	The user-defined stop number, where `1` is for the origin and the largest number is for the destination with any stops in between ordered by appointment time.
`shipmentStops.appointmentWindow`	The shipment's expected window of arrival at the defined stop.
`shipmentStops.appointmentWindow.startDateTime`	The appointment window start date and time for the stop.
`shipmentStops.appointmentWindow.endDateTime`	The appointment window end date and time for the stop.
`shipmentStops.location`	The user-defined location of the stop. Use if no geocoordinates are provided.
`shipmentStops.location.address`	The address of the stop.
`shipmentStops.location.address.postalCode`	The postal code for the stop.
`shipmentStops.location.address.addressLines`	The street address for the stop.
`shipmentStops.location.address.city`	The stop's city.
`shipmentStops.location.address.state`	The stop's state. Only relevant for USA, Mexico, and Canada.
`shipmentStops.location.address.country`	The stop's country.
`shipmentStops.geocoordinates`	The latitude and longitude of the stop. This field may not be provided when creating a shipment but will always be returned. Use if no address is provided.
`equipmentIdentifiers`	An array of the identifiers for the truckload equipment being tracked. These do not need to be unique to the shipment.
`equipmentIdentifiers.type`	The type of equipment identifier. Valid values include `MOBILE_PHONE`, `VEHICLE_ID`, `LICENSE_PLATE`, `SENSITECH_DEVICE`, or `TIVE_DEVICE_ID`.
`equipmentIdentifiers.value`	The value of the equipment identifier.

Get List of Assets for a Given Carrier

Get all assets for a carrier that are known by project44. Use this endpoint if you do not know the carrier's equipment identifiers - this information is necessary to create a shipment.

Requirements

Have the following information:

Carrier Identifier (SCAC, MC_NUMBER, DOT_NUMBER, SYSTEM, or P44_EU).

Workflow

Complete the following steps:

Prepare a GET request to [ADD ENDPOINT] and include the carrier identifier.
Send the request.

Expected System Response

The request is successfully submitted and confirmed when a 200 OK response is received. For example,

Copy

Copied

{
  "paginationInfo": {
    "total": 0,
    "pageSize": 0,
    "pageNumber": 0
  },
  "results": [
    {
      "type": "MOBILE_PHONE_NUMBER",
      "value": "string",
      "shouldDelete": false
    }
  ],
  "infoMessages": [
    {
      "severity": "ERROR",
      "message": "string",
      "diagnostic": "string",
      "source": "SYSTEM"
    }
  ]
}

Errors

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

Fields & Objects

The table below describes only the minimum relevant fields necessary for the sending a status event and position update for a truckload shipment. These are also the same fields returned in the API Response 200 OK.

Field	Description
`capacityProviderIdentifierValue`	The value of the carrier identifier.
`capacityProviderIdentifierType`	The carrier identifier type. Valid values include `SCAC`, `MC_NUMBER`, `DOT_NUMBER`, `SYSTEM`, or `P44_EU`.
`paginationInfo`	An object that includes pagination information about a collection of resources.
`results`	An array that lists the resources contained on this page.
`results.type`	The type of equipment identifier. Valid values include `MOBILE_PHONE`, `VEHICLE_ID`, `LICENSE_PLATE`, `SENSITECH_DEVICE`, or `TIVE_DEVICE_ID`.
`results.value`	The value of the equipment identifier. Cell phone numbers will be obfuscated in project44 responses for privacy reasons.

Validate Equipment Identifiers

Validate equipment identifiers for a carrier.

note

If the carrier's tracking vendor does not support validating equipment identifiers without initiating tracking, then the endpoint will always report that the identifier is valid.

Requirements

Have the following information:

Carrier Identifier (SCAC, MC_NUMBER, DOT_NUMBER, SYSTEM, or P44_EU).
Equipment Identifier (MOBILE_PHONE, VEHICLE_ID, LICENSE_PLATE, SENSITECH_DEVICE, or TIVE_DEVICE_ID)

Workflow

Complete the following steps:

Prepare a GET request to [ADD ENDPOINT] and include the carrier and equipment identifiers.
Send the request.

Expected System Response

The request is successfully submitted and confirmed when a 200 OK response is received. For example,

Copy

Copied

{
  "valid": true
}

Errors

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

Fields & Objects

Field	Description
`capacityProviderIdentifierValue`	The value of the carrier identifier.
`capacityProviderIdentifierType`	The carrier identifier type. Valid values include `SCAC`, `MC_NUMBER`, `DOT_NUMBER`, `SYSTEM`, or `P44_EU`.
`equipmentIdentifiers.type`	The type of equipment identifier. Valid values include `MOBILE_PHONE`, `VEHICLE_ID`, `LICENSE_PLATE`, `SENSITECH_DEVICE`, or `TIVE_DEVICE_ID`.
`equipmentIdentifiers.value`	The value of the equipment identifier.
`valid`	Boolean field indicating if the equipment identifier is valid (`true`) or invalid (`false`).

Create a Shipment

Create a FTL Shipment

Requirements

note

Workflow

Expected System Response

note

Errors

Fields and Objects

Get List of Assets for a Given Carrier

Requirements

Workflow

Expected System Response

Errors

Fields & Objects

Validate Equipment Identifiers

note

Requirements

Workflow

Expected System Response

Errors

Fields & Objects

Was this page helpful?