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

# Battery health

> Paged battery prediction rows for vehicles in the JWT company.

### Overview

Returns **paged** battery prediction rows for vehicles in the JWT company, with optional search string.

<Note>
  A V2 version of this endpoint is available: [Battery health](/v2/api-reference/get-battery-health). New integrations should prefer V2.
</Note>

### Endpoint

`POST /api/GetCompanyVehiclesBatteryHealth`

### Query parameters

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

<ParamField query="searchString" type="string">
  Filter string; whitespace becomes empty search.
</ParamField>

<ParamField query="resultsPerPage" type="integer">
  Page size (default `25`).
</ParamField>

### Response

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

| Field           | Type    | Description                            |
| --------------- | ------- | -------------------------------------- |
| items           | array   | `VehicleBatteryPredictionItem` entries |
| totalResults    | integer | Total rows                             |
| lastResultIndex | integer | End index                              |
| currentPage     | integer | Current page                           |
| numberOfPages   | integer | Page count                             |

Each item:

| Field             | Type           | Description                                                                      |
| ----------------- | -------------- | -------------------------------------------------------------------------------- |
| vehicleId         | integer        | **Legacy** vehicle id                                                            |
| vehicleName       | string         | Display name                                                                     |
| currentVoltage    | number \| null | Observed voltage                                                                 |
| predictionResults | array          | `BatteryPredictionValue` label, `PredictionConfidence` label, `predictionForDay` |

### Error responses

| Status | Meaning               |
| ------ | --------------------- |
| 401    | Missing company claim |


## OpenAPI

````yaml openapi.yaml POST /api/GetCompanyVehiclesBatteryHealth
openapi: 3.1.0
info:
  title: Telemax External API (V1)
  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 `/api/Authentication/token/api-key` or
    `/api/Authentication/token/user`.


    **POST-first architecture:** Almost all data endpoints use `POST` with
    query-string parameters.

    The two exceptions using `GET` are `GetDeviceId` and `GET
    /api/devices/{id}/dtc-codes`.


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

    date-based version string (e.g. `2026-04-14`). See the
    [Changelog](/v1/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:
  /api/GetCompanyVehiclesBatteryHealth:
    parameters: []
    post:
      summary: Get Battery Health
      description: >
        Get battery health information for the vehicles within the specified
        company. Returns a paged list of vehicles with their current voltage and
        prediction results using the **legacy prediction model**
        (`batteryPredictionValue`: `Healthy`, `Check`, or `Failing`). A newer
        AI-based battery prediction endpoint with richer fields (`HealthScore`,
        `RulDays`, `Diagnosis`, `RiskCategory`, `IsEngineStarted`, and
        multi-window voltage history) is in development and will be documented
        here when exposed to the external API.
      parameters:
        - name: pageNumber
          in: query
          required: false
          description: Page number
          example: 1
          schema:
            type: integer
        - name: searchString
          in: query
          required: false
          description: Search string - used to search for vehicle names, IMEI
          example: Ford
          schema:
            type: string
        - name: resultsPerPage
          in: query
          required: false
          description: Number of results per page
          example: 25
          schema:
            type: integer
        - name: Content-Type
          in: header
          required: false
          description: Standard and must keep as it is.
          example: application/x-www-form-urlencoded
          schema:
            type: string
        - name: Authorization
          in: header
          required: true
          description: Bearer your_token
          example: Bearer {token}
          schema:
            type: string
      responses:
        '200':
          description: Successful response with paged battery prediction data
          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:
                allOf:
                  - $ref: '#/components/schemas/PaginationMeta'
                  - type: object
                    properties:
                      items:
                        type: array
                        description: List of vehicle battery prediction items.
                        items:
                          $ref: '#/components/schemas/VehicleBatteryPredictionItem'
              example:
                items:
                  - vehicleId: 1234
                    vehicleName: Fleet Vehicle 001
                    currentVoltage: 12.6
                    predictionResults:
                      - batteryPredictionValue: Healthy
                        predictionConfidence: High
                        predictionForDay: 1
                      - batteryPredictionValue: Check
                        predictionConfidence: Medium
                        predictionForDay: 3
                  - vehicleId: 5678
                    vehicleName: Fleet Vehicle 002
                    currentVoltage: 11.9
                    predictionResults:
                      - batteryPredictionValue: Failing
                        predictionConfidence: High
                        predictionForDay: 2
                totalResults: 20
                lastResultIndex: 9
                currentPage: 1
                numberOfPages: 2
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  headers:
    X-RateLimit-Limit:
      description: Maximum number of requests allowed per minute for this token.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: Number of requests remaining in the current rate limit window.
      schema:
        type: integer
        example: 47
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) at which the current rate limit window resets.
      schema:
        type: integer
        example: 1746000060
    Retry-After:
      description: Number of seconds to wait before retrying after a 429 response.
      schema:
        type: integer
        example: 30
  schemas:
    PaginationMeta:
      type: object
      description: Pagination metadata returned by list endpoints that support paging.
      properties:
        currentPage:
          type: integer
          description: The current page number (1-based).
          example: 1
        numberOfPages:
          type: integer
          description: Total number of pages.
          example: 7
        totalResults:
          type: integer
          description: Total number of records across all pages.
          example: 342
        lastResultIndex:
          type: integer
          description: Zero-based index of the last record on the current page.
          example: 24
      required:
        - currentPage
        - numberOfPages
        - totalResults
        - lastResultIndex
    VehicleBatteryPredictionItem:
      type: object
      properties:
        vehicleId:
          type: integer
          description: Vehicle ID.
          example: 1234
        vehicleName:
          type: string
          description: Name of the vehicle.
          example: Fleet Vehicle 001
        currentVoltage:
          type: number
          format: float
          nullable: true
          description: Current battery voltage.
          example: 12.6
        predictionResults:
          type: array
          description: List of prediction results.
          items:
            $ref: '#/components/schemas/PredictionResult'
    PredictionResult:
      type: object
      properties:
        batteryPredictionValue:
          type: string
          description: Battery prediction value.
          example: Healthy
        predictionConfidence:
          type: string
          description: Prediction confidence level.
          example: High
        predictionForDay:
          type: integer
          description: Number of days into the future the prediction is for.
          example: 3
    ApiError:
      type: object
      description: Standard error response returned by all API endpoints.
      properties:
        type:
          type: string
          description: >-
            Error category (e.g. AUTHENTICATION, AUTHORIZATION, NOT_FOUND,
            VALIDATION, RATE_LIMIT, SERVER_ERROR).
          example: AUTHENTICATION
        code:
          type: string
          description: Machine-readable error code within the category.
          example: TOKEN_EXPIRED
        description:
          type: string
          description: Human-readable explanation of the error and how to resolve it.
          example: The access token has expired. Request a new token.
        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#token-expired
      required:
        - type
        - code
        - description
  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: TOKEN_EXPIRED
            description: >-
              The access token has expired. Request a new token using
              /api/authentication/token/user or
              /api/authentication/token/api-key.
            requestId: req_7f3a2b1c
            docUrl: https://docs.telemax.com.au/errors#token-expired
    Forbidden:
      description: >
        **403 Forbidden** — Token is valid but the caller does not have access
        to the requested company or vehicle.

        Tokens issued for one company cannot access resources scoped to a
        different company in the hierarchy.
      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: AUTHORIZATION
            code: COMPANY_ACCESS_DENIED
            description: >-
              Your token does not grant access to company 99. Ensure you are
              using a token issued for this company.
            requestId: req_4a1d9e2f
            docUrl: https://docs.telemax.com.au/errors#company-access-denied
    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. Wait 30 seconds before retrying.
            requestId: req_6d2f8b4a
            docUrl: https://docs.telemax.com.au/errors#rate-limit
    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_ERROR
            description: >-
              An unexpected error occurred. Please try again or contact support
              with the requestId.
            requestId: req_1e5a3c7d
            docUrl: https://docs.telemax.com.au/errors#server-error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT Bearer token obtained from `POST /api/authentication/token/user` or
        `POST /api/authentication/token/api-key`.


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


        **Scoping:**

        - User tokens are scoped to a single company.

        - API key tokens may restrict access to a vehicle allowlist and/or
        action set (see token claims).


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

````