> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemax.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossary

> Plain-English definitions for terms used throughout the Telemax API documentation.

## AlertType integers

The `AlertType` field returned by `POST /api/GetAlerts` is an **integer discriminator**. The mapping to alert category is:

| Integer | Alert label               |
| ------- | ------------------------- |
| `1`     | Device Disconnected       |
| `2`     | Device Reconnected        |
| `3`     | Engine Code (DTC)         |
| `4`     | Fatigue                   |
| `5`     | Geofence                  |
| `6`     | Geofence Speed            |
| `7`     | Idle                      |
| `8`     | Ignition                  |
| `9`     | Low Battery               |
| `10`    | Exceed Maximum Speed      |
| `11`    | Mileage                   |
| `12`    | Above Speed Limit         |
| `13`    | Doors Unlocked            |
| `14`    | Tire Pressure             |
| `15`    | Charging                  |
| `16`    | Exceed RPM                |
| `17`    | Exceed Engine Temperature |
| `18`    | Reminder                  |

<Note>
  V2's `GET /api/v2/companies/{id}/alerts` returns the human-readable string label (e.g. `"Speeding"`) instead of an integer, so this mapping is only needed for V1 callers.
</Note>

***

## 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 long string (GUID format) 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 **Webhooks and API Key**. 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 or credentials.

***

## Company ID (`compId`)

An integer that identifies a company (or sub-company) in the Telemax hierarchy. Most endpoints require one. Retrieve yours by calling `POST /api/GetCompanies` — the `Id` on the first result is your primary company ID.

***

## DTC code

**Diagnostic Trouble Code.** 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). The Telemax API returns raw codes via `GET /api/devices/{id}/dtc-codes` — you will need an external DTC reference to look up their meaning, as `description` and `severity` fields are currently empty in the backend.

***

## IMEI

**International Mobile Equipment Identity.** A 15-digit number that uniquely identifies the GPS tracking device fitted to a vehicle. Use `GET /api/GetDeviceId/{imei}` to convert an IMEI to the internal vehicle ID that most other endpoints expect.

***

## Legacy vehicle ID

The integer vehicle identifier used by most Telemax API endpoints. It appears as `DeviceId` in position data, `vehicleId` in battery health, and as the `{id}` path parameter in device endpoints. All three refer to the same value. Retrieve a list of vehicle IDs via `POST /api/devices`.

***

## Pagination

When a response contains too many results to return at once, the API splits them into pages. The battery health endpoint uses pagination — pass `pageNumber` (default `1`) and `resultsPerPage` (default `25`) as query parameters, and the response tells you `numberOfPages` so you know how many pages to request.

***

## 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. 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: `?compId=85&from=2025-05-01T00:00:00Z&num=50`. Almost all Telemax API endpoints pass their parameters this way, even on `POST` requests — there is no JSON request body unless explicitly documented.

***

## UTC

**Coordinated Universal Time.** The global time standard used by all timestamps in the Telemax API. Convert to local time using the offset for your region:

| Timezone                                | Offset |
| --------------------------------------- | ------ |
| AEST (Australian Eastern Standard Time) | UTC+10 |
| AEDT (Australian Eastern Daylight Time) | UTC+11 |

`UtcTime` fields in Telemax responses are always UTC but do **not** include a `Z` suffix — treat them as UTC when parsing.

***

## 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.

| Code  | Meaning                                                  |
| ----- | -------------------------------------------------------- |
| `200` | Success                                                  |
| `400` | Bad request — check your parameters                      |
| `401` | Unauthorized — token missing, expired, or wrong          |
| `403` | Forbidden — authenticated but not allowed                |
| `404` | Not found — vehicle ID or resource doesn't exist         |
| `429` | Too many requests — slow down                            |
| `500` | Server error — try again; contact Telemax if it persists |