Telematics Guru supports a number of 3rd Party Device Types directly, such as Teltonika, Calamp and SPOT devices. Such devices can be configured as an asset and the Device Type selected from a dropdown. The specific payloads sent from these devices will be recognised by Telematics Guru and processed.

However there is a 3rd Party Device API, to allow for generic device data to be pushed into TG via HTTP POST. Relevant device data can be sent via JSON to Telematics Guru and these assets will be displayed.

Telematics Guru Third Party Device API
 

The Telematics Guru Third Party Device API lets you send telemetry into Telematics Guru from non-Digital Matter hardware using an HTTP POST with a JSON payload. This is useful when you have an existing device fleet (or a niche device type) and want it to appear and behave like a normal Telematics Guru-tracked asset. 

If you searched “Telematics Guru API” and you’re not sure which API you need, start at The Telematics Guru API. 

Prerequisites

• An API username (three-letter prefix) and password (Basic HTTP authentication). 
   
• The correct region endpoint for your Telematics Guru instance. If you’re unsure which region you’re on, use TG Region Specific Details. 
   
• The asset created in Telematics Guru with an SN that matches what you will send (including your prefix).

Endpoint and Authentication

Send HTTP POST requests to:

https://api-<region>.telematics.guru:7082

Authentication is Basic HTTP authentication using your API username and password.

The request body must be JSON. Responses are either HTTP 200 (success) or HTTP 500 (failure) with a textual error description.

Request Body Data Format

The payload is a single object containing an asset identifier (SN, plus optional IMEI/ICCID) and an array of one or more Records. Any field that is not required can be omitted.

Top-level fields

• SN (String, required) - Serial number exactly as entered in Telematics Guru, including your username prefix (for example, “AAA123”). 
   
• IMEI (String, optional) - Modem IMEI. 
   
• ICCID (String, optional) - SIM ICCID. 
   
• Records (Array, required) - One or more records (see below).

Record fields

Each record represents a point-in-time update (typically a GPS update plus IO/analog values).

• DateUTC (DateTime, required) - Timestamp of the record (second precision). 
   
• SeqNum (Int64, required) - Used for deduplication. Telematics Guru keeps a counter per asset and ignores out-of-order records, so this should be monotonically increasing. 
   
• LogReason (Byte, required) - Why the record was logged (see Log Reasons below). 
   
• Lat (Double, required) - Latitude in degrees (sign indicates N/S). 
   
• Lng (Double, required) - Longitude in degrees (sign indicates W/E). 
   
• SpeedKmH (Int16, optional) - Speed in km/h. 
   
• Heading (Int16, optional) - Heading in degrees. 
   
• Alt (Int16, optional) - Altitude in metres. 
   
• SpeedAcc (Byte, optional) - Speed accuracy indicator (cm/s / 10). 
   
• PositionAcc (Byte, optional) - Positional accuracy in metres. 
   
• PDOP (Byte, optional) - GPS PDOP (x10). 
   
• GpsFixOK (Bool, optional) - GPS fix valid. 
   
• GpsFix3D (Bool, optional) - GPS fix is 3D. 
   
• DigIn (Int32, required) - 32-bit integer of digital inputs (Input 0 = bit 0/LSB, Input 1 = bit 1, etc.). 
   
• DigOut (Int16, optional) - 16-bit integer of digital outputs (Output 0 = bit 0/LSB, etc.). 
   
• StatusFlags (Int16, optional) - General status flags. 
   
• DriverIdType (Byte, optional) and DriverIdData (Byte[], optional) - Driver ID data (types below). 
   
• A1...A10 (Int16, optional) - 16-bit signed analogue values (for example, battery voltage). 
   
• A11...A20 (Int32, optional) - 32-bit signed analogue values. 
   
• TTCode (String, optional) - Trip Type code as defined in Telematics Guru. Any record received during a trip assigns the trip type to that trip. 
   
• ProjCode (String, optional) - Project code as defined in Telematics Guru. Any record received during a trip assigns the project to that trip.

Log Reasons

Set LogReason per record to indicate why the record was generated.

• 1 - Start Of Trip 
   
• 2 - End Of Trip 
   
• 3 - Elapsed Time 
   
• 4 - Speed Change 
   
• 5 - Heading Change 
   
• 6 - Distance Travelled 
   
• 7 - Maximum Speed 
   
• 8 - Stationary 
   
• 9 - Digital Input Changed 
   
• 10 - Digital Output Changed 
   
• 11 - Heartbeat 
   
• 12 - Harsh Brake 
   
• 13 - Harsh Acceleration 
   
• 14 - Harsh Cornering 
   
• 15 - External Power Change 
   
• 17 - Driver ID Tag Read 
   
• 29 - Tamper Alert 
   
• 32 - Trip Restart

Driver ID Types

If you send driver identification, set DriverIdType and populate DriverIdData. If you need help with formatting, contact support.

• 0 - None 
   
• 1 - DM RFID 
   
• 2 - iButton 
   
• 3 - 4 Digit PIN 
   
• 4 - 5 Digit PIN 
   
• 5 - Username

How Trips Are Started and Ended

Telematics Guru uses the “In Trip IO” digital input to decide whether an asset is currently in a trip. By default this is Input 1 (bit 1). While this input is high, the asset is considered to be in a trip.

Ignition is tracked separately (default Input 0 / bit 0). The asset will only accumulate run hours and odometer distance when ignition is high during a trip. Keeping these separate helps distinguish “towing” trips versus “ignition” trips.

Example DigIn bit patterns:

• 0x00000000 - Neither trip nor ignition bits are high.
   
• 0x00000001 - Ignition IO is high, Trip IO is low.
   
• 0x00000002 - Ignition IO is low, Trip IO is high.
   
• 0x00000003 - Ignition IO and Trip IO are high.

Example JSON Payload

Below is the example payload structure from the API document. Adjust fields to match what you have available, and omit optional fields when you don’t need them.

{
  "SN": "XYZ1234567",
  "Records": [
    {
      "DateUTC": "2017-02-07T09:45:37.007",
      "SeqNum": 1233,
      "LogReason": 2,
      "Lat": -26.0430947,
      "Lng": 28.0147811,
      "SpeedKmh": 97,
      "Heading": 221,
      "DigIn": 3,
      "A1": 3574,
      "A2": 1140,
      "TTCode": "48",
      "ProjCode": "90"
    },
    {
      "DateUTC": "2017-02-07T09:48:37.007",
      "SeqNum": 1234,
      "LogReason": 2,
      "Lat": -26.0430947,
      "Lng": 28.0147811,
      "SpeedKmh": 97,
      "Heading": 221,
      "DigIn": 3,
      "A1": 3574,
      "A2": 1140,
      "TTCode": "48",
      "ProjCode": "90"
    }
  ]
}

Troubleshooting and Support

• If records aren’t appearing, confirm you are posting to the correct region endpoint (see TG Region Specific Details).
   
• If points are missing or “stale,” confirm SeqNum is strictly increasing per asset. Out-of-order records are ignored. 
   
• If trips are not forming correctly, confirm your DigIn bit mapping matches your intended ignition/trip behaviour (by default, ignition is Input 0 and in-trip is Input 1). 
   
• For driver ID formatting questions, contact support (the API document notes there are multiple formats).

For advanced help please fee free to Contact Support 

Next Steps

If you are evaluating third-party hardware options (including device types Telematics Guru can ingest natively), start with Third Party Device Support in Telematics Guru. 

For the broader integration picture (GraphQL, REST task guides, and webhooks), go to The Telematics Guru API.