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
        }
      }
    }
  ]
}

Field level Description

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.