Appendix

Request envelope

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

Field	Type	Required	Description
`customerAccountNumber`	string	No	The project44 tenant ID of the customer the data is for. Maximum 128 characters.
`truckload`	object	Yes	The Full Truckload (FTL) body.

customerAccountNumber is the customer's project44 tenant ID — obtain it from the customer or your project44 integration representative.

FTL mode body (`truckload`)

Field	Type	Required	Description
`identifiers`	object	Yes	Shipment-resolving identifiers. See Identifier reference.
`shipmentEvent`	object	Conditional	A single tracking event. Requires `type` and `dateTime`. At least one of `shipmentEvent` or `readings` must be present.
`readings`	object	Conditional	Position and/or sensor readings, with its own `dateTime`. At least one of `shipmentEvent` or `readings` must be present.
`assetType`	string	No	Type of tracked unit: `TRUCK`, `TRAILER`, or `OTHER`. Defaults to `TRAILER`.
`extensions`	object	No	Reserved for carrier-specific extension fields.

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`

Field	Type	Required	Description
`type`	string	Yes	The event type. See FTL event types.
`dateTime`	string	Yes	ISO 8601 date-time of the event (for example `2026-06-01T08:30:00Z`).
`stopNumber`	integer	No	1-based stop sequence the event applies to.
`stopReferenceId`	string	No	Carrier's reference id for the stop.
`stopId`	string	No	project44 stop id, if known.
`description`	string	No	Free-text note. Maximum 1024 characters.
`source`	string	No	`UNKNOWN`, `CARRIER`, or `CONTRACT`.
`exceptionCode`	string	No	Carrier exception code, if any.

`readings`

Field	Type	Required	Description
`dateTime`	string	Yes	ISO 8601 date-time of the readings (for example `2026-06-01T08:30:00Z`).
`position`	object	Conditional	GPS position. At least one of `position` or `sensor` is required.
`sensor`	object	Conditional	Telematics/sensor readings. At least one of `position` or `sensor` is required.

`readings.position`

Field	Type	Required	Description
`latitude`	number	Yes	Decimal degrees, -90 to 90.
`longitude`	number	Yes	Decimal degrees, -180 to 180.
`altitude`	number	No	Meters.
`speed`	number	No	Speed, expressed in `speedUnit`.
`heading`	number	No	Degrees, 0–359.
`speedUnit`	string	No	`KILOMETERS_PER_HOUR` or `MILES_PER_HOUR`.

`readings.sensor`

Field	Type	Description
`ignitionStatus`	string	`ON`, `OFF`, or `UNKNOWN`.
`reefer`	object	Reefer unit status (see below).
`fuel`	object	Fuel reading (see below).
`ambientTemperature`	object	Ambient temperature with `value` and `unit` (see below).
`zones`	array	Per-zone temperature readings, maximum 5 (see below).
`tirePressure`	array	Tire pressure readings, maximum 22 (see below).
`shock`	object	Shock event reading (see below).
`vibration`	object	Vibration reading (see below).

`readings.sensor.reefer`

Field	Type	Description
`state`	string	`ON`, `OFF`, `UNKNOWN`.
`powerSource`	string	`DIESEL`, `ELECTRIC`, `LIQUEFIED_PETROLEUM_GAS`, `BATTERY`, `UNKNOWN`.
`operatingMode`	string	`CONTINUOUS`, `CYCLE_SENTRY`, `START_STOP`, `UNKNOWN`.
`engineRpm`	integer	Reefer engine RPM.
`engineHours`	number	Cumulative engine hours.
`voltage`	number	Reefer battery voltage.

`readings.sensor.fuel`

Field	Type	Description
`type`	string	`DIESEL`, `GASOLINE`, `ELECTRIC`, `LIQUEFIED_NATURAL_GAS`, `COMPRESSED_NATURAL_GAS`.
`currentLevel`	number	0–100.
`capacity`	number	Tank capacity.
`fuelUnit`	string	`PERCENT`, `LITER`, `GALLON`, `PERCENT_REMAINING`, `KWH`.

`readings.sensor.zones[]`

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

Field	Type	Description
`id`	string	`ZONE1`–`ZONE5`. Single-zone units send `ZONE1`.
`returnAirTemperature`	number	-100 to 100.
`dischargeAirTemperature`	number	-100 to 100.
`supplyAirTemperature`	number	-100 to 100.
`setPoint`	number	Target temperature, -100 to 100.
`temperatureUnit`	string	`CELSIUS` or `FAHRENHEIT`.
`humidity`	object	`{ "percentage": 0–100 }`.
`battery`	object	`{ "percentage": 0–100, "isCharging": boolean }`.
`doorState`	string	`OPEN`, `CLOSED`, `UNKNOWN`.

`readings.sensor.ambientTemperature`

Field	Type	Description
`value`	number	Ambient temperature.
`unit`	string	`CELSIUS` or `FAHRENHEIT`.

`readings.sensor.tirePressure[]`

Field	Type	Description
`axle`	integer	1-based axle number.
`position`	string	`LEFT`, `RIGHT`, `INNER_LEFT`, `OUTER_LEFT`, `INNER_RIGHT`, `OUTER_RIGHT`.
`psi`	number	0–250.
`alarmState`	string	`OK`, `LOW`, `HIGH`, `CRITICAL`, `UNKNOWN`.

`readings.sensor.shock`

Field	Type	Description
`magnitude`	number	Shock magnitude.
`unit`	string	`G`.
`axis`	string	`X`, `Y`, `Z`, `RESULTANT`.
`durationInMilliseconds`	integer	Duration of the shock event.
`thresholdExceeded`	boolean	Whether a configured threshold was exceeded.
`thresholdValue`	number	The configured threshold.

`readings.sensor.vibration`

Field	Type	Description
`value`	number	Vibration value.
`unit`	string	`G`, `G_RMS`, `IN_PER_SEC`, `MM_PER_SEC`, `MIL`, `UM`, `DB`, `VDV`.
`axis`	string	`X`, `Y`, `Z`, `RESULTANT`.
`frequencyInHertz`	number	Dominant frequency.

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.

Category	Key	Description
Shipment	`billOfLadingNumber`	The shipment's bill of lading (BOL) number.
Shipment	`orderNumber`	The shipment's order number.

Additional identifier keys are accepted and stored, but only billOfLadingNumber and orderNumber currently resolve the shipment. Leading and trailing whitespace on identifier values is trimmed before matching.

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.

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:

Event type	Description
`ARRIVAL_AT_STOP`	Vehicle has arrived at the stop.
`DEPARTURE_FROM_STOP`	Vehicle has departed from the stop.
`LOAD_ONTO_VEHICLE`	Freight is being loaded onto the vehicle.
`UNLOAD_FROM_VEHICLE`	Freight is being unloaded from the vehicle.
`DELIVERY`	Freight has been delivered.
`GATE_IN`	Unit has entered the gate/facility.
`GATE_OUT`	Unit has exited the gate/facility.
`DISPATCH`	Vehicle has been dispatched.
`ARRIVED_AT_TERMINAL`	Unit has arrived at a terminal.
`DEPARTED_TERMINAL`	Unit has departed a terminal.

Events that do not map to a milestone (for example PICKED_UP, OUT_FOR_DELIVERY) are accepted with 202 and stored, but do not change the shipment's status. A position update flows whenever readings.position is present, regardless of the event type.

Payload limits

Entity	Limit
Total payload	1 MB
`identifiers` keys	250
Identifier value length	256 characters
`readings.sensor.zones[]` items	5
`readings.sensor.tirePressure[]` items	22

Error response codes

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

Status code	Meaning
`400 Bad Request`	Synchronous schema validation failed. The response body lists each violation. The event was not accepted.
`401 Unauthorized`	Authentication credentials are missing or invalid.
`403 Forbidden`	Your credentials are not authorized to push for this tenant.
`404 Not Found`	The requested resource does not exist.
`413 Content Too Large`	Payload exceeds the 1 MB size limit.

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.

JSON

{
  "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"
}

Error Response Field	Description
`httpStatusCode`	The value of the HTTP status code.
`httpMessage`	A brief description of the HTTP status code.
`errorMessage`	A detailed description of the error. Returned `null` for schema-validation errors.
`errors`	An array containing one entry per violation.
`errors.severity`	The severity of the message. Possible values: `ERROR`, `WARNING`, `INFO`.
`errors.message`	The JSON path of the offending field plus the reason.
`errors.diagnostic`	A machine-readable diagnostic code and the JSON path (for example `MISSING_REQUIRED_FIELD at $.truckload.identifiers`).
`errors.source`	The originator of the error. Returned `null` for schema-validation errors.
`supportReferenceId`	A reference identifier to quote when contacting project44 support.

Appendix

Request envelope

FTL mode body (truckload)

Objects

shipmentEvent

readings

readings.position

readings.sensor

readings.sensor.reefer

readings.sensor.fuel

readings.sensor.zones[]

readings.sensor.ambientTemperature

readings.sensor.tirePressure[]

readings.sensor.shock

readings.sensor.vibration