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

# List vehicles

> Returns last-known positions for a specific set of 1–50 vehicles.

### Overview

Returns last-known positions for a specific set of vehicles. The request body is required and must contain between 1 and 50 `deviceId` values — this limit prevents the endpoint from being used to scrape the entire fleet.

<Note>The V1 version of this endpoint is [Device positions](/v1/api-reference/post-devices). V2 is paginated.</Note>

<Note>**Rate limit:** 10 req/s · 30/min · 6,000/hr · 144,000/day</Note>

### Endpoint

`POST /v2/api/vehicles/list`

### Query parameters

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="pageSize" type="integer" default="50">
  Records per page.
</ParamField>

### Request body

```json theme={null}
{
  "vehicleIds": [88421, 88422]
}
```

| Field      | Type       | Required | Description                                                                                             |
| ---------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------- |
| vehicleIds | integer\[] | **Yes**  | `deviceId` values to query. Must contain between 1 and 50 entries. Returns **422** if empty or omitted. |

### Response

**200 OK** — `PagedListResult<PositionDto>`

Each item in `items` is a full `PositionDto`. All fields below are present on every item.

**Record & timestamps**

| Field             | Type     | Description                                           |
| ----------------- | -------- | ----------------------------------------------------- |
| utcTime           | datetime | Record timestamp (UTC, no fractional seconds)         |
| userTime          | datetime | Record timestamp in the user's timezone               |
| userTimeFormatted | string   | Record timestamp formatted per the user's date format |

**Location**

| Field  | Type    | Description                                            |
| ------ | ------- | ------------------------------------------------------ |
| lat    | number  | Latitude                                               |
| lng    | number  | Longitude                                              |
| speed  | number  | Speed (km/h)                                           |
| course | integer | Compass direction in degrees (N=0, E=90, S=180, W=270) |

**Engine & power**

| Field       | Type           | Description                                                       |
| ----------- | -------------- | ----------------------------------------------------------------- |
| ignition    | boolean        | Ignition state                                                    |
| odometer    | number \| null | GPS odometer (km)                                                 |
| voltage     | number \| null | Internal battery voltage (V)                                      |
| fatigue     | string         | .NET `TimeSpan` string — time since last rest (e.g. `"03:05:00"`) |
| engineHours | number         | Cumulative engine hours                                           |

**Signal**

| Field                     | Type            | Description                                                       |
| ------------------------- | --------------- | ----------------------------------------------------------------- |
| satelliteCoverage         | string          | Satellite signal status label (e.g. `"Wifi-Cell"`, `"GPS"`)       |
| satelliteCoverageRawValue | integer \| null | Raw satellite signal integer value                                |
| networkCoverage           | string          | Cellular network coverage label (e.g. `"No network information"`) |
| networkCoverageRawValue   | integer \| null | Raw network coverage integer value                                |

**Device & identity**

| Field        | Type           | Description                           |
| ------------ | -------------- | ------------------------------------- |
| deviceId     | integer        | Vehicle ID                            |
| ignitionTime | number \| null | Cumulative ignition-on time (seconds) |
| deviceName   | string         | Vehicle display name                  |
| imei         | string         | Device IMEI                           |
| vin          | string \| null | Vehicle Identification Number         |

**Movement history**

| Field                         | Type             | Description                                     |
| ----------------------------- | ---------------- | ----------------------------------------------- |
| startMovingTime               | datetime \| null | When the vehicle started moving (UTC)           |
| startMovingTimeUser           | datetime \| null | When the vehicle started moving (user timezone) |
| lastMovementTime              | datetime \| null | When the vehicle last stopped (UTC)             |
| lastMovementTimeUser          | datetime \| null | When the vehicle last stopped (user timezone)   |
| lastMovementTimeUserFormatted | string \| null   | Last movement time formatted                    |

**Trip & driver**

| Field       | Type            | Description                                |
| ----------- | --------------- | ------------------------------------------ |
| drivingTime | integer \| null | Driving time within current trip (seconds) |

**Fuel**

| Field      | Type            | Description          |
| ---------- | --------------- | -------------------- |
| fuelLevel  | integer \| null | Fuel level (%)       |
| fuelVolume | number \| null  | Fuel volume (litres) |

**Vehicle state**

| Field         | Type    | Description                      |
| ------------- | ------- | -------------------------------- |
| address       | string  | Reverse-geocoded street address  |
| engineEnabled | boolean | Whether engine output is enabled |

**Connectivity**

| Field    | Type    | Description                            |
| -------- | ------- | -------------------------------------- |
| isOnline | boolean | Whether the device is currently online |

**Request metadata**

| Field       | Type     | Description                               |
| ----------- | -------- | ----------------------------------------- |
| timeElapsed | number   | Request processing time elapsed (seconds) |
| startedTime | datetime | Request processing start timestamp        |
| endTime     | datetime | Request processing end timestamp          |

### Error responses

| Status | Meaning                                                                          |
| ------ | -------------------------------------------------------------------------------- |
| 401    | Missing or invalid token                                                         |
| 403    | Token scope does not include access to any company vehicles                      |
| 422    | Request body is missing, `vehicleIds` is empty, or contains more than 50 entries |

```bash theme={null}
curl -X POST "https://api.telemax.com.au/v2/api/vehicles/list?page=1&pageSize=50" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"vehicleIds": [88421, 88422]}'
```


## OpenAPI

````yaml openapi.yaml POST /v2/api/vehicles/list
openapi: 3.1.0
info:
  title: Telemax External API (V2)
  version: '2026-04-14'
  description: >
    Telemax External API — fleet telemetry, vehicle commands, and integrations.


    **Base URL:** `https://api.telemax.com.au`


    **Authentication:** All routes require a `Bearer` JWT unless marked
    `[AllowAnonymous]`.

    Obtain tokens via `POST /v2/api/authentication/token/api-key`.


    **RESTful architecture:** V2 uses standard HTTP methods (GET, POST, PUT,
    DELETE) with

    resource-based routes and consistent pagination via `page` and `pageSize`
    query parameters.


    **API versioning:** All responses will include an `X-API-Version` header
    containing the

    date-based version string (e.g. `2026-04-28`). See the
    [Changelog](/v2/changelog) for

    the deprecation policy and version history.


    For full documentation including error handling, pagination, and known field
    quirks, see [docs.telemax.com.au](https://docs.telemax.com.au).
servers:
  - url: https://api.telemax.com.au
security:
  - BearerAuth: []
paths:
  /v2/api/vehicles/list:
    post:
      summary: List vehicles (V2)
      description: >
        Returns the last known position for a specific set of vehicles.


        **Important — two ID fields per item:** Each item contains `id` (a
        position record ID, a large integer) and `deviceId` (the actual
        vehicle/device ID). Always use `deviceId` when calling individual
        vehicle endpoints such as `GET /v2/api/vehicles/{id}/last-position`.

        **`vehicleIds` is required** and must contain between 1 and 50
        `deviceId` values. Passing an empty array or omitting the field returns
        **422**.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 50
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vehicleIds
              properties:
                vehicleIds:
                  type: array
                  items:
                    type: integer
                  minItems: 1
                  maxItems: 50
                  description: >-
                    List of `deviceId` values to query. Must contain between 1
                    and 50 entries. Returns **422** if empty or omitted.
            example:
              vehicleIds:
                - 88421
                - 88422
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                items:
                  - utcTime: '2026-04-28T06:14:22'
                    userTime: '2026-04-28T16:14:22'
                    userTimeFormatted: 28/04/2026 04:14 PM
                    lat: -33.8688
                    lng: 151.2093
                    speed: 0
                    course: 142
                    ignition: false
                    odometer: 45321.2
                    voltage: 12.8
                    fatigue: '00:00:00'
                    engineHours: 1842.5
                    satelliteCoverage: Excellent
                    satelliteCoverageRawValue: 12
                    networkCoverage: Excellent
                    networkCoverageRawValue: 18
                    deviceId: 88421
                    ignitionTime: null
                    deviceName: Delivery Van 07
                    imei: '353148090123456'
                    vin: 1HGBH41JXMN109186
                    startMovingTime: null
                    startMovingTimeUser: null
                    lastMovementTime: '2026-04-28T05:50:00'
                    lastMovementTimeUser: '2026-04-28T15:50:00'
                    lastMovementTimeUserFormatted: 28/04/2026 03:50 PM
                    drivingTime: null
                    fuelLevel: null
                    fuelVolume: null
                    address: 42 George St, Sydney NSW 2000
                    engineEnabled: true
                    timeElapsed: 245.12
                    startedTime: '2026-04-28T06:14:22'
                    endTime: '2026-04-28T06:14:22'
                    isOnline: false
                totalResults: 1
                lastResultIndex: 1
                currentPage: 1
                numberOfPages: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: >-
            **422 Unprocessable Entity** — `vehicleIds` is empty, contains more
            than 50 entries, or `page` is less than 1.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                emptyVehicleIds:
                  summary: vehicleIds must have at least 1 entry
                  value:
                    type: VALIDATION_ERROR
                    code: INVALID_INPUT
                    description: VehicleIds must contain at least 1 entry.
                    requestId: 0HNLTALNU4DCU:00000001
                    docUrl: https://docs.telemax.com.au/errors/invalid-input
                tooManyVehicleIds:
                  summary: vehicleIds must not exceed 50
                  value:
                    type: VALIDATION_ERROR
                    code: INVALID_INPUT
                    description: VehicleIds must not contain more than 50 entries.
                    requestId: 0HNLTALNU4DCU:00000002
                    docUrl: https://docs.telemax.com.au/errors/invalid-input
                invalidPage:
                  summary: Page must be 1 or greater
                  value:
                    type: VALIDATION_ERROR
                    code: INVALID_INPUT
                    description: page must be 1 or greater.
                    requestId: 0HNLTALNU4DCU:00000003
                    docUrl: https://docs.telemax.com.au/errors/invalid-input
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: >
        **401 Unauthorized** — JWT is missing, expired, or malformed.

        The JWT bearer middleware rejects the request before it reaches the
        controller.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: AUTHENTICATION
            code: INVALID_CREDENTIALS
            description: The provided API key is invalid or does not exist.
            requestId: 0HNLTALNU4DCO:00000004
            docUrl: https://docs.telemax.com.au/errors/invalid-credentials
    TooManyRequests:
      description: >
        **429 Too Many Requests** — Rate limit exceeded. Check the Retry-After
        header for the number of seconds to wait before retrying.

        Use exponential backoff: wait Retry-After seconds, then double the
        interval on each subsequent 429.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: RATE_LIMIT
            code: RATE_LIMIT_EXCEEDED
            description: Too many requests. Please slow down.
            requestId: req_6d2f8b4a
            docUrl: https://docs.telemax.com.au/errors/rate-limit-exceeded
    InternalServerError:
      description: >
        **500 Internal Server Error** — An unexpected error occurred. Include
        the requestId when contacting support.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: SERVER_ERROR
            code: INTERNAL_SERVER_ERROR
            description: An unexpected error occurred. Please try again later.
            requestId: req_1e5a3c7d
            docUrl: https://docs.telemax.com.au/errors/internal-server-error
  schemas:
    ApiError:
      type: object
      description: Standard error response returned by all API endpoints.
      properties:
        type:
          type: string
          description: >-
            Error category (e.g. AUTHENTICATION, AUTHORIZATION, RESOURCE,
            VALIDATION_ERROR, RATE_LIMIT, SERVER_ERROR).
          example: AUTHENTICATION
        code:
          type: string
          description: Machine-readable error code within the category.
          example: INVALID_CREDENTIALS
        description:
          type: string
          description: Human-readable explanation of the error and how to resolve it.
          example: The provided API key is invalid or does not exist.
        requestId:
          type: string
          description: Unique request identifier for support correlation.
          example: req_7f3a2b1c
        docUrl:
          type: string
          format: uri
          description: Link to the relevant error documentation page.
          example: https://docs.telemax.com.au/errors/invalid-credentials
      required:
        - type
        - code
        - description
  headers:
    X-RateLimit-Limit:
      description: >-
        Maximum number of requests allowed per minute for this token. **Not yet
        active** — this header will be added once the rate-limit middleware is
        deployed. See the [Changelog](/v2/changelog) for the rollout date.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: >-
        Number of requests remaining in the current rate limit window. **Not yet
        active** — see `X-RateLimit-Limit`.
      schema:
        type: integer
        example: 47
    X-RateLimit-Reset:
      description: >-
        Unix timestamp (seconds) at which the current rate limit window resets.
        **Not yet active** — see `X-RateLimit-Limit`.
      schema:
        type: integer
        example: 1746000060
    Retry-After:
      description: Number of seconds to wait before retrying after a 429 response.
      schema:
        type: integer
        example: 30
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT Bearer token obtained from `POST
        /v2/api/authentication/token/api-key`.


        **Lifetime:** ~24 hours (86,399 seconds). Cache the token and reuse it.
        Re-authenticate 5 minutes before expiry.


        **Scoping:** API key tokens are scoped to the company the key belongs to
        and may restrict

        access to a vehicle allowlist and/or action set (see token claims).


        **No refresh endpoint** — re-authenticate with your API key when the
        token expires.

````