Introduction

Send tracking updates about a Truckload shipment:

A shipment must be created and added to project44's network before you can send tracking data.

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.
Sending status events as well as position updates is preferred. Sending only position updates is preferred to sending only status events.
Sending an ETA without either a position update or a status event is not possible.
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.

Send a Status Event with a Position Update

Requirements

Have the following information:

Shipment ID: BILL_OF_LADING or ORDER
Position Latitude & Longitude
UTC Timestamp
Customer ID
Event Stop Number
Event Type. See Truckload Event Types for the descriptions of truckload events.
[OPTIONAL] Carrier ID. This field is recommended if you are new to project44's carrier network.

Workflow

Complete these steps:

Call the POST /api/v4/capacityproviders/tl/shipments/statusUpdates endpoint.
Enter the required shipment update information in the request schema. For example,

JSON

{
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "latitude": 49.780089,
  "longitude": 18.099213,
  "utcTimestamp": "2022-08-10T22:12:49",
  "customerId": "string",
  "eventStopNumber": 2,
  "eventType": "ARRIVED"
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  }
}

This an example of a potential request. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Submit the request.

Expected Response

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

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

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 & 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 202 Accepted.

Field	Description	Notes
`shipmentIdentifiers`	An array that includes the identifiers for the shipments.
`shipmentIdentifiers.type`	The type of the shipment identifier.	Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The shipment identifier value agreed upon by you and our mutual customer.
`latitude`	Your vehicle’s current latitude in decimal degrees.
`longitude`	Your vehicle's current longitude in decimal degrees.
`utcTimestamp`	The UTC time of the shipment's creation.	Formatted `yyyy-mm-ddTHH:mm:ss`. Local time must be converted to UTC.
`customerId`	The Customer ID provided by your project44 representative.
`eventStopNumber`	The stop number for the event.
`eventType`	Send any status events in this field. See Truckload Event Types for valid values and descriptions of each event type.
`carrierIdentifier`	The identifier object for the carrier.
`carrierIdentifier.type`	The carrier ID type.	Valid values are `SCAC`, `DOT_NUMBER`, `MC_NUMBER`, `P44_EU`, `SYSTEM`, and `P44_GLOBAL`.
`carrierIdentifier.value`	The carrier ID value.

Send Just a Position Update

Requirements

Have the following information:

Shipment ID: BILL_OF_LADING or ORDER
Position Latitude & Longitude
UTC Timestamp
Customer ID
[OPTIONAL] Event Type = POSITION
[OPTIONAL] Carrier ID. This field is recommended if you are new to project44's carrier network.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/capacityproviders/tl/shipments/statusUpdates.
Enter the required shipment update information in the request schema. For example,

JSON

{
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "latitude": 49.780089,
  "longitude": 18.099213,
  "utcTimestamp": "2021-08-04T12:07:34",
  "customerId": "string",
  "eventType": "POSITION"
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  }
}

This an example of a potential request. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Send the request.

Expected Response

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

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

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 & Objects

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

Field	Description	Notes
`shipmentIdentifiers`	An array that includes the identifiers for the shipments.
`shipmentIdentifiers.type`	The type of the shipment identifier. Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The shipment identifier value agreed upon by you and our mutual customer.
`latitude`	Your vehicle’s current latitude in decimal degrees.
`longitude`	Your vehicle's current longitude in decimal degrees.
`utcTimestamp`	The UTC time of the shipment's creation formatted `yyyy-mm-ddTHH:mm:ss`. Local time must be converted to UTC.
`customerId`	The Customer ID provided by your project44 representative.
`eventType`	Send any status events in this field. See Truckload Event Types for valid values and descriptions of each event type.
`carrierIdentifier`	The identifier object for the carrier.
`carrierIdentifier.type`	The carrier ID type.	Valid values are `SCAC`, `DOT_NUMBER`, `MC_NUMBER`, `P44_EU`, `SYSTEM`, and `P44_GLOBAL`.
`carrierIdentifier.value`	The carrier ID value.

Send Just a Status Event

Requirements

Have the following information:

Shipment ID: BILL_OF_LADING or ORDER
Position Latitude & Longitude (send 0,0 only if you do not have the exact coordinates)
UTC Timestamp
Customer ID
Event Stop Number
Event Type. See Truckload Event Types for the descriptions of truckload events.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/capacityproviders/tl/shipments/statusUpdates.
Enter the required shipment update information in the request schema. For example,

JSON

{
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "latitude": 0,
  "longitude": 0,
  "utcTimestamp": "2022-08-12T15:56:52",
  "customerId": "string",
  "eventStopNumber": 2,
  "eventType": "DELIVERED"
}

This an example of a potential request. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Send the request.

Expected Response

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 & Objects

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

Field	Description
`shipmentIdentifiers`	An array that includes the identifiers for the shipments.
`shipmentIdentifiers.type`	The type of the shipment identifier. Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The shipment identifier value agreed upon by you and our mutual customer.
`latitude`	Your vehicle’s current latitude in decimal degrees.
`longitude`	Your vehicle's current longitude in decimal degrees.
`utcTimestamp`	The UTC time of the shipment's creation formatted `yyyy-mm-ddTHH:mm:ss`. Local time must be converted to UTC.
`customerId`	The Customer ID provided by your project44 representative.
`eventStopNumber`	The stop number for the event.
`eventType`	Send any status events in this field. See Truckload Event Types for valid values and descriptions of each event type.

Send Just a Reefer Temperature

Requirements

Have the following information:

Shipment ID: BILL_OF_LADING or ORDER
Position Latitude & Longitude (send 0,0 only if you do not have the exact coordinates)
UTC Timestamp
Customer ID
Latest Temperature & Temperature Unit

Workflow

Complete these steps:

Prepare a POST request to /api/v4/capacityproviders/tl/shipments/statusUpdates.
Enter the required shipment update information in the request schema. For example,

JSON

{
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "latitude": 0,
  "longitude": 0,
  "utcTimestamp": "2022-08-12T15:56:52",
  "customerId": "string",
  "latestTemperature": 34,
  "latestTemperatureUnit": "F"
}

This an example of a potential request. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Send the request.

Expected Response

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

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

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 & Objects

The table below describes only the minimum relevant fields necessary for the sending a reefer temperature update for a truckload shipment. These are also the same fields returned in the API Response 202 Accepted.

Field	Description
`shipmentIdentifiers`	An array that includes the identifiers for the shipments.
`shipmentIdentifiers.type`	The type of the shipment identifier. Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The shipment identifier value agreed upon by you and our mutual customer.
`latitude`	Your vehicle’s current latitude in decimal degrees.
`longitude`	Your vehicle's current longitude in decimal degrees.
`utcTimestamp`	The UTC time of the shipment's creation formatted `yyyy-mm-ddTHH:mm:ss`. Local time must be converted to UTC.
`customerId`	The Customer ID provided by your project44 representative.
`latestTemperature`	The numeric value of the latest temperature reading.
`latestTemperatureUnit`	The temperature unit for the latest temperature reading. Valid values are `F` or `C`.

Send a Status Event, an ETA, and a Reefer Temperature with a Position Update

Requirements

Have the following information:

Shipment ID: BILL_OF_LADING or ORDER
Position Latitude & Longitude
UTC Timestamp
Carrier Supplied ETA
Latest Temperature Reading
Customer ID
Event Type. See Truckload Event Types for the descriptions of truckload events.
Event Stop Number

Workflow

Complete these steps:

Prepare a POST request to /api/v4/capacityproviders/tl/shipments/statusUpdates.
Enter the required shipment update information in the request schema. For example,

JSON

{
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "latitude": 47.3472874,
  "longitude": -81.3476,
  "utcTimestamp": "2022-12-30T20:43:34",
  "shipmentStops": [
    {
      "carrierSuppliedEta": "2023-01-05T10:30:00+0000"
    }
  ],
  "latestTemperature": 34,
  "latestTemperatureUnit": "F",
  "customerId": "string",
  "eventType": "DEPARTED",
  "eventStopNumber": 2
}

This an example of a potential request. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Send the request.

Expected Response

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

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

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 & Objects

Field	Description
`shipmentIdentifiers`	An array that includes the identifiers for the shipments.
`shipmentIdentifiers.type`	The type of the shipment identifier. Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The shipment identifier value agreed upon by you and our mutual customer.
`latitude`	Your vehicle’s current latitude in decimal degrees.
`longitude`	Your vehicle's current longitude in decimal degrees.
`utcTimestamp`	The UTC time of the shipment's creation formatted `yyyy-mm-ddTHH:mm:ss`. Local time must be converted to UTC.
`carrierSuppliedEta`	Your ETA for the stop formatted `yyyy-mm-ddTHH:mm:ss`. Local time must be converted to UTC.
`customerId`	The Customer ID provided by your project44 representative.
`latestTemperature`	The numeric value of the latest temperature reading.
`latestTemperatureUnit`	The temperature unit for the latest temperature reading. Valid values are `F` or `C`.
`eventType`	Send any status events in this field. See Truckload Event Types for valid values and descriptions of each event type.
`eventStopNumber`	The stop number for the event.

Introduction

Send a Status Event with a Position Update

Requirements

Workflow

Expected Response

Errors

Fields & Objects

Send Just a Position Update

Requirements

Workflow

Expected Response

Errors

Fields & Objects

Send Just a Status Event

Requirements

Workflow

Expected Response

Errors

Fields & Objects

Send Just a Reefer Temperature

Requirements

Workflow

Expected Response

Errors

Fields & Objects

Send a Status Event, an ETA, and a Reefer Temperature with a Position Update

Requirements

Workflow

Expected Response

Errors

Fields & Objects

Was this helpful?