Create a Shipment

Create a Full Truckload (FTL) shipment to add the shipment to project44's system.

Create an FTL Shipment

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

Requirements

Have the following information:

Carrier Identifier (SCAC, MC_NUMBER, DOT_NUMBER, SYSTEM, VAT, 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_NUMBER, VEHICLE_ID, LICENSE_PLATE, SENSITECH_DEVICE, or TIVE_DEVICE_ID)

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.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/tl/shipments.
Add the required information to the request schema. For an example that uses addresses for the stop locations,

{
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "shipmentStops": [
    {
      "stopNumber": 1,
      "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"
        }
      }
    },
    {
      "stopNumber": 2,
      "appointmentWindow": {
        "startDateTime": "2019-08-26T14:15:22",
        "endDateTime": "2019-08-26T14: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
    }
  ]
}

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.

Fields and Objects

Element	Description	Type	Notes
`carrierIdentifier.type`	The carrier identifier type.	`string`	Valid values are `SCAC`, `MC_NUMBER`, `DOT_NUMBER`, `SYSTEM`, `VAT`, or `P44_EU`.
`carrierIdentifier.value`	The value of the carrier identifier.	`string`
`shipmentIdentifiers.type`	The type of the shipment identifier.	`string`	Valid values are `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The value of the shipment identifier.	`string`
`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.	`integer`
`shipmentStops.appointmentWindow.startDateTime`	The appointment window start date and time for the stop.	`string`
`shipmentStops.appointmentWindow.endDateTime`	The appointment window end date and time for the stop.	`string`
`shipmentStops.appointmentWindow.localTimeZoneIdentifier`	The timezone of the appointment window for the stop.	`string`	For example, 'America/Chicago'.
`shipmentStops.location.address.postalCode`	The postal code for the stop.	`string`
`shipmentStops.location.address.addressLines`	The street address for the stop.	`string`
`shipmentStops.location.address.city`	The stop's city.	`string`
`shipmentStops.location.address.state`	The stop's state.	`string`	This field is only relevant for USA, Mexico, and Canada.
`shipmentStops.location.address.country`	The stop's country.	`string <enum>`
`shipmentStops.geocoordinate.latitude`	The latitude of the stop.	`number <float>`	This field may not be provided when creating a shipment but will always be returned. Use if no address is provided.
`shipmentStops.geocoordinate.longitude`	The longitude of the stop.	`number <float>`	This field may not be provided when creating a shipment but will always be returned. Use if no address is provided.
`equipmentIdentifiers.type`	The type of equipment identifier.	`string`	This does not need to be unique to the shipment. Valid values include `MOBILE_PHONE_NUMBER`, `VEHICLE_ID`, `LICENSE_PLATE`, `SENSITECH_DEVICE`, or `TIVE_DEVICE_ID`.
`equipmentIdentifiers.value`	The value of the equipment identifier.	`string`	This does not need to be unique to the shipment.

Expected System Response

You have successfully submitted the request when you receive a 201 Created response. For example,

{
    "shipment": {
        "id": 0,
        "carrierIdentifier": {
            "type": "SCAC",
            "value": "string"
        },
        "shipmentIdentifiers": [
            {
                "type": "BILL_OF_LADING",
                "value": "string"
            }
        ],
        "shipmentStops": [
            {
                "stopNumber": 1,
                "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"
                    }
                }
            },
          {
            "stopNumber": 2,
            "appointmentWindow": {
              "startDateTime": "2019-08-26T14:15:22",
              "endDateTime": "2019-08-26T14: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"
        }
    ]
}

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.

Fields and Objects

Element	Description	Type	Notes
`shipment.id`	The unique project44 ID is returned in the response after shipment creation.	`integer <int64>`	Store this ID to use in future API calls.
`shipment.carrierIdentifier.type`	The carrier identifier type.	`string`	Valid values are `SCAC`, `MC_NUMBER`, `DOT_NUMBER`, `SYSTEM`, `VAT`, or `P44_EU`.
`shipment.carrierIdentifier.value`	The value of the carrier identifier.	`string`
`shipment.shipmentIdentifiers.type`	The type of the shipment identifier.	`string`	Valid values are `ORDER` or `BILL_OF_LADING`.
`shipment.shipmentIdentifiers.value`	The value of the shipment identifier.	`string`
`shipment.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.	`integer`
`shipment.shipmentStops.appointmentWindow.startDateTime`	The appointment window start date and time for the stop.	`string`
`shipment.shipmentStops.appointmentWindow.endDateTime`	The appointment window end date and time for the stop.	`string`
`shipment.shipmentStops.appointmentWindow.localTimeZoneIdentifier`	The timezone of the appointment window for the stop.	`string`	For example, 'America/Chicago'.
`shipment.shipmentStops.location.address.postalCode`	The postal code for the stop.	`string`
`shipment.shipmentStops.location.address.addressLines`	The street address for the stop.	`string`
`shipment.shipmentStops.location.address.city`	The stop's city.	`string`
`shipment.shipmentStops.location.address.state`	The stop's state.	`string`	This field is only relevant for USA, Mexico, and Canada.
`shipment.shipmentStops.location.address.country`	The stop's country.	`string <enum>`
`shipment.equipmentIdentifiers.type`	The type of equipment identifier.	`string`	This does not need to be unique to the shipment. Valid values include `MOBILE_PHONE_NUMBER`, `VEHICLE_ID`, `LICENSE_PLATE`, `SENSITECH_DEVICE`, or `TIVE_DEVICE_ID`.
`shipment.equipmentIdentifiers.value`	The value of the equipment identifier.	`string`	This does not need to be unique to the shipment.

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.

Create FTL Shipment with relaxed appointment windows

This is a beta feature and is currently available for a limited set of customers.

Create FTL shipment to be tracked by project44's network without providing appointment windows at the time of shipment creation.

Requirements

Have the following information:

Carrier Identifier (SCAC, MC_NUMBER, DOT_NUMBER, SYSTEM, VAT, 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)~~ (not required)
- Location (using either an address or geocoordinates)
Equipment Identifier (MOBILE_PHONE_NUMBER, VEHICLE_ID, LICENSE_PLATE, SENSITECH_DEVICE, or TIVE_DEVICE_ID)

Workflow

Contact your Project44 representative to enable shipment creation without any appointment window. This feature is disabled by default.
Prepare a POST request to /api/v4/tl/shipments.

For the full request schema and descriptions for all fields and objects, please see our reference documentation.

POST request is only valid if
- No appointmentWindow is provided at any stop, or
- At least appointmentWindow is provided for the origin stop (stops[0].appointmentWindow)
- If you provide an appointmentWindow for any stop, it MUST include both startDateTime and endDateTime.
Shipments are created successfully in the Project44 system but remain untracked until an appointment window is provided for the origin stop. If no origin appointment window is provided within 30 days (configurable) from shipment creation, the shipment is automatically timed out.
For shipments that have only an Origin appointment window, the shipment will automatically time out after 7 days (configurable) if it is not completed.

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:

{
  "shipment": {
    "carrierIdentifier": {
      "type": "SCAC",
      "value": "string"
    },
    "shipmentIdentifiers": [
      {
        "type": "BILL_OF_LADING",
        "value": "string"
      }
    ],
    "shipmentStops": [
      {
        "stopNumber": 1,
        "location": {
          "address": {
            "postalCode": "string",
            "addressLines": [
              "string"
            ],
            "city": "string",
            "state": "string",
            "country": "US"
          }
        }
      },
      {
        "stopNumber": 2,
        "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"
    }
  ]
}

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.

Create a Shipment

Create an FTL Shipment

Requirements

Workflow

Expected System Response

Errors

Create FTL Shipment with relaxed appointment windows

Requirements

Workflow

Expected System Response

Errors

Was this helpful?