Telematics Guru Third Party Device API: Detailed Setup

This article is the technical reference for sending telemetry into Telematics Guru with the Third Party Device API. It covers prerequisites, the regional endpoint and authentication, the serial-number prefix requirement, the full JSON payload structure, the LogReason and Driver ID tables, how trips and ignition are modelled from digital inputs, the StatusFlags rule, and the responses you should expect. For the concept and use cases, see the Third Party Device API overview.
 

Prerequisites

An API username (a three-letter prefix) and password, used for Basic HTTP authentication. You request a desired three-letter username and your Telematics Guru provider assigns it if it is still available.
 

The correct region endpoint for your Telematics Guru instance. If you are unsure which region you are on, see TG Region Specific Details.
 

The asset created in Telematics Guru with a serial number (SN) that matches what you will send, including your prefix.
 

Serial Number Prefix Requirement

Your assigned three-letter API username becomes part of every asset serial number you send. When you add the asset in Telematics Guru, its serial number must include this prefix, for example AAA123. You are responsible for keeping serial numbers unique within your prefix.
 

Endpoint and Authentication

Send HTTP POST requests to the regional endpoint:
 

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

Replace <region> with your instance's region. Authentication is Basic HTTP authentication using your API username and password. The request body must be JSON.
 

Request Body: Payload Structure

The payload is a single JSON object containing an asset identifier and an array of one or more records. Each record is a point-in-time update, typically a GPS update plus IO and analogue values. Any field that is not required can be omitted.
 

Top-level fields

Record fields

Log Reasons

Set LogReason on each record to indicate why it was generated. Log reasons are generally informative. Harsh driving reasons (12, 13, and 14) are treated as an exception rather than purely informative.
 

Driver ID Types

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

Trips and Ignition from Digital Inputs

Telematics Guru decides whether an asset is currently in a trip using the "In Trip IO" digital input. 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, by default on Input 0 (bit 0). The asset only accumulates run hours and odometer distance when ignition is high during a trip. Keeping these separate helps distinguish towing trips from ignition trips.
 

Example DigIn bit patterns using the default mapping:
 

Digital Outputs

DigOut supplies digital output states. For example, DigOut=1 sets output 0, and DigOut=0 clears it.
 

StatusFlags and the DigIn High Byte

When StatusFlags is present, its least significant byte overrides the most significant byte of DigIn. Because DigIn is a 32-bit value, do not assume all 32 submitted input bits are preserved unchanged when you also send StatusFlags. If you rely on the high input bits, account for this overlay.
 

Timestamps

DateUTC is specified at second precision. A value sent without a timezone suffix is interpreted as UTC. Values with fractional seconds were accepted and processed.
 

Responses

Each POST returns one of the following:
 

Next Steps

To see these fields in a running scenario, continue to the Third Party Device API tutorial, which walks through a single vehicle and one trip with sample start, mid-trip, and end JSON POSTs and the resulting Telematics Guru behaviour.