Telematics Guru Third Party Device API: Tutorial

This tutorial walks through a single, complete example: one vehicle making one trip, sent into Telematics Guru through the Third Party Device API. It shows the three key moments of a trip (start, mid-trip, and end) with a sample JSON POST for each, and explains how Telematics Guru interprets them. By the end you will understand how the records you send translate into a trip on the map.

This article assumes you have already read the Telematics Guru Third Party Device API: Detailed Setup article, which covers your username and serial prefix, the regional endpoint, authentication, and the full payload field reference. If you are new to the API, start with the Telematics Guru Third Party Device API: Overview.

The Scenario

We will track a single vehicle through one trip:

• Serial number AAA123 (prefix AAA, matching the account's allocated prefix).
• Default digital input mapping, where Ignition is Input0 (bit 0) and the In Trip IO is Input1 (bit 1).
• With that mapping, the DigIn value is a bitmask: bit 0 is ignition, bit 1 is the in-trip input. So DigIn = 3 means both ignition and the in-trip input are high; DigIn = 1 means only ignition is high; DigIn = 0 means both are low.

Each step below is one HTTP POST to the regional endpoint with Basic authentication, as described in the setup article. We show only the JSON body here.

Step 1: Start of Trip

The vehicle starts moving. We send a record with LogReason 1 (Start Of Trip) and set DigIn to 3 so that both ignition and the in-trip input are high. Raising the in-trip input is what opens the trip.

{
  "Serial": "AAA123",
  "Records": [
    {
      "SeqNo": 1,
      "DateUTC": "2026-10-21 08:00:00",
      "LogReason": 1,
      "Lat": -31.95224,
      "Long": 115.86140,
      "Speed": 0,
      "Heading": 0,
      "DigIn": 3
    }
  ]
}

Telematics Guru opens a new trip for the asset. The in-trip input is high, so the asset is now considered to be on a trip. The position appears on the map as the trip's starting point.

Step 2: Mid-Trip

As the vehicle drives, your service keeps sending position records. You can send them one at a time or batch several records into a single POST; batching is efficient for devices that buffer points. Here we send two records in one POST. Keep DigIn at 3 throughout the trip so the in-trip input stays high and the trip remains open.

{
  "Serial": "AAA123",
  "Records": [
    {
      "SeqNo": 2,
      "DateUTC": "2026-10-21 08:05:00",
      "LogReason": 4,
      "Lat": -31.94870,
      "Long": 115.85730,
      "Speed": 42,
      "Heading": 310,
      "DigIn": 3
    },
    {
      "SeqNo": 3,
      "DateUTC": "2026-10-21 08:10:00",
      "LogReason": 4,
      "Lat": -31.94210,
      "Long": 115.85090,
      "Speed": 55,
      "Heading": 295,
      "DigIn": 3
    }
  ]
}

Each record extends the trip with a new point. LogReason 4 here represents ongoing in-trip logging (for example a time or distance interval). Note two things about mid-trip sending:

• Increment SeqNo on every record. The sequence number must always increase. Telematics Guru uses it to order records and to recognise ones it has already seen.
• Duplicate records are de-duplicated. If your service retries a POST or resends a record with a sequence number already received, Telematics Guru discards the duplicate rather than adding a second point. This makes retries safe, but it is why the sequence number must keep increasing for genuinely new records.

Step 3: End of Trip

The vehicle arrives and the trip should end. We send a record with LogReason 2 (End Of Trip) and, importantly, drop the in-trip input by setting DigIn to 1 (ignition still on) or 0 (ignition off as well).

{
  "Serial": "AAA123",
  "Records": [
    {
      "SeqNo": 4,
      "DateUTC": "2026-10-21 08:20:00",
      "LogReason": 2,
      "Lat": -31.93680,
      "Long": 115.84420,
      "Speed": 0,
      "Heading": 0,
      "DigIn": 1
    }
  ]
}

The in-trip input has gone low, so Telematics Guru closes the trip. The final point becomes the trip's end location, and the completed trip is available on the map and in reporting like any other.

What You Sent and What Happened

Putting the three steps together:

• Step 1 raised the in-trip input (DigIn 3) with Start Of Trip, which opened the trip.
• Step 2 sent ongoing points with the in-trip input still high (DigIn 3), each with an increasing sequence number, keeping the trip open and extending its path. Duplicates were discarded automatically.
• Step 3 dropped the in-trip input (DigIn 1 or 0) with End Of Trip, which closed the trip.

The result is one clean trip for serial AAA123, from the start point to the end point, behaving like any other Telematics Guru trip.

Next Steps

From here, extend the same pattern to your real integration: translate your device's telemetry into these records, increment the sequence number for every new record, keep the in-trip input high for the duration of each trip, and drop it to end the trip. For the complete field reference, log reason list, and response codes, see the Telematics Guru Third Party Device API: Detailed Setup article. If you need help, contact your Telematics Guru provider's support.