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

# Quickstart

> Obtain a JWT and make your first V2 API calls in minutes.

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

<Note>
  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.
</Note>

## Step 1 — Get an access token

V2 token endpoints are at `/v2/api/authentication/token/...`. Interactive reference: [API key token](/v2/api-reference/post-authentication-token-api-key).

<CodeGroup>
  ```bash cURL theme={null}
  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=a3f1c2b4-5d6e-7890-abcd-ef1234567890"
  ```

  ```javascript JavaScript theme={null}
  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: "a3f1c2b4-5d6e-7890-abcd-ef1234567890",
      }),
    },
  );
  const { access_token, expires_in } = await r.json();
  ```

  ```python Python theme={null}
  import requests
  r = requests.post(
      'https://api.telemax.com.au/v2/api/authentication/token/api-key',
      data={'apiKey': 'a3f1c2b4-5d6e-7890-abcd-ef1234567890'},
  )
  r.raise_for_status()
  token = r.json()['access_token']
  ```
</CodeGroup>

**200 OK** response shape:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86399
}
```

Cache this token and reuse it. Tokens are valid for \~24 hours — see [Authentication](/v2/authentication#token-caching-strategy) for the recommended caching pattern.

***

## Step 2 — List your companies

Use [`GET /v2/api/companies`](/v2/api-reference/get-companies) to discover the company IDs your token can access. The `Id` on the first result is your primary company ID — you'll need it for fleet and alert endpoints.

```bash theme={null}
curl -s "https://api.telemax.com.au/v2/api/companies" \
  -H "Authorization: Bearer <access_token>"
```

**200 OK** — paginated list of companies:

```json theme={null}
{
  "items": [
    { "Id": 85, "Name": "Acme Fleet", "ParentId": null }
  ],
  "currentPage": 1,
  "numberOfPages": 1,
  "totalResults": 1,
  "lastResultIndex": 0
}
```

***

## Step 3 — Get your fleet's last positions

Use [`GET /v2/api/companies/{id}/vehicles/last-position`](/v2/api-reference/get-companies-id-vehicles-last-position) with the company ID from Step 2 to fetch the current location of every vehicle.

```bash theme={null}
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`](/v2/api-reference/get-vehicles-id-last-position) for a specific vehicle by its vehicle ID (`DeviceId`):

```bash theme={null}
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`](/v2/api-reference/get-vehicles-imei-device-ids).

***

## Common first errors

| Symptom                   | Cause                                     | Fix                                                                            |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
| `401` with no body        | Missing or invalid `Authorization` header | Obtain a fresh token; prefix with `Bearer `                                    |
| `401` from token endpoint | Wrong or unknown API key                  | Verify credentials; key must exist in the Telemax dashboard and not be deleted |
| `403` on a data route     | Token not scoped to that company          | Check `GET /v2/api/companies` for accessible company IDs                       |
| `404` on a vehicle route  | Vehicle ID unknown or not in your company | Use `POST /v2/api/vehicles/list` to confirm the vehicle exists                 |
| `429 Too Many Requests`   | Rate limit exceeded                       | Wait the `Retry-After` header value before retrying                            |
| Empty `access_token`      | Parsing error                             | Ensure `Content-Type` is `application/x-www-form-urlencoded`, not JSON         |

See [Error handling](/v2/errors) for the full list of error codes and retry guidance.