Asset pairing with communication unit

The asset event group supports pairing events for communication units and assets. A unit can be paired automatically when it is installed on an asset and begins communicating, based on the VIN configured in the TBS or EBS, or manually through the SCALAR UI or the Datahub API.

These events are available to customers with an active Datahub subscription.

Datahub subscription configuration

In the Datahub portal, users can configure the webhook URL for the event group asset and the following event names:

"unit.paired"
"unit.unpaired"

{
  "eventBatchId": "31fccdce-725e-4c87-a91b-3a8e66144641",
  "eventSubscriptionId": "41634ca6-a7fb-4dc2-9461-7e9b24be885e",
  "eventBatchTime": "2025-05-13T13:18:13.2017310Z",
  "eventsData": [
    {
      "eventType": "unit.paired",
      "eventVersion": 2,
      "eventData": {
        "registeredOn": "2025-05-12T22:20:00.000Z",
        "organizationId": "c8c90b90-ad39-4a3d-8b89-c25a22acaa25",
        "unitId": "txtrailerguard:359315075384726",
        "status": "failed",
        "reason": "Unknown",
        "sensorVIN": "F3D000001",
        "location": {
          "latitude": 50.869,
          "longitude": 2.8942
        }
      }
    }
  ]
}

Field level Description

Standard event envelope

Field	Type	Required	Description
eventBatchId	String (UUID)	Required	A unique identifier for the batch of events. Multiple events occurring close together can be grouped into a single batch.
eventSubscriptionId	String (UUID)	Required	A unique identifier representing the subscription through which the event was delivered.
eventBatchTime	DateTime (ISO 8601 timestamp, UTC)	Required	The timestamp when the event batch was created and prepared for delivery.
eventsData	Array	Required	An array containing one or more asset pairing event objects.
eventsData[].eventType	String	Required	The type of event. Possible values in this event group: unit.paired, unit.unpaired.
eventsData[].eventVersion	Integer	Required	The version of the event schema. Currently 1.
eventsData[].eventData	Object	Required	Contains the asset pairing payload data.

Pairing lifecycle

Asset pairing events progress through the following outcomes:

unit.paired → success  (manual or auto pairing completed) 
unit.paired → failed   (InvalidData | NotFound | MultipleMatchFound | Unknown) 
unit.unpaired            (manual unpairing completed)

The unit.paired events is used for both successful and failed pairing attempts. The final outcome is determined by the status and reason fields in eventData.

Business decisions

All asset pairing events follow the standard Datahub event envelope with eventBatchId, eventSubscriptionId, eventBatchTime, and eventsData.
Manual pairing and manual unpairing can be performed through the SCALAR UI or the Datahub API.
Auto pairing depends on the VIN configured in the TBS or EBS and the organization-level auto pairing configuration.
The unit.paired event may represent either a successful pairing or a failed pairing attempt.
candidateAssetIds is only applicable for the MultipleMatchFound auto pairing outcome.
In the NotFound scenario, the failure event is emitted every hour for 48 hours to encourage remediation.
The location object, when present, contains latitude and longitude reported with the pairing attempt