Quickstart

Prerequisites — Create an API Key

Before making any API calls, you’ll need an API key. Head to the Telemax API Keys V2 section in the Telemax dashboard to create your own key.

Navigate to Telemax Dashboard → API Keys V2 to generate a new API key. Copy the key and keep it secure — you’ll use it in the step below.

Step 1 — Get an access token

The V2 token endpoint is POST /v2/api/authentication/token/api-key. Interactive reference: API key token.

curl -s -X POST "https://api.telemax.com.au/v2/api/authentication/token/api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "apiKey=EXAMPLE-api-key-do-not-use-0123456789abcdEF"

const r = await fetch(
  "https://api.telemax.com.au/v2/api/authentication/token/api-key",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      apiKey: "EXAMPLE-api-key-do-not-use-0123456789abcdEF",
    }),
  },
);
const { access_token, expires_in } = await r.json();

import requests
r = requests.post(
    'https://api.telemax.com.au/v2/api/authentication/token/api-key',
    data={'apiKey': 'EXAMPLE-api-key-do-not-use-0123456789abcdEF'},
)
r.raise_for_status()
token = r.json()['access_token']

200 OK response shape:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86399
}

Cache this token and reuse it. Tokens are valid for ~24 hours — see Authentication for the recommended caching pattern.

Step 2 — List your companies

Use GET /v2/api/companies to list your company and its sub-companies. Your own company is the item with level 0; it is listed last, after its sub-companies (on the last page when there are more companies than pageSize). You’ll need its id for fleet and alert endpoints. Not every listed company can be used with other endpoints — see Token scoping.

curl -s "https://api.telemax.com.au/v2/api/companies" \
  -H "Authorization: Bearer <access_token>"

200 OK — paginated list of companies (abridged; List companies shows every field):

{
  "items": [
    { "id": 86, "name": "Acme Fleet North", "parentId": 85, "level": 1 },
    { "id": 85, "name": "Acme Fleet", "parentId": null, "level": 0 }
  ],
  "currentPage": 1,
  "numberOfPages": 1,
  "totalResults": 2,
  "lastResultIndex": 2,
  "dateTimeFormat": "dd/MM/yyyy",
  "timezone": "Australia/Brisbane",
  "utcOffset": "10:00:00"
}

Step 3 — Get your fleet’s last positions

Use GET /v2/api/companies/{id}/vehicles/last-position with the company ID from Step 2 to fetch the current location of every vehicle mapped to that company. Sub-company vehicles are not included unless they are also mapped to it: to cover them, repeat the call for each company with level 1 in the Step 2 response (deeper levels return 404), and de-duplicate by deviceId, falling back to imei when deviceId is -1.

curl -s "https://api.telemax.com.au/v2/api/companies/85/vehicles/last-position?page=1&pageSize=50" \
  -H "Authorization: Bearer <access_token>"

200 OK — paginated PositionDto list with fields including deviceId, deviceName, lat, lng, utcTime, speed, ignition.

Step 4 — Fetch a single vehicle’s last position

Use GET /v2/api/vehicles/{id}/last-position for a specific vehicle by its public vehicle ID (deviceId):

curl -s "https://api.telemax.com.au/v2/api/vehicles/88421/last-position" \
  -H "Authorization: Bearer <access_token>"

If you only have an IMEI, convert it first with GET /v2/api/vehicles/{imei}/device-ids.

Common first errors

Symptom	Cause	Fix
`401` on a data route	Missing, invalid or expired bearer token (the JSON body has `code: INVALID_CREDENTIALS`)	Obtain a fresh token; send it as `Authorization: Bearer <token>`
`401` from token endpoint	Wrong or unknown API key	Verify the key; it must exist under API Keys V2 in the Telemax dashboard and not be deleted
`403` on a data route	The API key lacks this endpoint’s permission (`INVALID_SCOPE`), or the company is suspended	Check the key’s permissions in the dashboard; see 403 Forbidden
`404` on a data route	The ID is unknown or not in your companies	Check the ID: use company IDs with `level` `0` or `1` from `GET /v2/api/companies` (see Token scoping); a vehicle’s public ID can be looked up by IMEI with `GET /v2/api/vehicles/{imei}/device-ids`
`422` from token endpoint	The body was sent as JSON, or `apiKey` is missing	Send `apiKey` as `application/x-www-form-urlencoded`
`429 Too Many Requests`	Rate limit exceeded	Wait the `Retry-After` header value (the length of the exhausted window) before retrying

See Error handling for the full list of error codes and retry guidance.

Getting Started

Guides

Authentication

Companies & fleet

Vehicles

Vehicle commands

Alerts

Telemetry & replay

Insights & diagnostics

Webhooks

Reference

Prerequisites — Create an API Key

Step 1 — Get an access token

Step 2 — List your companies

Step 3 — Get your fleet’s last positions

Step 4 — Fetch a single vehicle’s last position

Common first errors

​Prerequisites — Create an API Key

​Step 1 — Get an access token

​Step 2 — List your companies

​Step 3 — Get your fleet’s last positions

​Step 4 — Fetch a single vehicle’s last position

​Common first errors

Prerequisites — Create an API Key

Step 1 — Get an access token

Step 2 — List your companies

Step 3 — Get your fleet’s last positions

Step 4 — Fetch a single vehicle’s last position

Common first errors