Introduction

The Data Ingest API provides a streamlined method for ingesting asset data into the Trackunit Iris platform. This RESTful API is designed for efficient time-series data transmission, prioritizing accuracy for both historical and real-time asset information within the Iris ecosystem.

Supports ingestion of multiple data types:

• Machine Insights
• Locations
• Advanced Sensors
• Faults

Subscription requirement

The Data Ingest API is only available to customers on IrisX. Learn more about the IrisX subscription

Early access

Please be aware that Data Ingest API is currently in an early access, available only upon request.

Use Cases

The Data Ingest API is particularly valuable for:

• Systems requiring minimal data latency
• Recovery scenarios requiring backfilling of data
• Migration projects involving bulk historical data import
• Telematics data integrations where data feeds are insufficient

Updating data points is not supported

The Data Ingest API does not support updating or overwriting existing data. Once a data point with a specific timestamp has been ingested, attempting to send a new datapoint with the same timestamp may lead to unexpected behavior.

The only exception is Faults, which are updated when sent again with the same identifier and occurrence time.

Concepts

Assets

Assets are the core entities in the Trackunit ecosystem, representing various machines, equipment, tools, and attachments:

• Each asset has a unique identifier in the system
• Assets can have zero to many telematics devices associated with them
• Learn more about assets

Machine Insights

Machine Insights are standardized metrics that provide comprehensive operational data about assets:

• Conform to ISO 15143-3 standards plus Trackunit-specific extensions
• Provide normalized data across different asset types, enabling standardized reporting and analytics
• Support both real-time monitoring and historical trend analysis
• Learn more about Machine Insights

Advanced Sensors

Advanced Sensors represent custom, non-standardized metrics that capture equipment-specific data points:

• Identified by unique sensor IDs within the Trackunit platform
• Designed to accommodate proprietary or specialized measurements not covered by standard Machine Insights
• Ideal for capturing manufacturer-specific CAN bus data or equipment-specific readings

Locations

Geographical position information for assets:

• Includes latitude, longitude, and accuracy radius
• Timestamped for tracking movement history

Faults

Diagnostic or problem events reported for an asset, such as a generator alarm or an engine fault code:

• Have a lifecycle: open while active, resolved once cleared
• Shown in Manager as Machine Faults in the asset's event log
• Learn more about Faults

Requirements

• User's account has visibility access of the assets
• All assets already exist within the Trackunit Iris Platform and have exactly one associated telematics device. Otherwise all datapoints of the asset are rejected with a TELEMATICS_DEVICE_NOT_FOUND or MULTIPLE_TELEMATICS_DEVICES violation.
• Advanced Sensors already exists within Trackunit Iris Platform
• Datapoint timestamps are no older than 400 days and no more than 2 days in the future. Datapoints outside this range are rejected.
• Each datapoint appears only once per asset in a request. See Duplicate datapoints.

If a new device needs to be created, it can be done via Create Assets API using the assetType "OTHER". An associated telematics device will be created automatically.

Duplicate datapoints

Within one request, datapoints of the same asset are duplicates when they share the same key:

Type	Key
Location	datetime
MachineInsight	insightType and datetime
AdvancedSensor	sensorId and datetime
FaultCode	identifier and occurredAt

Datetimes are compared as instants at millisecond precision, so the same moment written with different time zone offsets is the same key.

• Identical copies (every field equal) are ingested once and counted once in totalDatapoints.
• Conflicting copies (same key, any field different) are all rejected with a DUPLICATE_DATAPOINT violation. No copy is ingested. The rest of the request is still processed and the response is 207 Multi-Status.