Skip to main content

​
API

Application Programming Interface. A defined way for two software systems to communicate. The Telemax API lets your software request fleet data directly from Telemax servers using standard HTTPS requests.

​
API key

A 43-character string that identifies your integration to the Telemax system — similar to a password, but intended for automated systems rather than humans. Generate one from the Telemax dashboard under Settings → API Keys V2. Keys from Webhooks & Api Keys are V1 keys, which the V2 token endpoint rejects. Store it securely and never commit it to source control.

​
Bearer token / access token / JWT

A temporary credential returned when you authenticate. You include it in every API request using the Authorization: Bearer <token> header.
  • JWT (JSON Web Token) — the format of the token. It encodes your company ID, timezone, and permissions as a signed JSON payload.
  • Bearer token — the HTTP authentication scheme used to send it.
  • Tokens expire after approximately 24 hours. Request a new one using your API key.

​
Company ID

An integer that identifies a company (or sub-company) in the Telemax hierarchy. Most endpoints require one. Call GET /v2/api/companies: your own company is the item with level 0. It is listed last, after its sub-companies, so when there are more companies than pageSize it is on the last page. Which of the listed companies other endpoints accept is described under Token scoping.

​
Engine code

Diagnostic Trouble Code (DTC). A standardised fault code read from a vehicle’s OBD-II or CAN bus. Codes follow the SAE J1979 / ISO 15031-6 standard (e.g. P0300 = random misfire). GET /v2/api/vehicles/{id}/engine-codes returns the codes first reported in the vehicle’s latest engine-fault record, with the detection location and, where an analysis exists, an AI-generated description, possible causes, recommended actions and severity.

​
IMEI

International Mobile Equipment Identity. A 15-digit number that identifies the GPS tracking device fitted to a vehicle. Use GET /v2/api/vehicles/{imei}/device-ids to look up the public vehicle ID for an IMEI. More than one vehicle record can carry the same IMEI (for example after a tracker moved between data providers); the lookup then returns one of them, or 404.

​
Vehicle ID

A vehicle has two integer IDs, and V2 fields use one or the other:
  • The public vehicle ID is the {id} of every /v2/api/vehicles/{id} route, of /v2/api/replay/{id} and of vehicles/info?id=, and the values in the vehicles/list body. It appears as deviceId in position data, and as vehicleId in device-ids, fleet last-time-online and alert configurations’ units[]. A vehicle with no public ID shows -1 as deviceId and null in units[].
  • The internal vehicle ID appears as vehicleId in alert records and battery health, and as VehicleId in webhook payloads.
The two can differ for the same vehicle, so never pass an internal ID as a route {id}. To match battery health rows to position data, use imei when both are non-null. To list a company’s vehicles, use fleet last positions.

​
Pagination

When a response contains too many results to return at once, the API splits them into pages. Paginated endpoints take page (default 1) and pageSize (default 50) as query parameters and return currentPage, numberOfPages and totalResults; see Pagination. Battery health is the exception: it takes pageNumber (default 1) and pageSize (default 25), and returns totalCount, page and pageSize.

​
Polyline (encoded)

A compact string representation of a GPS route, using the Google Polyline Algorithm. The encoded field on TripDto (trip replay) uses this format and covers only the first 400 entries of the trip’s points. Decode it with the polyline library (Python) or @mapbox/polyline (JavaScript/Node) to get an array of [lat, lng] coordinates.

​
Query parameter

Data passed in a URL after the ? character, in key=value pairs separated by &. Example: ?from=2025-05-01T00:00:00Z&num=50. Most V2 endpoints take their parameters in the path or query string. The token endpoint takes a form body, and POST /v2/api/vehicles/list and the webhook POST/PUT routes take a JSON body; see Content types.

​
UTC

Coordinated Universal Time. The time standard for the utcTime-style timestamps in the Telemax API. Convert to local time using the offset for your region: utcTime fields in Telemax responses are UTC but do not include a Z suffix — treat them as UTC when parsing. Fields such as userTime and engine-code detectedAt are in the API key’s time zone instead.

​
Telemetry

Data automatically transmitted from a vehicle’s GPS tracker to the Telemax platform. Includes position (lat/lng), speed, ignition state, odometer, voltage, and fuel level, reported approximately every 30 seconds when the vehicle is active.

​
HTTP status codes

The three-digit code in every API response indicating whether the request succeeded.