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"

Events - v1

The following events can be subscribed to:

unit.paired: a communication unit has been paired to an asset
unit.unpaired: a communication unit has been unpaired from an asset

unit.paired

The unit.paired event is emitted when a communication unit is paired to an asset.

This event can be triggered in two ways:

manual pairing through the SCALAR UI or Datahub API
auto pairing when auto pairing is enabled for the organization and the VIN received from the communication unit matches an asset

Manual pairing

The event is emitted when a customer or user manually pairs a communication unit to an asset through the SCALAR UI or the Datahub API.

The payload contains the standard Datahub event envelope together with the pairing result, including the organization, asset, unit, status, reason, and asset VIN.

{
  "eventBatchId": "31fccdce-725e-4c87-a91b-3a8e66144641",
  "eventSubscriptionId": "41634ca6-a7fb-4dc2-9461-7e9b24be885e",
  "eventBatchTime": "2025-05-13T13:18:13.2017310Z",
  "eventsData": [
    {
      "eventType": "unit.paired",
      "eventVersion": 1,
      "eventData": {
        "registeredOn": "2025-05-12T22:20:00.000Z",
        "organizationId": "c8c90b90-ad39-4a3d-8b89-c25a22acaa25",
        "assetId": "5bca3b72-e006-4cea-bfaa-f5a4dcf3a63c",
        "unitId": "tp:890123847562332",
        "status": "success",
        "reason": "ManualPair",
        "assetVIN": "1HGCM82633A000001"
      }
    }
  ]
}

Failure scenario

This payload is emitted when the auto pairing flow fails. Failure can occur because of invalid data, no matching asset, multiple matching assets, or an unknown system error.

InvalidData

This payload is emitted when the VIN is unavailable or invalid and cannot be used for asset pairing.

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

MultipleMatchFound

This payload is emitted when the VIN partially matches more than one asset.

{
  "eventBatchId": "31fccdce-725e-4c87-a91b-3a8e66144641",
  "eventSubscriptionId": "41634ca6-a7fb-4dc2-9461-7e9b24be885e",
  "eventBatchTime": "2025-05-13T13:18:13.2017310Z",
  "eventsData": [
    {
      "eventType": "unit.paired",
      "eventVersion": 1,
      "eventData": {
        "registeredOn": "2025-05-12T22:20:00.000Z",
        "organizationId": "c8c90b90-ad39-4a3d-8b89-c25a22acaa25",
        "unitId": "krone:890123847562332",
        "status": "failed",
        "reason": "MultipleMatchFound",
        "sensorVIN": "F3D000001",
        "candidateAssetIds": [
          "c8c90b90-ad39-4a3d-8b89-c25a22acaa25",
          "d8d90d90-dd29-3d3d-3b89-c45a22acab34"
        ],
        "location": {
          "lat": 50.869,
          "lon": 2.8942
        }
      }
    }
  ]
}

Unknown

This payload is emitted when an unexpected system error prevents the pairing from being completed.

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

unit.unpaired

The unit.unpaired event is emitted when a communication unit is unpaired from an asset.

Manual unpairing

The event is emitted when a customer or user manually unpairs a unit from an asset through the SCALAR UI or the Datahub API.

The payload contains the standard Datahub event envelope together with the asset and unit identifiers for the removed association.

{
  "eventBatchId": "31fccdce-725e-4c87-a91b-3a8e66144641",
  "eventSubscriptionId": "41634ca6-a7fb-4dc2-9461-7e9b24be885e",
  "eventBatchTime": "2025-05-13T13:18:13.2017310Z",
  "eventsData": [
    {
      "eventType": "unit.unpaired",
      "eventVersion": 1,
      "eventData": {
        "registeredOn": "2025-05-12T22:20:00.000Z",
        "organizationId": "c8c90b90-ad39-4a3d-8b89-c25a22acaa25",
        "assetId": "5bca3b72-e006-4cea-bfaa-f5a4dcf3a63c",
        "unitId": "tp:890123847562332",
        "assetVIN": "1HGCM82633A000001"
      }
    }
  ]
}

Events - v2

The following events can be subscribed to in the V2 version of the asset event group:

unit.paired: a communication unit has been paired to an asset.

unit.paired

The unit.paired event is emitted when a communication unit is paired to an asset.

This event can be triggered in two ways:

manual pairing through the SCALAR UI or Datahub API

auto pairing when auto pairing is enabled for the organization and the VIN received from the communication unit matches an asset

Manual pairing

The event is emitted when a customer or user manually pairs a communication unit to an asset through the SCALAR UI or the Datahub API.

The payload contains the standard Datahub event envelope together with the pairing result, including the organization, asset, unit, status, reason, and asset VIN.

{
  "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",
        "assetId": "5bca3b72-e006-4cea-bfaa-f5a4dcf3a63c",
        "unitId": "tp:890123847562332",
        "status": "success",
        "reason": "ManualPair",
        "assetVIN": "1HGCM82633A000001"
      }
    }
  ]
}

Auto pairing

The event is emitted when auto pairing is enabled for the organization and the communication unit starts communicating after installation. The auto pairing flow uses the VIN configured in the TBS or EBS and attempts to match it with an asset in SCALAR.

Asset settings reference: https://help.zf-scalar.com/docs/asset-management/#h-asset-settings

Depending on the outcome of the pairing flow, the payload may include the asset VIN, the sensor VIN, candidate asset IDs, and the reported location.

Success scenario

This payload is emitted when the auto pairing flow completes successfully and the communication unit is paired with the asset based on the VIN match

{
  "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": "tp:890123847562332",
        "status": "success",
        "reason": "AutoPair",
        "assetId": "5bca3b72-e006-4cea-bfaa-f5a4dcf3a63c",
        "assetVIN": "1HGCM82633A000001",
        "sensorVIN": "F3A000001",
        "location": {
          "latitude": 50.869,
          "longitude": 2.8942
        }
      }
    }
  ]
}

Failure scenario

This payload is emitted when the auto pairing flow fails. Failure can occur because of invalid data, no matching asset, multiple matching assets, or an unknown system error.

InvalidData

This payload is emitted when the VIN is unavailable or invalid and cannot be used for asset pairing.

{
  "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": "tp:890123847562332",
        "status": "failed",
        "reason": "InvalidData",
        "location": {
          "latitude": 50.869,
          "longitude": 2.8942
        }
      }
    }
  ]
}

NotFound

This payload is emitted when the VIN does not match exactly or partially against any asset. In this case, the failure event is sent every hour for 48 hours to prompt corrective action and enable successful pairing.

{
  "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": "tp:890123847562332",
        "status": "failed",
        "reason": "NotFound",
        "sensorVIN": "F3A000001",
        "location": {
          "latitude": 50.869,
          "longitude": 2.8942
        }
      }
    }
  ]
}

MultipleMatchFound

This payload is emitted when the VIN partially matches more than one asset.

{
  "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": "krone:890123847562332",
        "status": "failed",
        "reason": "MultipleMatchFound",
        "sensorVIN": "F3D000001",
        "candidateAssetIds": [
          "c8c90b90-ad39-4a3d-8b89-c25a22acaa25",
          "d8d90d90-dd29-3d3d-3b89-c45a22acab34"
        ],
        "location": {
          "latitude": 50.869,
          "longitude": 2.8942
        }
      }
    }
  ]
}

Unknown

This payload is emitted when an unexpected system error prevents the pairing from being completed.

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

unit.paired event data

Field	Type	Required	Description
eventData.registeredOn	DateTime (ISO 8601 timestamp, UTC)	Required	The timestamp when the pairing event was registered in the system.
eventData.organizationId	String (UUID)	Required	The unique identifier of the organization to which the event belongs.
eventData.assetId	String (UUID)	Conditionally required	The unique identifier of the asset paired to the communication unit. Present for successful pairing outcomes.
eventData.unitId	String	Required	The unique identifier of the communication unit, including unit type and serial number.
eventData.status	String	Required	The result of the pairing attempt. Possible values shown in this document: success, failed.
eventData.reason	String	Required	The reason describing how the pairing was processed or why it failed. Possible values shown in this document: ManualPair, AutoPair, InvalidData, NotFound, MultipleMatchFound, Unknown.
eventData.assetVIN	String	Optional	The VIN stored on the asset in SCALAR. Present for manual pairing and successful auto pairing examples.
eventData.sensorVIN	String	Optional	The VIN received from the communication unit and configured in the TBS or EBS. Present for applicable auto pairing outcomes.
eventData.candidateAssetIds	Array of String (UUID)	Optional	A list of candidate asset identifiers that partially match the received VIN. Present only for the MultipleMatchFound outcome.
eventData.location	Object	Optional	The reported location associated with the pairing attempt. Present for applicable auto pairing outcomes.
eventData.location.lat	Number	Required when location is present	The latitude of the reported location.
eventData.location.lon	Number	Required when location is present	The longitude of the reported location.

unit.paired (v2 Event Group) event data

Field	Type	Required	Description
eventData.registeredOn	DateTime (ISO 8601 timestamp, UTC)	Required	The timestamp when the pairing event was registered in the system.
eventData.organizationId	String (UUID)	Required	The unique identifier of the organization to which the event belongs.
eventData.assetId	String (UUID)	Conditionally required	The unique identifier of the asset paired to the communication unit. Present for successful pairing outcomes.
eventData.unitId	String	Required	The unique identifier of the communication unit, including unit type and serial number.
eventData.status	String	Required	The result of the pairing attempt. Possible values shown in this document: success, failed.
eventData.reason	String	Required	The reason describing how the pairing was processed or why it failed. Possible values shown in this document: ManualPair, AutoPair, InvalidData, NotFound, MultipleMatchFound, Unknown.
eventData.assetVIN	String	Optional	The VIN stored on the asset in SCALAR. Present for manual pairing and successful auto pairing examples.
eventData.sensorVIN	String	Optional	The VIN received from the communication unit and configured in the TBS or EBS. Present for applicable auto pairing outcomes.
eventData.candidateAssetIds	Array of String (UUID)	Optional	A list of candidate asset identifiers that partially match the received VIN. Present only for the MultipleMatchFound outcome.
eventData.location	Object	Optional	The reported location associated with the pairing attempt. Present for applicable auto pairing outcomes.
eventData.location.latitude	Number	Required when location is present	The latitude of the reported location.
eventData.location.longitude	Number	Required when location is present	The longitude of the reported location.

unit.unpaired event data

Field	Type	Required	Description
eventData.registeredOn	DateTime (ISO 8601 timestamp, UTC)	Required	The timestamp when the unpairing event was registered in the system.
eventData.organizationId	String (UUID)	Required	The unique identifier of the organization to which the event belongs.
eventData.assetId	String (UUID)	Required	The unique identifier of the asset from which the communication unit was unpaired.
eventData.unitId	String	Required	The unique identifier of the communication unit, including unit type and serial number.
eventData.assetVIN	String	Optional	The VIN stored on the asset in SCALAR at the time of unpairing.

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