Changelog

​

Deprecation policy

1. A deprecation notice is added to this changelog and to the relevant endpoint reference page.
2. The live API begins returning a Sunset HTTP response header (RFC 8594) on every call to the deprecated route, with the removal date as an HTTP-date value:
   Sunset: Sat, 14 Oct 2026 23:59:59 GMT
   
3. The endpoint continues to work for a minimum of 6 months from the deprecation notice date.
4. After the Sunset date the route may return 410 Gone or be removed entirely.

​

API versioning

X-API-Version: 2

​

Version history

​

2026-10-07 — Documentation corrections

​

Corrected

• GET /v2/api/companies/{id}/alert-records — address leads with a house number whenever a nearby address point is found, not only on point-of-interest matches, e.g. "14, George St, Haymarket, Sydney, NSW, AUS"; the house number can be a range or carry a letter (244-246, 533A); the whole address is that address point’s, so it can be a neighbouring property’s, even one on a nearby street rather than the road the vehicle was on; otherwise it is the road’s address, with no house number; parts with no value are left out

• Position fields (vehicle list, last position, fleet last positions, nearest) — address likewise (see PositionDto fields)
• GET /v2/api/vehicles/{id}/engine-codes — location.address likewise

​

2026-10-06 — Documentation corrections

​

Corrected

• Token scoping — a token can use its own company and its direct, non-cancelled sub-companies; companies further down are listed by GET /v2/api/companies but return 404 on other endpoints, and so do vehicles mapped only to them, with the exceptions described in Token scoping

• GET /v2/api/companies — your own company is the item with level 0, listed last (on the last page when there are more companies than pageSize), not the first item
• GET /v2/api/companies/{id}/vehicles/last-position — returns only the vehicles mapped to {id}, not every vehicle of its sub-companies; to cover your fleet, call it for your own company and each direct sub-company, and de-duplicate by deviceId (or imei when deviceId is -1); checkVehicleHandlerState is optional and has no dependable effect, so leave it false
• GET /v2/api/companies/{id}/vehicles/nearest — distances are planar degrees, not metres, with no road routing: realDistance is in degrees, and distance is realDistance rounded to a multiple of 100, so it is 0 for any nearby point; radius is compared with that rounded distance, so from a nearby point a radius of 1 or more keeps every vehicle with a position and a radius of 0 or less returns none; results are not ordered by nearness, and num keeps the first N results, not the N nearest, with no default cap; to find the nearest vehicles, compute distances yourself from vehicle.lat and vehicle.lng
• GET /v2/api/companies/{id}/alert-records — returns records for every company your token can read; {id} must be one of them but does not narrow the scope; only 10 alert types are returned; num applies per alert type and is required in practice (without it the list is empty), so set it to at least page × pageSize for the deepest page you read
• GET /v2/api/companies/{id}/alerts — alertType is the display name, e.g. Low Battery, not a numeric string; units and tags are the lists saved on the alert, not the monitored set: when isAllFleet is true the alert covers every vehicle of its company, whatever units lists; paused definitions are returned, and no field marks them
• PUT /v2/api/companies/{id}/set-all-alerts-read — takes no date range (startDate and endDate are ignored) and marks every record of the 10 alert-record types across your token’s companies; {id} must be one of them but does not narrow the scope; the read flag is shared with the Telemax Dashboard, so Dashboard users see the records as read too

• Vehicle IDs — a vehicle’s public and internal IDs can differ. The public ID is the {id} of every /v2/api/vehicles/{id} route and of /v2/api/replay/{id}, deviceId in position data, and vehicleId in device-ids, fleet last-time-online and alert configurations’ units[]; vehicleId in alert records and battery health, and VehicleId in webhook payloads, are internal IDs (see Vehicle ID)
• Position fields (vehicle list, last position, positions, fleet last positions, nearest) — on vehicle list, fleet last positions and nearest, utcTime is when the server last rebuilt the vehicle’s state, not the time of the position; fatigue is not the time since the last rest: it is always 00:00:00 on last position, and on vehicle list, fleet last positions and nearest the time since the ignition last changed state; ignitionTime is not cumulative; engineHours is always 0; voltage, and internalBatteryVoltage on positions, are the vehicle (12/24 V) battery, not the tracker’s; odometer comes from the vehicle’s configured source, CAN or GPS, when the device reports it, and otherwise from the device’s own source; isDoorLocked is documented again; true does not confirm a lock, because on connected-car (Compass) vehicles it is also true when the vehicle sends no lock data and on Flespi-connected vehicles it means the doors are closed; for Telemax trackers it is always null; timeElapsed is in milliseconds; engineEnabled and satelliteCoverage are now described per endpoint; the electric-vehicle fields batteryLevel, chargerPower, chargingEnergy and batteryRange are now documented (see PositionDto fields)
• GET /v2/api/vehicles/{id}/last-position — the empty 200 body is also returned when the vehicle has not yet completed an ignition-on or ignition-off period
• GET /v2/api/vehicles/{id}/positions — to is exclusive
• GET /v2/api/vehicles/info — also returns 404 when the vehicle has no VIN, and [] when its VIN has not been decoded
• GET /v2/api/vehicles/{id}/odometer — odometerValue is read live from Flespi, so it is always null for vehicles not on the Flespi data provider, and it can differ from odometer in position data
• GET /v2/api/vehicles/{id}/engine-codes — returns the codes newly reported in the latest engine-fault record, not the codes currently active; description is null when no AI analysis exists; detectedAt is in the API key’s time zone

• PUT /v2/api/vehicles/{id}/odometer — odometer defaults to 0, so omitting it sets the odometer to 0; a 200 does not confirm that the device received or applied the value; 409 may be returned when the odometer comes from the CAN bus

• PUT /v2/api/alerts/{id}/{date}/update-read-status — an omitted isRead marks the record unread; when no record matches, the response is 200 with no change, not 404; {date} is the record’s utcTime and must match the stored trigger time exactly, to the fraction of a second, so a record stored with fractional seconds cannot be addressed and the call returns 200 with no change

• GET /v2/api/replay/{id} — only completed ignition-on trips of at least 300 m that overlap the window are returned, and to is inclusive here; encoded and url cover only the first 400 points of a trip; startTimeUser and endTimeUser are formatted MM/dd/yyyy HH:mm:ss whatever the key’s date format; omitting from returns every trip up to to, omitting only to returns 422, and points are clipped to the window

• GET /v2/api/battery-health — now documents the response production returns: score, band, badges, badgeSummary, the component scores and last90DaysVoltage (oldest first), not voltageHistory, forecast, statuses or healthScore; band is Excellent, Good, Fair, Poor or Critical, not Critical, Warning or Healthy. It covers only the vehicles mapped to your token’s own company and scored on its latest scoring date; the values of filter, sortBy and badgeFilter are listed, and with any sort other than internal vehicle ID, items with equal values can repeat or be skipped between pages

• POST /v2/api/webhooks — an alert ID that is unknown, deleted or not in your companies returns 404, not 422; http URLs are accepted; a host that does not resolve, or resolves to a loopback, private or similar address, is refused. The secret is 64 uppercase hexadecimal characters, and its case matters because the signing key is that exact string
• GET /v2/api/webhooks/{id} — also returns webhooks of direct, non-cancelled sub-companies
• GET /v2/api/webhooks — lists every webhook that is not deleted, active or not, of your token’s companies (its own and its direct, non-cancelled sub-companies)
• PUT /v2/api/webhooks/{id} — as the body replaces the whole configuration, omitting isActive re-enables a disabled webhook, isGlobal defaults to false, and switching a webhook to global removes its links; also accepts webhooks of direct, non-cancelled sub-companies
• DELETE /v2/api/webhooks/{id} — deliveries stop within about 30 seconds, and deliveries already queued, including retries, still go out; also accepts webhooks of direct, non-cancelled sub-companies
• POST /v2/api/webhooks/{id}/link-alert — also accepts webhooks and alert configurations of direct, non-cancelled sub-companies; a global webhook cannot have links, and the call returns 422

• Alert monitoring, Vehicle diagnostics and Trip replay guides — sample code corrected: alert polling passes num and does not treat a record’s id as unique (it is the alert configuration’s ID), alert type names match the API, battery health is paged with pageNumber and matched to vehicles by imei, and maps draw from points because encoded holds at most 400
• Glossary — create V2 keys under Settings → API Keys V2; keys from Webhooks & Api Keys are V1 keys, which the V2 token endpoint rejects
• Quirks — units and formats corrected, e.g. fatigue is a .NET TimeSpan string, not ISO 8601, and trip distance is in km
• Request and response — a field with no value is written as null, never omitted; the webhook POST and PUT routes take a JSON body
• Introduction, Quickstart, Which endpoint and Environments — V2 has no location-update command; battery health returns scores, not predictions; the Quickstart examples use the camelCase keys the API returns (deviceId, lat, utcTime); POST /v2/api/vehicles/list takes up to 50 known vehicle IDs and is not a search; Environments links the V2 OpenAPI specification

• The API versioning section and the 2026-04-28 API V2 release entry — the section no longer says that every V2 response carries X-API-Version; that entry no longer lists endpoints that V2 does not have, its rate-limit and X-API-Version lines are corrected, and GET /v2/api/vehicles/{id}/odometer and PUT /v2/api/vehicles/{id}/odometer/source have their own 2026-06-01 entry

​

2026-10-05 — Documentation corrections

​

Corrected

• Rate limiting — limits apply per API key, not per token, and per endpoint, in four fixed windows (second, minute, hour and day), not sliding ones; the per-endpoint limits are corrected, and four single-vehicle endpoints have one tight limit, counted per API key across all vehicles: GET /v2/api/vehicles/{id}/last-position 60 per day, GET /v2/api/vehicles/{id}/positions 60 per hour, GET /v2/api/vehicles/info 60 per minute and GET /v2/api/vehicles/{id}/last-online 2 per second; every response that reaches an endpoint counts, including 403, 404, 409, 422 and 500; Retry-After is the length of the exhausted window (1, 60, 3600 or 86400 seconds), so wait that long rather than capping a backoff at 60 seconds; the token endpoint is not rate-limited; the X-RateLimit-* headers are live, not “not yet active” as the specification said (see Rate limiting)
• Errors — a resource that exists but is outside your token’s companies returns 404, not 403; 403 means the API key lacks the endpoint’s permission (INVALID_SCOPE) or the company is suspended, which has its own body (CompanySuspended); every model-binding failure returns the same 422 description; every docUrl now leads to a reference page; the error table on each endpoint page is corrected (see Errors)
• Pagination — lastResultIndex is the 1-based position of the last record on the page, not a zero-based index; pageSize is at most 100 on alert records and alert configurations; battery health takes pageNumber and pageSize (see Pagination)
• X-API-Version — always 2, not date-based; not sent on a 401 for a missing, invalid or expired bearer token, or on a 429 (see Response headers)

• POST /v2/api/authentication/token/api-key — the examples use a 43-character API key instead of a GUID, and show expires_in as an integer (86399)

• POST /v2/api/vehicles/list — vehicle IDs that are unknown or not in your companies are left out of the 200 response, without an error

• Webhook payloads — keys are delivered in PascalCase, e.g. AlertType, VehicleId and Position.Lat, not in camelCase (alertType, vehicleId) as previously shown; match key names exactly. Address, when not null, always has 9 keys, including PostalCode (not postcode); AlertType values include ExceedMaximumSpeed and LowBattery, not Speeding, and on global webhooks some values contain spaces and differ from the names GET …/alerts returns, e.g. Speed Limit for Above Speed Limit and Door Unlocked for Doors Unlocked; VehicleId is the internal vehicle ID. /webhooks.yaml now describes the payload that is actually sent (see Payload shape)
• Webhook delivery — deliveries start only once Telemax has enabled webhook alerts for the company that owns the linked alert configuration (for a global webhook, the company that owns the webhook); each event gets up to 3 attempts with a 5-second timeout, 2 then 5 seconds apart, not exponential backoff, and is dropped after the third failure; a 300, 301, 302 or 303 redirect is re-sent as a GET without the body, so register the final URL; X-Telemax-Delivery changes on every attempt, so it cannot identify a retry, and an event can occasionally arrive again as a new delivery: de-duplicate on a hash of the raw body; verify the signature with the secret exactly as returned, as UTF-8 text, not hex-decoded; global webhooks receive only the types listed under Supported alert types, and Charging, Exceed RPM, Exceed Engine Temperature and Driving after dark are not delivered (see Delivery retries)

​

Removed from the documentation

• POST /v2/api/authentication/token/user, POST /v2/api/vehicles/{id}/ignition, PUT /v2/api/vehicles/{id}/door-lock, GET /v2/api/safety-score/{id} and GET /v2/api/vehicles/{id}/dtc — documented, but not part of V2; they return 404 (PATH_NOT_FOUND). Ignition, door lock and safety score are V1 only; for engine codes use GET /v2/api/vehicles/{id}/engine-codes

​

2026-06-01 — Odometer endpoints

​

Added

• GET /v2/api/vehicles/{id}/odometer — new — the vehicle’s odometer source and reading

• PUT /v2/api/vehicles/{id}/odometer/source — new — set the odometer source to CAN or GPS

​

2026-04-28 — API V2 release

​

Added

• Rate limiting per API key and per endpoint; a request over a limit returns 429 with a Retry-After header — see Rate limiting for the windows and headers
• Exception middleware — all V2 errors return a standardised ApiError JSON body (type, code, description, requestId, docUrl)
• X-API-Version: 2 response header on V2 responses (not on a 401 for a missing, invalid or expired token, or on a 429)

• POST /v2/api/authentication/token/api-key — V2 API key login

• GET /v2/api/companies — paginated list of accessible companies
• GET /v2/api/companies/{id}/vehicles/last-position — paginated fleet-wide last positions
• GET /v2/api/companies/{id}/vehicles/nearest — nearest vehicles to a coordinate (paginated)
• GET /v2/api/companies/{id}/vehicles/last-time-online — paginated fleet last-seen timestamps
• GET /v2/api/companies/{id}/alert-records — paginated alert records
• GET /v2/api/companies/{id}/alerts — new — paginated alert configurations with string AlertType and linked vehicle/tag lists
• PUT /v2/api/companies/{id}/set-all-alerts-read — mark every alert record of the 10 types in Alert records as read across your token’s companies; {id} must be one of those companies but does not narrow the scope

• POST /v2/api/vehicles/list — paginated vehicle list
• GET /v2/api/vehicles/{id}/last-position — last known position for a vehicle
• GET /v2/api/vehicles/{id}/positions — paginated position history
• GET /v2/api/vehicles/info — new — look up vehicle metadata by IMEI, vehicle ID, or VIN
• GET /v2/api/vehicles/{id}/last-online — last-seen timestamp for a vehicle
• GET /v2/api/vehicles/{imei}/device-ids — IMEI → vehicle ID lookup
• GET /v2/api/vehicles/{id}/engine-codes — changed — paginated engine codes newly reported in the latest engine-fault record (V1 returns every code in the latest DTC report), with AI analysis where available, severity, and detection location

• PUT /v2/api/vehicles/{id}/odometer — update odometer
• PUT /v2/api/vehicles/{id}/name — rename vehicle

• PUT /v2/api/alerts/{id}/{date}/update-read-status — new — mark a single alert record as read or unread

• GET /v2/api/replay/{id} — paginated trip replay

• GET /v2/api/battery-health — paginated battery health scores

• POST /v2/api/webhooks — create a webhook; response includes the plaintext HMAC secret (returned once only)
• GET /v2/api/webhooks/{id} — get a webhook by ID
• GET /v2/api/webhooks — paginated list of the webhooks of your token’s companies
• PUT /v2/api/webhooks/{id} — replace a webhook’s configuration (URL, active state, global flag and linked alerts)
• DELETE /v2/api/webhooks/{id} — soft-delete a webhook
• POST /v2/api/webhooks/{id}/link-alert — link an alert configuration to a webhook

​

2026-04-28 — GetSafetyScore parameter updates

​

Changed

• POST /api/GetSafetyScore — vehicleId parameter renamed from id (breaking for clients using the old name)
• POST /api/GetSafetyScore — start and finish are now optional; omit both and supply intervalType to use a preset time window
• POST /api/GetSafetyScore — new intervalType parameter: 1 = instant range, 2 = relative to end of local day, 3 = three-day window, 4 = week window. Validate preset windows in staging before relying on them (see endpoint reference for the known date-arithmetic quirk)

​

2026-04-14 — v1 (Initial public documentation)

​

Added

• POST /api/Authentication/token/user — JWT via username + password
• POST /api/Authentication/token/api-key — JWT via API key

• POST /api/GetCompanies — list accessible companies
• POST /api/GetAllLastPositionData/{companyId} — fleet-wide last positions
• POST /api/GetNearestVehicles — nearest vehicles to a coordinate
• POST /api/devices — vehicle list for a company
• POST /api/GetAllLastTimeOnline — last-seen timestamps for all vehicles

• POST /api/GetLastPositionData — latest position for one vehicle
• POST /api/GetPositionData — historical positions for one vehicle
• POST /api/GetReplay — trip replay (UTC time context)
• POST /api/GetReplayUserTime — trip replay (user timezone context)
• GET /api/GetDeviceId — IMEI → vehicle ID lookup

• POST /api/GetAlerts — list alerts for a company
• POST /api/SetAlertAsRead — mark one alert as read
• POST /api/SetAllAlertAsRead — mark all company alerts as read

• POST /api/GetCompanyVehiclesBatteryHealth — paged battery predictions
• POST /api/GetSafetyScore — trip safety score for a vehicle
• GET /api/devices/{id}/dtc-codes — latest DTC codes from vehicle handler state

• POST /api/ChangeOdometer — update odometer value
• POST /api/SetVehicleName — rename a vehicle
• POST /api/UpdateLocation — trigger device location update
• POST /api/SendIgnition — send ignition enable/disable command
• POST /api/LastTimeOnline — last-seen timestamp for one vehicle
• POST /api/SendDoorLock — send door lock command (ATrack SMS path)

• POST /api/Test — anonymous connectivity health check

​

Deprecated

• POST /api/rebuild-vehicle-movement-cache — removed from public API reference (internal dev/ops only; not for integration partners).