Skip to content
TLGPSDocumentation

Developer documentation

Gateway / V1

Subscriptions

Gateway V1 connections, subscriptions and supported updates.

Subscriptions determine which Real-time events are delivered to a connected client.

After successful authentication, clients may subscribe to one or more topics. Each subscription instructs the Fleet Management Gateway to deliver events matching the specified resource.

A single Gateway connection may maintain multiple active subscriptions simultaneously.

Subscriptions remain active until one of the following occurs:

  • The client explicitly unsubscribes.
  • The Gateway connection is closed.
  • The gateway disconnects the client.

Subscription Model

Every subscription consists of two components:

Field Description
topic The type of resource being monitored.
identifier The UUID identifying the specific resource.

The current protocol supports subscriptions to specific vehicles only.


Subscription Lifecycle

Client                                 Gateway
  │                                       │
  ├────────── Subscribe ─────────────────►│
  │                                       │
  │◄───────── Subscribed ─────────────────│
  │                                       │
  │◄────────── Telemetry ─────────────────│
  │◄────────── Telemetry ─────────────────│
  │◄────────── Telemetry ─────────────────│
  │                                       │
  ├──────── Unsubscribe ─────────────────►│
  │                                       │
  │◄────────--------- Unsubscribed ───────│

Subscription Message

Clients create subscriptions by sending a subscribe message.

{
    "type": "subscribe",
    "subscriptions": [
        {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    ]
}

Subscription Fields

Field Type Description
topic string Resource type to subscribe to.
identifier UUID UUID of the resource associated with the topic.

Successful Subscription

When the subscription is accepted, the gateway responds with:

{
    "type": "subscribed",
    "timestamp": "2026-07-05T15:37:10+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    }
}

Receiving a subscribed message indicates that the subscription has been successfully registered and the client will begin receiving matching Real-time events.


Removing a Subscription

Clients may stop receiving events by sending an unsubscribe message.

{
    "type": "unsubscribe",
    "subscriptions": [
        {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    ]
}

Successful Unsubscription

{
    "type": "unsubscribed",
    "timestamp": "2026-07-05T15:37:10+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    }
}

Subscription Notes

  • A client may maintain multiple active subscriptions simultaneously.
  • One request may contain multiple vehicle subscriptions.
  • Duplicate topic/identifier pairs produce one effective subscription.
  • Batch preparation is all-or-nothing. If any requested vehicle is unavailable, none of that request is registered.
  • Vehicle permission and current Company visibility constrain the subscription.
  • Offline vehicles may be subscribed.
  • A vehicle without resolved current state receives a subscribed acknowledgment without an initial telemetry message; future telemetry still reaches the active subscription.
  • Unsubscribing from a resource that is not currently subscribed has no effect.
  • Subscriptions are scoped to the current Gateway connection.
  • Closing the connection automatically removes all active subscriptions.

Public documentation · authorized integration access required

Engineering-maintained documentation. Examples use synthetic data and placeholder credentials.

Back to top