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

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.