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": 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
    }
  ]
}

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": 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"
        }
    ]
}

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.