Appendix

Request Envelope

Every request body is a JSON object with the Full Truckload data under the truckload key.

FTL Mode Body (truckload)

Objects

Field references for the nested objects under truckload. Timestamps are ISO 8601 date-times (for example 2026-06-01T08:30:00Z) and must not be more than 5 minutes in the future.

shipmentEvent

readings

readings.position

readings.sensor

readings.sensor.reefer

readings.sensor.fuel

readings.sensor.zones[]

Each temperature zone. All temperatures in a zone share the zone's temperatureUnit.

readings.sensor.ambientTemperature

readings.sensor.tirePressure[]

readings.sensor.shock

readings.sensor.vibration

stops[]

Each entry updates one stop that already exists on the shipment. project44 never creates, removes or reorders stops from this array. Identify the stop with stopNumber or stopReferenceId, and always send at least one value to set. An entry that identifies a stop but carries neither carrierEstimatedArrivalDateTime nor carrierAppointmentWindow is accepted and simply has no effect, so it will not tell you that something is missing.

stops[].carrierAppointmentWindow

Identifier Reference

The identifiers object uses named keys, not a polymorphic typed array. At least one of billOfLadingNumber or orderNumber is required; each value is a string with a maximum length of 256 characters.

Pushing for Another Carrier

Normally you push tracking data for your own shipments, and no carrier identifier is needed: project44 uses the credentials on the request to work out which carrier the data is about.

A carrier identifier is only needed when those two are different — for example when a telematics provider or fleet aggregator pushes for the carriers whose fleets it manages. Two roles are involved:

• Reporting carrier — the party that holds the API credentials and makes the request.
• Subject carrier — the carrier the data is about, that is, the carrier on the shipment. The subject carrier does nothing at request time.

When the reporting carrier and the subject carrier are different, name the subject carrier in the identifiers object using whichever of scac, dotNumber, or mcNumber that carrier has. A carrier without a SCAC, for example, is identified by dotNumber or mcNumber. All values are strings.

{
  "truckload": {
    "identifiers": {
      "billOfLadingNumber": "BOL-20260601-001",
      "scac": "XPPP"
    }
  }
}

Stop Coupling

Stop-coupled events reference a stop through the shipmentEvent object (not identifiers), using any of stopReferenceId, stopId, or stopNumber. All three are optional. When more than one is present, they are resolved in the priority order stopReferenceId > stopId > stopNumber.

Entries in stops[] identify their stop independently of shipmentEvent, using stopReferenceId, stopNumber or stopType, resolved in that order. A stop update that matches no stop on the shipment is discarded.

FTL Event Types

The endpoint accepts project44's standard shipment event types plus the truckload terminal events ARRIVED_AT_TERMINAL and DEPARTED_TERMINAL. The complete list is in the reference documentation. Other values are accepted and stored but do not change the shipment's status; only the events below produce a status milestone:

Migrating from the Truckload Status-Update Endpoint

If you already send Truckload tracking data to /api/v4/capacityproviders/tl/shipments/statusUpdates (see Send Tracking Updates), the table below maps what you send today to its Universal PUSH equivalent. For complete payloads, see Send Tracking Updates.

Payload Limits

Error Response Codes

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

No 5xx status is surfaced externally.

Error Response Body

Validation errors return the standard project44 ApiError envelope. errors[] may carry more than one entry (for example, an empty identifiers object returns three). errorMessage and source are returned null; supportReferenceId is a reference id to quote when contacting project44 support.

{
  "httpStatusCode": 400,
  "httpMessage": "Bad Request",
  "errorMessage": null,
  "errors": [
    {
      "severity": "ERROR",
      "message": "$.truckload.readings.position: required property 'latitude' not found",
      "diagnostic": "MISSING_REQUIRED_FIELD at $.truckload.readings.position",
      "source": null
    }
  ],
  "supportReferenceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}