Alert Monitoring Pipeline

Overview

V2 uses standard pagination for alert retrieval — no sliding window or num cap required. Alerts are returned as AlertDto records from GET /v2/api/companies/{id}/alert-records. Key fields per alert:

Field	Type	Description
`id`	integer	Unique alert identifier — use for acknowledgement
`utcTime`	string	When the alert occurred (UTC, no `Z` suffix)
`userTime`	string	Alert time in the user’s configured timezone
`userTimeFormatted`	string	Pre-formatted display string
`alertType`	string	Alert type identifier (e.g. `"18"`)
`description`	string	Human-readable alert message
`vehicleId`	integer	Vehicle that triggered the alert
`vehicleName`	string	Vehicle display name
`address`	string	Reverse-geocoded location
`lat` / `lng`	double	Location coordinates
`isRead`	boolean	Whether the alert has been acknowledged

V2 adds GET /v2/api/companies/{id}/alerts which returns your alert configurations — including the human-readable AlertType string (e.g. "Speeding", "Geofence"). Use this to build your type mapping instead of discovering it empirically.

Step 1 — Look up alert type names

Before polling, fetch your alert configurations to build a type-ID-to-name map:

Python

import requests

def get_alert_config_map(company_id: int, token: str) -> dict:
    configs = {}
    page = 1
    while True:
        r = requests.get(
            f"https://api.telemax.com.au/v2/api/companies/{company_id}/alerts",
            params={"page": page, "pageSize": 50},
            headers={"Authorization": f"Bearer {token}"},
        )
        r.raise_for_status()
        data = r.json()
        for cfg in data.get("items", []):
            configs[cfg["alertId"]] = cfg["alertType"]   # e.g. {3631: "18"}
        if page >= data.get("numberOfPages", 1):
            break
        page += 1
    return configs

Step 2 — Poll with pagination

GET /v2/api/companies/{id}/alert-records supports standard page/pageSize pagination. Filter by IsRead to process only unread alerts.

import os, time, requests

API_BASE   = "https://api.telemax.com.au"
API_KEY    = os.environ["TELEMAX_API_KEY"]
COMPANY_ID = 85
POLL_SEC   = 60

_token, _expires_at = None, 0

def get_token():
    global _token, _expires_at
    if _token and time.time() < _expires_at - 300:
        return _token
    r = requests.post(f"{API_BASE}/v2/api/authentication/token/api-key",
                      data={"apiKey": API_KEY})
    r.raise_for_status()
    d = r.json()
    _token, _expires_at = d["access_token"], time.time() + d["expires_in"]
    return _token

def fetch_unread_alerts() -> list:
    alerts = []
    page = 1
    while True:
        r = requests.get(
            f"{API_BASE}/v2/api/companies/{COMPANY_ID}/alert-records",
            params={"page": page, "pageSize": 50},
            headers={"Authorization": f"Bearer {get_token()}"},
        )
        r.raise_for_status()
        data = r.json()
        unread = [a for a in data.get("items", []) if not a["isRead"]]
        alerts.extend(unread)
        if page >= data.get("numberOfPages", 1):
            break
        page += 1
    return alerts

alert_types = get_alert_config_map(COMPANY_ID, get_token())

while True:
    try:
        alerts = fetch_unread_alerts()
        for alert in alerts:
            process_alert(alert, alert_types)   # your handler — see Step 3
    except Exception as e:
        print(f"Poll error: {e}")
    time.sleep(POLL_SEC)

const API_BASE = "https://api.telemax.com.au";
const COMPANY_ID = 85;
let token = null, tokenExpiresAt = 0;

async function getToken() {
  if (token && Date.now() < tokenExpiresAt - 300_000) return token;
  const res = await fetch(`${API_BASE}/v2/api/authentication/token/api-key`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ apiKey: "YOUR_API_KEY" }),
  });
  const { access_token, expires_in } = await res.json();
  token = access_token;
  tokenExpiresAt = Date.now() + expires_in * 1000;
  return token;
}

async function fetchUnreadAlerts() {
  const alerts = [];
  let page = 1;
  while (true) {
    const res = await fetch(
      `${API_BASE}/v2/api/companies/${COMPANY_ID}/alert-records?page=${page}&pageSize=50`,
      { headers: { Authorization: `Bearer ${await getToken()}` } },
    );
    const data = await res.json();
    alerts.push(...(data.items ?? []).filter(a => !a.isRead));
    if (page >= (data.numberOfPages ?? 1)) break;
    page++;
  }
  return alerts;
}

async function pollAlerts() {
  const alerts = await fetchUnreadAlerts();
  for (const alert of alerts) {
    handleAlert(alert);  // your handler — see Step 3
  }
}

pollAlerts();
setInterval(pollAlerts, 60_000);

Step 3 — Filter by alert type

Use the config map from Step 1 to route alerts to the appropriate handler:

Python

ALERT_HANDLERS = {
    "Speeding":       "overspeed",
    "Geofence":       "geofence",
    "DoorUnlocked":   "door_unlocked",
    "LowBattery":     "battery",
    # extend from your GET /v2/api/companies/{id}/alerts response
}

def process_alert(alert: dict, alert_types: dict):
    type_name  = alert_types.get(alert["alertType"], f"type_{alert['alertType']}")
    handler    = ALERT_HANDLERS.get(type_name, "unknown")
    print(f"[{handler}] {alert['vehicleName']} — {alert['description']} @ {alert['address']}")
    dispatch_notification(handler, alert)

Step 4 — Acknowledge alerts

Mark one alert as read

PUT /v2/api/alerts/{id}/{date}/update-read-status accepts a JSON body. In V2, isRead is honoured — you can mark an alert as unread by passing false.

cURL

curl -s -X PUT \
  "https://api.telemax.com.au/v2/api/alerts/101/2025-05-01T10:30:00/update-read-status?isRead=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

def mark_read(alert: dict, is_read: bool = True):
    requests.put(
        f"{API_BASE}/v2/api/alerts/{alert['id']}/{alert['utcTime']}/update-read-status",
        params={"isRead": str(is_read).lower()},
        headers={"Authorization": f"Bearer {get_token()}"},
    ).raise_for_status()

Bulk clear all alerts

When you want to reset the unread state for the entire company:

cURL

curl -s -X PUT \
  "https://api.telemax.com.au/v2/api/companies/85/set-all-alerts-read" \
  -H "Authorization: Bearer YOUR_TOKEN"

PUT /v2/api/companies/{id}/set-all-alerts-read marks all alerts for the company as read. In multi-tenant or multi-integration setups, only call this when every consumer is caught up.

Building notification rules

Python

SEVERITY = {
    "overspeed":   "high",
    "geofence":    "medium",
    "door_unlocked": "medium",
    "battery":     "low",
}

CHANNELS = {
    "high":   lambda a: send_sms(a),
    "medium": lambda a: send_email(a),
    "low":    lambda a: log_to_dashboard(a),
}

def dispatch_notification(handler: str, alert: dict):
    severity = SEVERITY.get(handler, "low")
    CHANNELS[severity](alert)

Gotchas

No sliding window needed. V2 uses standard pagination — fetch all pages, filter by IsRead: false.
isRead is now honoured. Unlike V1, V2’s update-read-status correctly sets the read state to the value you pass.
AlertType names are available. Use GET /v2/api/companies/{id}/alerts to get the string name for each AlertType integer — no need to build the mapping empirically.
UtcTime has no Z suffix but is always UTC — treat it as UTC when parsing.

Getting Started

Guides

Authentication

Companies & fleet

Vehicles

Vehicle commands

Alerts

Telemetry & replay

Insights & diagnostics

Webhooks

Reference

Alert Monitoring Pipeline

Overview

Step 1 — Look up alert type names

Step 3 — Filter by alert type

Step 4 — Acknowledge alerts

Mark one alert as read

Bulk clear all alerts

Building notification rules

Gotchas

​Overview

​Step 1 — Look up alert type names

​Step 2 — Poll with pagination

​Step 3 — Filter by alert type

​Step 4 — Acknowledge alerts

​Mark one alert as read

​Bulk clear all alerts

​Building notification rules

​Gotchas

Overview

Step 1 — Look up alert type names

Step 2 — Poll with pagination

Step 3 — Filter by alert type

Step 4 — Acknowledge alerts

Mark one alert as read

Bulk clear all alerts

Building notification rules

Gotchas