Faults

Faults can be ingested through the Assets data ingest endpoint alongside Machine Insights, Locations and Advanced Sensors.

What is a fault

A fault is a diagnostic or problem event reported for an asset, such as a generator alarm or an engine fault code. Unlike other datapoints, a fault has a lifecycle:

• Open - the fault has occurred and is still active
• Resolved - the fault has been cleared

Ingested faults appear in Manager as Machine Faults in the asset's event log, with a criticality derived from their severity and a history of state changes.

Structure

A fault is sent as a datapoint with type set to FaultCode:

Field	Required	Description
type	Yes	Always FaultCode
identifier	Yes	Your fault code, as free-form text
occurredAt	Yes	ISO 8601 date-time when the fault occurred
resolvedAt	No	ISO 8601 date-time when the fault was resolved. When present, the fault is resolved
severity	No	Integer from 0 to 100. Determines the criticality, see Severity and criticality
description	No	Human-readable description of the fault
codeSource	No	Integer from 0 to 255. J1939 source address of the controller (ECU) that reported the fault, complementing identifier (e.g. SPN and FMI). It is not part of the fault identity: if the same identifier can be reported by several controllers, include the source in identifier as well

occurredAt and resolvedAt must be within the accepted time range of 400 days in the past to 2 days in the future.

Always provide a description

Trackunit has no interpretation for ingested fault identifiers. Without a description, the fault is shown as "Unknown Machine Fault".

Example

{
  "assetData": [
    {
      "metadata": {
        "assetId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "datapoints": [
        {
          "type": "FaultCode",
          "identifier": "E042",
          "occurredAt": "2026-10-20T08:15:00Z",
          "severity": 80,
          "description": "Low oil pressure",
          "codeSource": 0
        }
      ]
    }
  ]
}

Fault identity

A fault is identified by its identifier and occurredAt on a given asset. Sending a fault with the same identifier and occurredAt again updates the existing fault instead of creating a new one. This is how faults are resolved and corrected.

Two faults with the same identifier but a different occurredAt are separate occurrences.

Lifecycle

Open a fault

Send the fault without resolvedAt:

{
  "type": "FaultCode",
  "identifier": "E042",
  "occurredAt": "2026-10-20T08:15:00Z",
  "severity": 80,
  "description": "Low oil pressure"
}

Resolve a fault

Send the same identifier and occurredAt again, with resolvedAt:

{
  "type": "FaultCode",
  "identifier": "E042",
  "occurredAt": "2026-10-20T08:15:00Z",
  "resolvedAt": "2026-10-20T09:40:00Z",
  "severity": 80,
  "description": "Low oil pressure"
}

Always send the complete fault. The re-sent fault replaces the previous version.

Update a fault

To correct the severity or description of a fault, send it again with the same identifier and occurredAt and the new values.

Ingest a resolved fault

A fault that has already been resolved can be sent in a single request, with both occurredAt and resolvedAt. It is created directly as resolved, never appears as an active fault, and does not raise an alarm. Use this when backfilling historical faults, or when a fault opened and resolved since your last request. Send only the resolved version: an open and a resolved copy of the same fault in one request are rejected as duplicates.

Resolving a fault that is already resolved has no effect.

Severity and criticality

severity is mapped to the criticality shown in Manager:

Severity	Criticality
0	None
1 - 50	Low
51 - 100	Critical
Not provided	Low (defaults to 5)

There is no intermediate criticality level. A fault sent without severity cannot be told apart from one sent with a low severity.

Fault events for integrators

Ingested faults are published to webhooks and other integrations as fault code events, like faults reported by Trackunit devices.

• Send a fault only when it is new, changed, or resolved. Every update reaches Trackunit, but integrations may receive a re-sent open fault again or not at all, whether it changed or not. Avoid re-sending unchanged faults, for example all open faults on a schedule.

Known limitations

• No mobile push notifications. Ingested faults do not trigger push notifications in the Trackunit mobile apps.
• Not shown in Service Management. Ingested faults do not appear in Trackunit Service Management.
• No fault interpretation. Fault identifiers are not matched against Trackunit's fault code catalogue. The description you send is the only explanation shown to users.
• No deletion. A fault cannot be deleted through the API, only updated or resolved.