# Cartrack for Developers

---



---

Plain-markdown copy of the documentation at https://developer.cartrack.com/. The Fleet API endpoint reference is the OpenAPI specification at https://developer.cartrack.com/openapi/openapi.yaml.

---



---

# Authentication

Source: https://developer.cartrack.com/docs/fleet-api-general/authentication

To use Cartrack services and the Fleet API, you must have an account. The Cartrack Fleet API uses HTTP Basic Authentication. Requests must include an `Authorization` header containing a Base64‑encoded `username:password` pair. Always use HTTPS when sending credentials.

There are two primary user roles:

- **Administrator:** Full access to account settings and fleet data; responsible for issuing credentials and managing user permissions.
- **Subuser:** Access limited to features and data permitted by an Administrator. Fleetweb writes this as "sub-user"; the API reference and the endpoint and field names use "subuser" (`/subusers`, `subuser_id`).

## Administrator

Administrators sign in to Fleetweb with the credentials provided by Cartrack. Typical responsibilities include:

- Issuing API credentials to subusers and integrations.
- Creating and managing subuser accounts and access permissions in Fleetweb.
- Maintaining fleet configuration and access controls.

## Subuser

Administrators can create and manage subusers in Fleetweb and assign permissions appropriate to their role. If you require access, request it from your organization's Fleetweb Administrator.

A subuser authenticates with the main account's username together with the subuser's own API password, so the username is shared across the account and only the password identifies the subuser.

### Delivery access limits

Subuser credentials are read-only across the whole Delivery family. Before you build an integration on them, check these limits:

- Every `POST`, `PUT` and `DELETE` under `/delivery/` returns `403 Forbidden` when the request is authenticated with a subuser API password.
- Most Delivery reads do accept subuser credentials, but they return the whole account's data with no filtering by subuser. A subuser API password does not narrow what a Delivery read returns.
- A few Delivery reads require the main account's API password and also return `403 Forbidden` for a subuser. `GET /delivery/reports/drivers` is one of them.

To create or update a delivery resource on behalf of a subuser, authenticate with the main account's API password and set `subuser_id`: as a request body field on delivery jobs and drivers, on create and update, and as a column in the uploaded file on `POST /delivery/jobs/bulk-upload`. That is the supported way to attribute a delivery write to a subuser.

These limits apply to Delivery only. On the rest of the API a subuser sees only what the Administrator has granted it, for example its permitted vehicle listings.

## Fleetweb Access

Use the region-specific Fleetweb URL for your account. Select your country below to open the correct Fleetweb endpoint:

_Interactive content, see https://developer.cartrack.com/docs/fleet-api-general/authentication_

## Generating Administrator and Subuser API passwords

In order to generate API credentials, you will need to connect to Fleetweb.

Sign in to your region's Fleetweb site (for example: `https://fleetweb-<region>.cartrack.com`).

Open the API Settings page at `https://fleetweb-<region>.cartrack.com/settings/api-settings` (Settings → API Settings in the Fleetweb menu). See screenshot below.

![Access Admin Section](/img/fleetweb/finding-api-section.png "Administrator credentials page")

### Administrator password

Generate a new Administrator password following the on-screen prompts.

![API Section Admin](/img/fleetweb/api-section-admin.png "API Admin part")

Store the password securely and share it only with trusted personnel.

### Subuser API password

Use the "Generate User Credentials" button in the User Credentials section to create a new password for the integration or partner.

![API Section User](/img/fleetweb/api-section-subuser.png "API User part")

Assign only the scopes/permissions required and store the password securely. Note that a subuser password cannot write to the Delivery endpoints: see [Delivery access limits](#delivery-access-limits).

Notes

- Use subuser accounts for external integrations when possible; reserve Administrator credentials for management tasks. An integration that writes to `/delivery/` is the exception and needs the main account's credentials.
- If your account is hosted in a different region, use the corresponding Fleetweb and API base URL — otherwise authentication will fail with HTTP 401.
- Refer to the Base URLs page for region codes and endpoints.

## Identifying Username and Password

For Administrator, the username and password are found here:

![Admin Username and Password](/img/fleetweb/api-section-authentication-admin.png)

For subusers, the username will be the same as the administrator, but the password will be different. You can find the subuser password here:

![User Username and Password](/img/fleetweb/api-section-authentication-sub.png)

## How to construct the header

1. Concatenate your username, a colon (`:`), and your password: `username:password`.
2. Base64‑encode that string. This side can be useful: https://www.base64encode.org, however most API clients such as Postman offer the functionality to do this for you by selecting "Basic Auth" in the Authorization tab.
3. Add the encoded value to the `Authorization` header prefixed with `Basic`.

### Example (raw header)

```http
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
```

If you want, you can have it a try and decode this text here: https://www.base64decode.org

## Quick examples

curl

```bash
curl -u "username:password" "https://fleetapi-za.cartrack.com/rest/vehicles"
```

JavaScript (fetch)

```javascript
const credentials = btoa(`${username}:${password}`);
fetch('https://fleetapi-za.cartrack.com/rest/vehicles', {
 headers: { 'Authorization': `Basic ${credentials}` }
});
```

## Security best practices

- Always use HTTPS — never send credentials over plain HTTP.
- Do not embed credentials directly in client-side code that may be public.
- Store credentials securely (environment variables, secret managers, vaults).
- Use least privilege: generate subuser API passwords for integrations instead of sharing administrator credentials. Delivery is the exception, because subuser credentials cannot write to `/delivery/` and do not narrow what a Delivery read returns (see [Delivery access limits](#delivery-access-limits)).
- Rotate and revoke credentials regularly; update integrations after rotation.
- If you receive HTTP 401 Unauthorized, verify you're using the correct regional endpoint for your account (see Base URLs).

---

# Base URLs

Source: https://developer.cartrack.com/docs/fleet-api-general/base-url

Correct base URLs ensure optimal performance, correct data routing, and compliance with regional requirements. Cartrack accounts are hosted by region — using the wrong regional endpoint for an account can prevent authentication and will typically return HTTP 401 Unauthorized. Use the region-specific endpoint for the account you are working with.

## Base URL template

_Interactive content, see https://developer.cartrack.com/docs/fleet-api-general/base-url_

- Replace `<region>` with the two-letter country code (ISO alpha-2).
- Example: <BrandAwareBaseUrlExampleInline />.

## Supported countries (code — name)

Domain note:

- `ke` (Kenya) and `sa` (Kingdom of Saudi Arabia) use the `karooooo.com` domain.
- All other supported countries use the `cartrack.com` domain.

- au — Australia
- bw — Botswana
- es — Spain
- hk — Hong Kong
- id — Indonesia
- ke — Kenya
- kh — Cambodia
- me — Middle East
- mw — Malawi
- my — Malaysia
- mz — Mozambique
- na — Namibia
- ng — Nigeria
- nz — New Zealand
- ph — Philippines
- pl — Poland
- pt — Portugal
- rw — Rwanda
- sa — Kingdom of Saudi Arabia
- sg — Singapore
- sz — Swaziland
- th — Thailand
- tz — Tanzania
- vn — Vietnam
- za — South Africa
- zm — Zambia
- zw — Zimbabwe

## Quick example (curl)

_Interactive content, see https://developer.cartrack.com/docs/fleet-api-general/base-url_

Notes:

- Verify which country code is associated with your account (ask your Fleetweb Administrator).
- For the canonical API reference see the [API References](/docs/applications/fleet-api) page.

![Example of base URL](/img/api/base_urls.png "Example of base URL")

---

# Follow Fleet API Releases

Source: https://developer.cartrack.com/docs/fleet-api-general/follow-releases

Every Fleet API release note on the [changelog pages](/docs/fleet-api-general/changelog) is also published in machine-readable form. Use the feeds to get notified of new releases in a feed reader or chat tool, or read `changelog.json` to react to changes from your own code, for example to flag deprecated endpoints your integration still calls.

The feeds and files contain exactly what the changelog pages show, and are updated with every release.

## Feeds

| Format | URL | Content |
|---|---|---|
| RSS 2.0 | [`/changelog/rss.xml`](pathname:///changelog/rss.xml) | Latest 20 releases, full text |
| Atom | [`/changelog/atom.xml`](pathname:///changelog/atom.xml) | Latest 20 releases, full text |
| JSON Feed 1.1 | [`/changelog/feed.json`](pathname:///changelog/feed.json) | Latest 20 releases, full text as HTML and markdown |

Each release is one item, identified by a stable ID that never changes once published, so a feed reader shows each release once.

### Feeds per API area

Release notes are tagged with the API area they concern, such as **Geofences** or **Trips**. Each area has its own RSS feed at `/changelog/<area>.xml`, containing only that area's changes from the latest 20 releases that touched it.

Areas use the names written in the release notes, so a topic can appear under more than one name (for example **Delivery** and **Delivery Jobs**). Subscribe to each name that matters to you, or filter `changelog.json` by endpoint instead.

_Interactive content, see https://developer.cartrack.com/docs/fleet-api-general/follow-releases_

## Structured data: changelog.json

[`/changelog.json`](pathname:///changelog.json) holds one record per release-note bullet for the latest 20 releases, newest first, in `entries`. It also lists those releases in `releases`, and the feed URLs in `feeds`.

```json
{
  "version": "1.26.0930.1",
  "date": "2026-09-30",
  "kind": "deprecation",
  "section": "Improvements",
  "area": "Vehicle Commands",
  "contract": ["v1"],
  "endpoints": [
    "PUT /vehicles/{registration}/immobilise",
    "GET /vehicles/immobilise/status"
  ],
  "breaking": false,
  "text": "`PUT /vehicles/{registration}/immobilise` and `GET /vehicles/immobilise/status` are no longer listed in the API reference. Both keep serving their existing callers; new integrations should use the start-inhibit endpoints above."
}
```

| Field | Description |
|---|---|
| `version` | Fleet API version the change shipped in. |
| `date` | Release date, `YYYY-MM-DD`. |
| `kind` | `feature`, `improvement`, `fix`, `deprecation`, `breaking` or `other`. See below. |
| `section` | The heading the bullet appears under on the changelog page, for example `New Features`. |
| `area` | The API area tag, or `null` for older releases written before areas were tagged. |
| `contract` | API contract versions the change applies to. Currently always `["v1"]`. |
| `endpoints` | Endpoints named in the bullet, as `METHOD /path`. Empty when the change is not tied to specific endpoints. |
| `breaking` | `true` when the change is listed under a Breaking Changes heading. |
| `text` | The release-note text, in markdown. |

`kind` comes from the section heading: **New Features** is `feature`, **Improvements** is `improvement`, **Bug Fixes** is `fix`. A bullet that deprecates something, or removes an endpoint from the API reference, is `deprecation` whichever section it is listed in.

### Older releases

`changelog.json` covers the latest 20 releases. Every release, back to the first, is listed in [`/changelog/versions/index.json`](pathname:///changelog/versions/index.json), and each has its own file at `/changelog/versions/<version>.json` with the same records. Each version file links to the one before and after it in `previous` and `next`, so you can page back from any release.

## Polling efficiently

All feeds and JSON files are served with `ETag` and `Last-Modified` headers. Send them back with `If-None-Match` or `If-Modified-Since`, and you get `304 Not Modified` with no body until something changes:

```bash
# First request: keep the ETag from the response headers
curl -si https://developer.cartrack.com/changelog.json | grep -i '^etag'
# ETag: "6abe16bf-11135"

# Later requests: send it back. 304 means nothing has changed.
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'If-None-Match: "6abe16bf-11135"' https://developer.cartrack.com/changelog.json
# 304
```

Releases ship a few times a month, so checking once an hour is plenty.

The files can be fetched from a web page on any domain. In browser code, call `fetch()` without setting `If-None-Match` yourself: the browser revalidates with the `ETag` automatically, and setting the header by hand makes the browser send an extra preflight request first.

## AI tools

For AI assistants and crawlers, the site publishes:

- [`/llms.txt`](pathname:///llms.txt): an index of the documentation pages, the OpenAPI specification and the changelog data above, following the [llms.txt](https://llmstxt.org) convention.
- [`/llms-full.txt`](pathname:///llms-full.txt): the documentation and the latest 20 releases as a single markdown file.

Point your assistant at `llms.txt` to give it the Fleet API documentation, and at the [OpenAPI specification](pathname:///openapi/openapi.yaml) for the exact endpoints and schemas.

---

# Overview

Source: https://developer.cartrack.com/docs/fleet-api-general/overview

The Cartrack Fleet API helps you connect your systems to fleet data and operations so you can monitor vehicles, automate workflows, and build fleet-facing products.

This page is the recommended starting point for both business and technical teams before going deeper into endpoint details.

## What the Fleet API enables

Examples of what you can do with the Fleet API include, but are not limited to:

- View vehicle, trip, and event data to improve operational visibility.
- Integrate driver, fuel, route, and delivery workflows into your own platforms.
- Trigger business actions from telemetry and status updates.
- Build internal dashboards, alerts, and process automations.

## Recommended integration path

Follow these pages in order for a faster and clearer setup:

1. **Confirm your integration goals** in [Use Cases](/docs/fleet-api-general/use-cases).
2. **Prepare account access, roles, and validate credentials** in [Authentication](/docs/fleet-api-general/authentication).
3. **Get your regional API endpoint** in [Base URLs](/docs/fleet-api-general/base-url).
5. **Run your first request** with [Quick Start](/docs/fleet-api-general/quick-start).
6. **Harden for production** with [Rate Limiting](/docs/fleet-api-general/rate-limiting) and [Webhook Notifications](/docs/fleet-api-general/webhook-notification).
7. **Implement specific business flows** under [Guides](/docs/fleet-api-general/use-cases) and full [API References](/docs/applications/fleet-api).

## How business and technical teams can collaborate

- Agree on priority workflows first (for example: tracking, delivery, driver assignment, or fuel monitoring).
- Define data ownership and expected refresh behavior (pull APIs vs webhook events).
- Validate API access, roles, and environments before development starts.
- Pilot with a small fleet scope, then scale after monitoring and error-handling checks.

## Next step

Start with [Authentication](/docs/fleet-api-general/authentication) to confirm access, roles, and account readiness.

---

# Quick Start

Source: https://developer.cartrack.com/docs/fleet-api-general/quick-start

:::tip

Get started immediately and perform your first API request to retrieve the vehicles list [here](/docs/fleet-api/get-vehicles-list).

:::

Getting started with the Cartrack Fleet API is straightforward. This section provides a basic example of how to make your first API call using curl, JavaScript, or Python.

## Prerequisites

Before you proceed, make sure you have:

- **An HTTP client**: curl (available on Unix, Linux, macOS, and Windows), or an HTTP library in your language of choice (e.g. `requests` for Python, `fetch` for JavaScript).
- **Base URL and Authentication Credentials**: You will need the base URL for the Cartrack Fleet API and valid credentials. For detailed guidance on obtaining these, please refer to the [Authentication](/docs/fleet-api-general/authentication) and [Base URLs](/docs/fleet-api-general/base-url) sections of our documentation.

## Making an API Call

The example below retrieves the list of vehicles. Replace `{baseUrl}` with your regional base URL and supply your credentials (see [Authentication](/docs/fleet-api-general/authentication)).

**curl**

```bash
curl --location '{baseUrl}/rest/vehicles' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic your_encoded_credentials'
```

**JavaScript**

```javascript
const credentials = btoa('username:password');

const response = await fetch('{baseUrl}/rest/vehicles', {
  headers: {
    'Accept': 'application/json',
    'Authorization': `Basic ${credentials}`,
  },
});

const data = await response.json();
console.log(data);
```

**Python**

```python
import requests

response = requests.get(
    '{base_url}/rest/vehicles',
    auth=('username', 'password'),
    headers={'Accept': 'application/json'},
)

print(response.json())
```

## Response

The API will return a JSON response containing a list of vehicles, each with details like vehicle ID, model, and other relevant information.

For more detail on the available endpoints and request/response schemas, see the [Fleet API reference](/docs/fleet-api/fleet-api).

## Import to Postman

You can import the Cartrack OpenAPI specification into Postman to generate a ready-to-use collection of requests.

- Spec URL: [https://developer.cartrack.com/openapi/openapi.yaml](https://developer.cartrack.com/openapi/openapi.yaml)
- In Postman: click **Import → Link**, paste the URL, then click **Import**. Or use **Import → File** and upload the downloaded `openapi.yaml`.
- Postman will create a collection of requests based on the spec.
- Configure environment values:
  - Set the base URL using the guidance on the [Base URLs](/docs/fleet-api-general/base-url) page.
  - Configure authentication: Cartrack APIs use **Basic Authentication**. In Postman, open any request, go to the **Authorization** tab, choose **Basic Auth**, and enter your username and password. Alternatively, add the `Authorization` header with the value `Basic <base64-encoded-credentials>`.
    See the [Authentication](/docs/fleet-api-general/authentication) page for details on generating credentials.
- Run individual requests or use the Collection Runner to execute multiple calls.

---

# Rate Limiting

Source: https://developer.cartrack.com/docs/fleet-api-general/rate-limiting

The Cartrack Fleet API applies rate limiting to all incoming API requests to protect network resources, maintain system performance, and ensure a consistent experience for all users.

### Default Rate Limit
The API has a default rate limit of **1,000 requests per minute**. This limit applies across most API endpoints unless otherwise specified. Any requests exceeding this limit will receive an HTTP `429 Too Many Requests` response.

### API Endpoint Specific Rate Limit

Some API endpoints have stricter rate limits to ensure fairness and prevent abuse. Below are the specific limits for these endpoints:

| **Endpoint**                                                  | **Rate Limit**                   | **Description**                                                        |  
|---------------------------------------------------------------|----------------------------------|------------------------------------------------------------------------|  
| [POST /fuel/consumed](/docs/fleet-api/retrieve-fuel-consumed-sensor-data-for-multiple-vehicles) | 10 requests per minute | Retrieve fuel used estimate for multiple vehicles. |
| [POST /fuel/level](/docs/fleet-api/retrieve-fuel-used-estimate-for-multiple-vehicles) | 10 requests per minute | Retrieve fuel consumed sensor data for multiple vehicles. |
| [POST /vehicles/ev-consumption](/docs/fleet-api/retrieve-electric-vehicles-estimated-battery-consumptions) | 10 requests per minute | Retrieve battery consumption for multiple electric vehicles. |
| [POST /vehicles/range](/docs/fleet-api/retrieve-multiple-electric-vehicles-remaining-range) | 10 requests per minute | Retrieve EV range reported events for multiple electric vehicles. |
| [POST /vehicles/soc](/docs/fleet-api/retrieve-multiple-electric-vehicles-state-of-charge-so-c-events) | 10 requests per minute | Retrieve state of charge (SoC) events for multiple electric vehicles. |
| [GET /vehicles/status](/docs/fleet-api/get-vehicles-status-location-fuel-odometer-and-more) | 60 requests per minute | Retrieve the latest snapshot for the entire fleet. |
| [GET /vehicles/events](/docs/fleet-api/get-events-for-all-vehicles) | 60 requests per minute | Retrieve events for all vehicles in the fleet. |
| [GET /vehicles/\{registration\}/events](/docs/fleet-api/get-events-for-one-vehicle) | 200 requests per minute | Retrieve events for a specific vehicle. |
| [GET /vehicles/\{registration\}/events/idling](/docs/fleet-api/get-idling-events-for-one-vehicle) | 200 requests per minute | Retrieve idling events for a specific vehicle. |
| [GET /vehicles/vext](/docs/fleet-api/get-vehicles-vext-at-ignition-off) | 10 requests per minute | Retrieve vehicles VEXT data regardless of ignition status. |
| [GET /vision/status](/docs/fleet-api/get-vision-camera-online-status) | 6 requests per minute | Retrieve the current online status of Vision cameras across the fleet. |

For endpoint-specific rate limits, exceeding the limit will also result in an HTTP `429 Too Many Requests` response.

### Vehicle Command Cooldown

In addition to the request rate limits above, the vehicle command endpoints apply a cooldown to prevent duplicate commands:

- [PUT /vehicles/\{registration\}/central-locking](/docs/fleet-api/send-command-to-lock-or-unlock-a-vehicle)
- [POST /vehicles/commands/\{registration\}](/docs/fleet-api/send-command-to-sound-horn-or-turn-on-hazard-lights-on-vehicle)

Once a command is accepted, the same command cannot be sent again to the same vehicle while the previous one is still being processed, for up to **30 seconds**. During this window the API responds with an HTTP `409 Conflict` and a `Retry-After` header indicating the number of seconds to wait before retrying.

The cooldown applies per vehicle and per command: sending a different command to the same vehicle, or the same command to a different vehicle, is not affected.

**Example Response**
```json
HTTP/1.1 409 Conflict
Content-Type: application/json
Retry-After: 30

{
    "data": null,
    "error": {
        "code": 409,
        "message": "Cannot send lock/lock simultaneously. Try again later."
    }
}
```

### Retry Behavior

If you receive a HTTP `429 Too Many Requests` response, you must respect the headers included in the response. These headers provide information about when you can retry:

- `X-RateLimit-Retry-At`: The timestamp of the next earliest retry.
- `X-RateLimit-Retry-After-Seconds`: The number of seconds until the next earliest retry.

**Example Response**
```json
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Retry-At: 1737592000
X-RateLimit-Retry-After-Seconds: 15

{
    "error": {
        "code": 429,
        "message": "Too many requests. Please wait before retrying."
    }
}
```

**How to Handle `429 Too Many Requests`**
- **Wait and Retry**: Respect the `X-RateLimit-Retry-At` and `X-RateLimit-Retry-After-Seconds` header to wait for the recommended time before retrying.
- **Exponential Backoff**: Implement exponential backoff with jitter to avoid repeated rate-limit violations.

**Notes**: Repeated violations of rate limits may result in temporary or permanent access restrictions.

### Increasing the Limit

If your application requires a higher rate limit, you may submit a request for a limit increase. Requests will be evaluated on a case-by-case basis to ensure compatibility with our infrastructure. Approved limits will be customized and communicated accordingly.

---

# Carpool Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/carpool-services

Carpool is Cartrack's shared vehicle booking system: drivers request a pool vehicle for a scheduled time window, a manager approves or declines the request, and the vehicle's actual pickup and return are tracked against that window. This page explains the read-only Carpool endpoints, with a focus on the booking lifecycle and the `booking_status` values on `GET /carpool/bookings`.

## Which Endpoint Should I Use?

Use this mapping based on what you want to accomplish:

| Goal | Endpoint |
|------|----------|
| Search or list bookings by vehicle, driver, date range, or status | [Get All Carpool Bookings](https://developer.cartrack.com/docs/fleet-api/get-all-carpool-bookings) |
| Get full detail for a single booking | [Get Carpool Booking by Booking ID](https://developer.cartrack.com/docs/fleet-api/get-carpool-booking-by-booking-id) |
| List vehicles enabled for carpool use, their category, and setup completeness | [Get All Carpool Enabled Vehicles](https://developer.cartrack.com/docs/fleet-api/get-all-carpool-enabled-vehicles) |
| List the vehicle categories available for booking | [Get All Carpool Vehicle Categories](https://developer.cartrack.com/docs/fleet-api/get-all-carpool-vehicle-categories) |
| List drivers registered for carpool use and their booking eligibility | [Get All Registered Carpool Drivers](https://developer.cartrack.com/docs/fleet-api/get-all-registered-carpool-drivers) |

## Booking Status Values

`booking_status` on a booking record is not something the requester or approver sets directly for most of its values. Most transitions are computed automatically by a backend process that re-evaluates every booking every couple of minutes against the current time and the vehicle's telemetry (ignition state, geofence entry/exit). A few values are set manually by a fleet manager acting in Fleetweb, not by that automatic process.

```mermaid
stateDiagram-v2
    [*] --> REQUESTED : Driver submits a request
    REQUESTED --> APPROVED : Manager approves (or client auto-approves)
    REQUESTED --> DECLINED : Manager declines
    REQUESTED --> EXPIRING_APPROVAL : Start time is under 1 hour away, still no decision
    EXPIRING_APPROVAL --> APPROVED : Manager approves before start time
    EXPIRING_APPROVAL --> DECLINED : Manager declines before start time
    EXPIRING_APPROVAL --> CANCELLED : Start time passes with no decision
    APPROVED --> CANCELLED : Vehicle never picked up within the grace period
    APPROVED --> ACTIVE : Vehicle picked up
    ACTIVE --> ACTIVE_ALMOST_LATE : Scheduled end time approaching
    ACTIVE --> ACTIVE_LATE : Scheduled end time passes, vehicle still out
    ACTIVE_ALMOST_LATE --> ACTIVE_LATE : Scheduled end time passes, vehicle still out
    ACTIVE --> RETURNED : Vehicle returned at or before end time
    ACTIVE_LATE --> RETURNED_LATE : Vehicle returned after end time
    APPROVED --> FORCE_TERMINATED : Manager force-ends the booking (Fleetweb)
    ACTIVE --> FORCE_TERMINATED : Manager force-ends the booking (Fleetweb)
    ACTIVE_LATE --> FORCE_TERMINATED : Manager force-ends the booking (Fleetweb)
```

| Value | Meaning |
|-------|---------|
| `BOOKING_STATUS_FREE` | Reserved value in the schema. No booking record returned by `GET /carpool/bookings` carries this status — it does not represent a state a real booking passes through. |
| `BOOKING_STATUS_REQUESTED` | A driver has submitted a booking request. Awaiting a manager's approval or decline decision. |
| `BOOKING_STATUS_APPROVED` | The booking is confirmed for its scheduled window — every department required to sign off has approved. This includes bookings approved automatically under a client's "Automatically approve new request" carpool setting: `is_approved` is `true` in that case too, but `approved_by` stays `null` because no manager actually took an approval action. |
| `BOOKING_STATUS_DECLINED` | A manager declined the request. Unlike approval, decline doesn't need consensus — a single department manager declining is enough to move the whole booking to `DECLINED`, even if other departments haven't responded yet. |
| `BOOKING_STATUS_CANCELLED` | The booking was cancelled — manually by the driver (only while still `REQUESTED` or `APPROVED`, not once picked up) or a manager (from any status), or automatically because the vehicle was never picked up. A `REQUESTED`, `EXPIRING_APPROVAL`, or `APPROVED` booking that passes its `start_ts` without being picked up is auto-cancelled once its client-configured grace period elapses (30 minutes after `start_ts` by default; some clients configure this relative to `end_ts` instead). |
| `BOOKING_STATUS_ACTIVE` | The vehicle has been picked up and the booking is in progress, before its scheduled `end_ts`. What counts as "picked up" is configurable per client — ignition on, leaving a pickup geofence, key collection from a smart locker, or a manual action in Fleetweb. |
| `BOOKING_STATUS_ACTIVE_ALMOST_LATE` | An early-warning state for an in-progress booking whose scheduled `end_ts` is approaching. Sits between `ACTIVE` and `ACTIVE_LATE` in the lifecycle — handle it as a valid value, but don't assume every booking passes through it before going late. |
| `BOOKING_STATUS_ACTIVE_LATE` | The scheduled `end_ts` has passed and the vehicle has not yet been returned. |
| `BOOKING_STATUS_RETURNED` | The vehicle was returned at or before the scheduled `end_ts`. |
| `BOOKING_STATUS_RETURNED_LATE` | The vehicle was returned after the scheduled `end_ts`. |
| `BOOKING_STATUS_EXPIRING_APPROVAL` | The booking is still awaiting a manager's decision (`REQUESTED`) and its scheduled `start_ts` is now less than one hour away. If no decision is made before `start_ts`, the booking is auto-cancelled. |
| `BOOKING_STATUS_FORCE_TERMINATED` | A fleet manager manually ended the booking from Fleetweb — only possible while the booking is `ACTIVE`, `ACTIVE_ALMOST_LATE`, or `ACTIVE_LATE` (the vehicle must currently be checked out). This is not an automatic transition; Fleetweb's own confirmation prompt frames it for cases like an accident, breakdown, or the vehicle being towed, not routine returns. |

## Developer Considerations

- The `ACTIVE` → `ACTIVE_ALMOST_LATE` → `ACTIVE_LATE` progression is graduated, not guaranteed — don't treat a booking going straight from `ACTIVE` to `ACTIVE_LATE` as unexpected or an error.
- Don't recompute lateness yourself by comparing `returned_at` to `end_ts`. The API's `returned_at` prefers a site-location (geofence) timestamp over the ignition timestamp when both exist, and it can differ slightly from the timestamp actually used to decide `RETURNED` vs `RETURNED_LATE`. Trust the `booking_status` value for that determination.

## Setup Status: Vehicles and Drivers

Both `GET /carpool/vehicles` and `GET /carpool/drivers` return a `setup_status` field, but the two use different enums (`SETUP_INCOMPLETE` / `READY` for vehicles, `SETUP_INCOMPLETE` / `ACTIVE_CARPOOL` for drivers) and different completeness rules — don't assume they're interchangeable.

For vehicles, `SETUP_INCOMPLETE` means the vehicle is missing a department, category, default location, or license class. Which of those four are actually required is configurable per client: an account may not require all of them, so a vehicle can be `READY` without, for example, a department assigned, if that client hasn't turned department scoping on.

For drivers, `ACTIVE_CARPOOL` requires the driver to be enabled for carpool booking (`can_book_carpool`) and to have at least one of `allow_system_auto_booking` or `allow_specific_vehicle_booking` enabled, plus any department/license requirements the client has turned on. A driver with `can_book_carpool: true` but both booking methods disabled still shows as `SETUP_INCOMPLETE`.

## Approval Fields: `is_approved`, `approved_by`, `declined_by`

`approved_by` and `declined_by` are `null` whenever no manager has taken an approval action on the booking — including auto-approved bookings. Use `is_approved` and `booking_status` to determine the booking's approval state; use `approved_by`/`declined_by` only to find out whether a manager was the one who decided it.

---

# Delivery Job Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/delivery-job-services

This page explains how to create delivery jobs with the Fleet API and how to confirm whether submitted jobs were created successfully.

## Acronyms and Terms

- **API**: Application Programming Interface.
- **ERP**: Enterprise Resource Planning.
- **HTTP**: Hypertext Transfer Protocol.

## Which Endpoint Should I Use?

Use this mapping based on your job creation volume and feedback needs:

- **High-volume job creation (batch uploads)**:
  - [Bulk Upload Delivery Jobs](https://developer.cartrack.com/docs/fleet-api/bulk-upload-delivery-jobs)
- **Single or low-volume job creation (immediate response)**:
  - [Create a Delivery Job](https://developer.cartrack.com/docs/fleet-api/create-a-delivery-job)

## 1) Bulk Upload Delivery Jobs

### What It Means

Submit multiple jobs in a single request when you need to push many deliveries from ERP or dispatch systems.

### Confirmation and Notifications

The bulk upload service supports a `webhooks_url` field.
After processing is completed, Cartrack sends a webhook callback so your system can confirm the upload outcome and reconcile what was created.
For webhook setup, signature verification, and security guidance, see [Webhooks](/docs/fleet-api-general/webhook-notification).

### Purpose

- Best option for scheduled or large delivery imports.
- Gives operations teams a reliable confirmation flow instead of assuming all jobs were created.
- Helps identify partial-creation scenarios quickly.

### Developer Considerations

- Treat the request as an asynchronous flow.
- Use webhook callbacks as the source of truth for completion status.
- Compare your submitted jobs with callback results and trigger retry/escalation for jobs that were not created.

## 2) Create a Delivery Job

### What It Means

Create one delivery job per request with immediate API feedback.

### Confirmation and Errors

If the job cannot be created, the API returns a non-`200` HTTP status code together with an error message that explains the failure.

### Purpose

- Best for interactive flows where users create one job at a time.
- Failures are visible immediately and can be surfaced directly to support or dispatch users.

### Developer Considerations

- Validate the HTTP response status for every request.
- Handle non-`200` responses as explicit creation failures.
- Log and return the API error message so operations teams can resolve data issues quickly.

## Recommended Integration Pattern

1. Keep a client-side reference for each submitted job (from ERP/dispatch).
2. Use bulk upload with `webhooks_url` for high-volume imports.
3. Track callback outcomes and reconcile expected vs created jobs.
4. Handle all non-`200` responses from single-job creation as failures.
5. Retry or escalate failed jobs through your internal support workflow.

---

# Driver Identification Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/driver-identification-services

This page explains how driver assignment works in the Fleet API, including driver tags, default drivers, mobile app assignment, and API linkage.

## Acronyms and Terms

- **API**: Application Programming Interface.
- **RFID**: Radio-Frequency Identification.

## Which Endpoint Should I Use?

Use this mapping based on how you want to identify drivers for vehicles:

- **Current driver snapshot across the fleet**:
  - [Get Vehicle's Status: location, fuel, odometer and more](https://developer.cartrack.com/docs/fleet-api/get-vehicles-status-location-fuel-odometer-and-more)
- **Set or change a vehicle's default (fallback) driver**:
  - [Update a Vehicle's Details](https://developer.cartrack.com/docs/fleet-api/update-a-vehicles-details)
- **Audit RFID driver tag reads over time**:
  - [Get Driver Tags Events](https://developer.cartrack.com/docs/fleet-api/get-driver-tags-events)
- **Assign driver from a third-party integration (RFID-like behavior)**:
  - [Link Driver to a Vehicle](https://developer.cartrack.com/docs/fleet-api/link-driver-to-a-vehicle)
- **Clear or inspect API-created linkages**:
  - [Unlink Driver from a Vehicle](https://developer.cartrack.com/docs/fleet-api/unlink-driver-from-a-vehicle)
  - [Retrieve Current Linkages](https://developer.cartrack.com/docs/fleet-api/retrieve-current-linkages)

## Driver Association Methods

Drivers can associate to vehicles in multiple ways:

1. **Default driver on the vehicle**:
   - Persistent/fallback assignment.
   - Used when no temporary assignment is currently detected.
2. **RFID driver tag read in vehicle** (requires compatible fitment):
   - Driver tags in while ignition is ON.
   - Association is kept until ignition is OFF, or another driver tag is read and overrides it.
3. **Cartrack driver mobile app assignment**:
   - Driver assigns themselves in the app.
4. **Vehicle Driver Linkage API**:
   - Third-party system links a driver to a vehicle.
   - Useful when reproducing RFID-style behavior through integration.

## How Driver Tags Help Identify the Driver

Driver tags provide an operational way to identify who is currently driving, without relying only on static/default vehicle ownership.

- They capture a per-use driver context while ignition is ON.
- They can override a previously assigned temporary driver during the same ignition cycle.
- Their events can be audited historically through the driver tags events endpoint.

This helps teams improve trip accountability and driver-level reporting for shared vehicles.

## Driver Resolution in Vehicle Status

`/vehicles/status` is a snapshot service and returns the current driver context for each vehicle.

- If an active temporary association exists (RFID tag flow or linkage API flow), that driver is shown as the current driver.
- If no temporary association is active, the vehicle default driver is used as the fallback value.
- RFID association is cleared at ignition OFF.

## Recommended Integration Pattern

For most integrations:

1. Set and maintain default drivers as baseline ownership.
2. Use one temporary assignment flow for active-driver identification.
3. Poll vehicle status for operational snapshots.
4. Query driver tag events for historical audit and investigations.

:::warning Integration Constraint
Vehicle Driver Linkage endpoints should not be used together with other Cartrack driver-vehicle assignment services (for example, driver mobile app or driver tags) in the same operational flow.
:::

---

# Fuel Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/fuel-services

This page explains the fuel-related services in the Fleet API for both business and technical audiences.

## Acronyms and Terms

- **API**: Application Programming Interface.
- **ECU**: Engine Control Unit. The in-vehicle computer that controls and monitors engine operation.
- **CAN bus**: Controller Area Network bus. The vehicle network used by electronic modules to exchange data.

## Fuel Concepts at a Glance

- **Fuel consumed**: A cumulative value from the ECU that represents total fuel burned by the engine since a reference point.
- **Fuel level**: Fuel quantity in the tank, read from an analog sensor or from the CAN bus.
- **Fuel fills and estimated fuel used**: Events and usage periods inferred from fuel level trends over time.

## How to Check Sensor Availability Per Vehicle

Before calling fuel endpoints, you can verify whether each vehicle has the required sensors by using:

- [Get vehicles list](https://developer.cartrack.com/docs/fleet-api/get-vehicles-list)

In the response, check `data.sensors.*`:

- `data.sensors.fuel_canbus_consumed`: `true` when CAN bus fuel consumed data is available.
- `data.sensors.fuel_canbus_level`: `true` when CAN bus fuel level data is available.
- `data.sensors.fuel_analog_level`: `true` when an analog fuel level sensor is installed.
- `data.sensors.electric_battery`: `true` when an electric battery sensor is installed.
- `data.sensors.electric_charging`: `true` when an electric charging status sensor is installed.

### Fuel Service Mapping

- **Fuel consumed services** require `data.sensors.fuel_canbus_consumed = true`.
- **Fuel level services** require at least one of:
  - `data.sensors.fuel_canbus_level = true`, or
  - `data.sensors.fuel_analog_level = true`.
- **Fuel fills / estimated fuel used** also depend on fuel level availability, so they require at least one of the two fuel level flags above.

### Example

```json
{
  "data": {
    "vehicle_id": "123456",
    "sensors": {
      "fuel_canbus_consumed": true,
      "fuel_canbus_level": true,
      "fuel_analog_level": false,
      "electric_battery": false,
      "electric_charging": false
    }
  }
}
```

## 1) Fuel Consumed (ECU cumulative value)

### Definition

`fuel_consumed` is the total volume of fuel consumed by the vehicle engine since a defined reference point (typically vehicle commissioning or factory release).  
It is a monotonically increasing cumulative value reported by the vehicle ECU.

### What It Is Not

- Fuel currently in the tank.
- Fuel used during one trip only.
- Fuel used since ignition turned on.

### What It Is

- Total engine fuel burned over the vehicle lifetime (from the ECU reference point).
- Computed internally by the ECU from injection timing and flow models.
- Independent of refueling events.

### Business Interpretation

- Useful for long-term fuel performance and cost analysis.
- Best suited for lifetime or long-period efficiency tracking.
- Should not be used as a direct substitute for current tank fuel.

### Developer Interpretation

- Treat as a cumulative counter.
- Compute period usage by subtracting two valid readings.
- Expect no value when the required capability is not enabled on the vehicle.

### Endpoints

- Single vehicle: [Get a vehicle's fuel consumed sensor data](https://developer.cartrack.com/docs/fleet-api/get-a-vehicles-fuel-consumed-sensor-data)
- Multiple vehicles: [Retrieve fuel consumed sensor data for multiple vehicles](https://developer.cartrack.com/docs/fleet-api/retrieve-fuel-consumed-sensor-data-for-multiple-vehicles)

### Availability

Fuel consumed data requires the Cartrack fuel-consumed capability to be available for the vehicle.  
If the API returns no result, contact your Cartrack sales representative to confirm availability.

## 2) Fuel Level (analog sensor or CAN bus)

### Definition

Fuel level is the measured amount of fuel in the tank at a point in time, read either from:

- An analog fuel sensor.
- The CAN bus.

### Business Interpretation

- Useful for operational monitoring, fuel theft detection, and refill oversight.
- Provides tank-state visibility rather than lifetime engine burn.

### Developer Interpretation

- Treat as time-series telemetry.
- Expect variation due to movement, slosh, sensor characteristics, and sampling.

### Endpoint

- Vehicle history: [Get fuel level history for a vehicle](https://developer.cartrack.com/docs/fleet-api/get-fuel-level-history-for-a-vehicle)

### Availability

Fuel level services require available fuel level readings for the vehicle.  
If no data is returned, contact your Cartrack sales account manager to confirm availability.

## 3) Fuel Fills and Estimated Fuel Used (derived from fuel level)

### Definition

Cartrack identifies:

- **Fuel fill periods** from increases in fuel level.
- **Estimated fuel used periods** from decreases in fuel level.

Both outputs are estimated from fuel level readings and require fuel level data availability.

### Business Interpretation

- Helps reconcile refueling activity and consumption patterns.
- Supports exception analysis (unexpected fills, unusual usage).

### Developer Interpretation

- Treat these as derived analytics, not direct ECU counters.
- Data quality depends on fuel level signal quality and coverage.

### Endpoints

- Fuel fills (single vehicle): [Get fuel fills for a vehicle](https://developer.cartrack.com/docs/fleet-api/get-fuel-fills-for-a-vehicle)
- Fuel fills (all vehicles): [Get fuel fills for all vehicles](https://developer.cartrack.com/docs/fleet-api/get-fuel-fills-for-all-vehicles)
- Estimated fuel used (single vehicle): [Get fuel used estimate for a vehicle](https://developer.cartrack.com/docs/fleet-api/get-fuel-used-estimate-for-a-vehicle)

### Availability

Fuel fills and estimated fuel used rely on fuel level readings.  
If no data is returned, confirm fuel level availability for the vehicle with your Cartrack sales account manager.

---

# Mileage and Odometer Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/mileage-odometer-services

This page explains how vehicle mileage and odometer data is tracked and reported through the Fleet API, covering how values are sourced, which endpoints to use for different use cases, and common integration pitfalls.

## Which Endpoint Should I Use?

Use this mapping based on what you want to accomplish:

| Goal | Endpoint |
|------|----------|
| Get total distance travelled over a period | [Get Odometer Reading](https://developer.cartrack.com/docs/fleet-api/get-the-odometer-reading) |
| Get a breakdown of distance per trip | [Get All Trips](https://developer.cartrack.com/docs/fleet-api/get-all-trips) / [Get Trips by Registration](https://developer.cartrack.com/docs/fleet-api/get-trips-by-registration) |
| Get the current odometer snapshot for a vehicle | [Get Vehicles Status](https://developer.cartrack.com/docs/fleet-api/get-vehicles-status-location-fuel-odometer-and-more) |

## 1) How Mileage is Tracked

### Data Source

Cartrack trackers read odometer data directly from the vehicle's CAN bus where the hardware and vehicle support it. CAN bus odometer data reflects the vehicle's own internal mileage counter, making it the most accurate source.

If CAN bus odometer data is not available for a vehicle, Cartrack calculates distance from GPS positions instead. The calculation method is transparent to you in the API — the fields are the same regardless of source.

### Units

All odometer and distance values in the Fleet API are returned in **meters** unless otherwise stated. The vehicle status endpoint (`GET /vehicles/status`) is the only exception — it supports an optional `?odometer_in_km=true` parameter to return the value in kilometers.

### Flags to Watch

Two flags on the odometer endpoint can indicate that values may be inconsistent over a queried period:

| Flag | Meaning |
|------|---------|
| `odometer_reset` | The vehicle's odometer was reset during the period. This can happen when the tracker is reconfigured from GPS odometer to CAN odometer, or when the odometer is manually reset. Distance calculations across a reset period may not be reliable. |
| `terminal_has_changed` | The physical Cartrack tracker in the vehicle was replaced during the period. The odometer counter restarts from a new baseline on the replacement device. |

If either flag is `true` for a queried period, treat the distance values with caution and consider splitting the query into periods before and after the event.

## 2) Distance for a Period

### What It Means

`GET /vehicles/{registration}/odometer` returns the odometer reading at the start and end of a specified time range, plus the total distance travelled in between. This is the recommended endpoint for any use case that needs accurate period-level distance, such as daily mileage reports or billing.

### Response Fields

| Field | Description |
|-------|-------------|
| `start_odometer_value` | Odometer at the start of the queried period, in meters |
| `end_odometer_value` | Odometer at the end of the queried period, in meters |
| `distance` | Total distance travelled during the period, in meters |
| `current_odometer_value` | The vehicle's current odometer reading at query time, in meters |
| `latest_event_ts` | Timestamp of the most recent data received from the vehicle |

### Network Coverage Note

The `latest_event_ts` field indicates when Cartrack last received data from the vehicle. If the vehicle is operating in an area with poor network coverage, data transmission may be delayed. If `latest_event_ts` is significantly earlier than your `end_timestamp`, the returned values may not yet reflect the full period. Query again later once coverage is restored.

### Developer Considerations

- The time range is limited to a maximum of 31 days per request.
- Check `odometer_reset` and `terminal_has_changed` before relying on the `distance` value for a period.
- If you need distance across more than 31 days, issue multiple requests and sum the `distance` values for periods where neither flag is `true`.

## 3) Per-Trip Distance

### What It Means

The trips endpoints return individual trip records, each with a `trip_distance` field and odometer readings at the start and end of the trip. This is useful when you need a journey-level breakdown rather than a period total.

### Response Fields (per trip)

| Field | Description |
|-------|-------------|
| `trip_distance` | Distance covered during the trip, in meters |
| `start_odometer` | Odometer at the beginning of the trip, in meters |
| `end_odometer` | Odometer at the end of the trip, in meters |

### The Trip Boundary Pitfall

:::warning Do not sum trip_distance for daily totals
The trips endpoint returns any trip that overlaps the requested time window, including trips that started before `start_timestamp` or ended after `end_timestamp`. Those trips are returned in full — their full distance is included, not just the portion that falls within your window. Summing `trip_distance` across all returned trips will over- or under-count distance relative to your requested period.

**For accurate daily or period distance totals, always use `GET /vehicles/{registration}/odometer` instead.**
:::

### Developer Considerations

- Use trips data for per-journey breakdowns, driving behaviour reports, and start/end location analysis.
- Do not derive total period distance by summing `trip_distance` — use the odometer endpoint.
- The trips endpoint supports up to 31 days per request and returns paginated results.

## 4) Current Odometer Snapshot

`GET /vehicles/status` includes an `odometer` field representing the vehicle's odometer reading as of its last update event. This is a point-in-time snapshot, not a period calculation. Use it for live fleet dashboards and current-state displays.

Pass `?odometer_in_km=true` to receive the value in kilometers instead of meters.

## Recommended Integration Pattern

1. For **daily or period distance reporting**: use `GET /vehicles/{registration}/odometer` with `start_timestamp` and `end_timestamp` set to midnight boundaries. Check `odometer_reset` and `terminal_has_changed` before using the `distance` value.
2. For **per-trip mileage breakdown**: use `GET /trips/{registration}` and rely on `trip_distance` per individual trip record, not on a sum across trips.
3. For **live fleet odometer display**: poll `GET /vehicles/status` at your refresh interval and read the `odometer` field.
4. If values look inconsistent for a period, query `latest_event_ts` from the odometer endpoint to confirm whether all data has been received — coverage gaps can delay transmission.

---

# Positions and Trip Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/positions-route-services

This page explains how to retrieve vehicle positions and trip history with the Fleet API for both business and technical audiences.

:::info Also known as
The dense sequence of GPS points recorded along a trip is also commonly called a **waypoint list**, **GPS trail**, or **breadcrumb trail**. This page uses "breadcrumb" and "waypoint"/"trail" interchangeably to refer to the same data.
:::

## Acronyms and Terms

- **API**: Application Programming Interface.
- **GPS**: Global Positioning System.

## Which Endpoint Should I Use?

Use this mapping based on the location-related data you need:

- **All GPS positions / full trip point history**:
  - [Get events for one vehicle](https://developer.cartrack.com/docs/fleet-api/get-events-for-one-vehicle)
  - [Get events for all vehicles](https://developer.cartrack.com/docs/fleet-api/get-events-for-all-vehicles)
- **Continuous tracking (near real-time fleet view)**:
  - [Get vehicles status, location, fuel, odometer and more](https://developer.cartrack.com/docs/fleet-api/get-vehicles-status-location-fuel-odometer-and-more)
- **Trip start and end locations**:
  - [Get all trips](https://developer.cartrack.com/docs/fleet-api/get-all-trips/)
  - [Get trips by registration](https://developer.cartrack.com/docs/fleet-api/get-trips-by-registration)

## 1) All GPS Positions

### What It Means

Retrieve historical position events over a period to reconstruct where a vehicle has been.

### Best Endpoints

- Single vehicle: [Get events for one vehicle](https://developer.cartrack.com/docs/fleet-api/get-events-for-one-vehicle)
- All vehicles: [Get events for all vehicles](https://developer.cartrack.com/docs/fleet-api/get-events-for-all-vehicles)

### Business Interpretation

- Use for investigations, trip replay, proof of presence, and operational audits.
- Best source when users ask for "all points" across a time window.

### Developer Interpretation

- Treat events as historical telemetry points.
- Query by time windows and paginate as needed.
- For long periods, fetch in chunks to avoid very large responses.

### Recipe: Retrieving a GPS Breadcrumb Trail (Waypoints) for a Trip

Use this recipe to get the dense GPS trail (waypoints) for a single trip, rather than every event type mixed together.

1. **Get the trip's time window.** Call [Get trips by registration](https://developer.cartrack.com/docs/fleet-api/get-trips-by-registration) (or [Get all trips](https://developer.cartrack.com/docs/fleet-api/get-all-trips/)) for the date range you care about, and read `start_timestamp`/`end_timestamp` off the trip you want:

   ```
   GET /trips/{registration}?start_timestamp=2022-01-01 08:00:00&end_timestamp=2022-01-01 20:00:00
   ```

   ```json
   {
     "data": [
       {
         "trip_id": 123456,
         "registration": "ABX123",
         "start_timestamp": "2022-01-01 08:12:00",
         "end_timestamp": "2022-01-01 08:49:00"
       }
     ]
   }
   ```

2. **Fetch the periodic GPS pings for that window.** Call [Get events for one vehicle](https://developer.cartrack.com/docs/fleet-api/get-events-for-one-vehicle) using the trip's `start_timestamp`/`end_timestamp`, filtered to `terminal_event_type_id=2` (`PERIODIC_EVENT`). This excludes discrete events like ignition, geofence, or harsh braking, and returns just the dense position pings that make up the breadcrumb trail:

   ```
   GET /vehicles/{registration}/events?start_timestamp=2022-01-01 08:12:00&end_timestamp=2022-01-01 08:49:00&terminal_event_type_id=2
   ```

   ```json
   {
     "data": [
       {
         "event_id": 123456,
         "registration": "ABX123",
         "terminal_event_type_id": 2,
         "event_description": "PERIODIC_EVENT",
         "latitude": 1.320227,
         "longitude": 103.889653,
         "event_ts": "2022-01-01 08:12:02+00:00"
       },
       {
         "event_id": 123457,
         "registration": "ABX123",
         "terminal_event_type_id": 2,
         "event_description": "PERIODIC_EVENT",
         "latitude": 1.320318,
         "longitude": 103.889801,
         "event_ts": "2022-01-01 08:12:34+00:00"
       }
     ]
   }
   ```

   Each result is one waypoint on the trail. Points are typically spaced a few seconds to about a minute apart, depending on vehicle speed and hardware configuration.

## 2) Continuous Tracking (Near Real-Time)

### What It Means

Show the latest known vehicle positions continuously, similar to a live fleet map.

### Best Endpoint

- [Get vehicles status, location, fuel, odometer and more](https://developer.cartrack.com/docs/fleet-api/get-vehicles-status-location-fuel-odometer-and-more)

### Business Interpretation

- Use for day-to-day live operations and dispatcher monitoring.
- Best for "where is the vehicle now?" use cases.

### Developer Interpretation

- Implement polling (for example every 10 to 30 seconds) to refresh latest states.
- This is near real-time status polling, not a websocket streaming feed.
- Combine with events endpoints when historical breadcrumb detail is required.

## 3) Full Trip History

### What It Means

Depending on your use case, "trip history" can mean either:

- Full breadcrumb points of a journey (also called waypoints or a GPS trail), or
- Trip summaries with start and end locations.

### Endpoint Selection

- For **full breadcrumb trip points (waypoints/trail)**: use the events endpoints, filtered to `terminal_event_type_id=2`. See [Retrieving a GPS Breadcrumb Trail (Waypoints) for a Trip](#recipe-retrieving-a-gps-breadcrumb-trail-waypoints-for-a-trip) above.
- For **trip-level start and end locations**:
  - [Get all trips](https://developer.cartrack.com/docs/fleet-api/get-all-trips/)
  - [Get trips by registration](https://developer.cartrack.com/docs/fleet-api/get-trips-by-registration)

### Business Interpretation

- Use trips for reporting and KPI-level trip analysis.
- Use events when analysts need path-level detail.

### Developer Interpretation

- Trips are summary records and should not be treated as complete trip-point datasets.
- Build full trip replay from events data for the selected time interval.

## Recommended Implementation Pattern

For most fleet applications:

1. Poll the vehicle status endpoint for current map state.
2. Query events endpoints for historical trip playback.
3. Query trips endpoints for trip reporting (start/end and trip context).

---

# Vehicle Sensors Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/vehicle-sensors-services

This page explains the vehicle sensor timeline available in the Fleet API, which sensors are supported, and how to retrieve historical sensor readings.

## Supported Sensors

The sensor timeline endpoint supports the following sensor types:

| Sensor | `filter[sensor]` value | Description |
|--------|------------------------|-------------|
| Fuel (CAN bus) | `FUEL` | Fuel level reported via the vehicle's CAN bus |
| EV Battery | `EV_BATTERY` | State of charge for electric vehicles |
| EV Charging Status | `EV_BATTERY_CHARGING_STATUS` | Whether the vehicle is currently charging |
| EV Range | `EV_RANGE` | Estimated remaining range for electric vehicles |
| EV Consumption | `EV_CONSUMPTION` | Energy consumption for electric vehicles |
| Taxi | `TAXI` | Taximeter state, available for supported taxi operators |

:::warning
Sensor availability depends on the hardware installed in the vehicle and the sensors configured for the account. If a sensor is not configured, the endpoint returns no data for that vehicle. Contact your Cartrack account manager if you are unsure which sensors are active.
:::

## Which Endpoint Should I Use?

Use the following endpoint to retrieve sensor timeline data for a single vehicle:

- Single vehicle: [Get sensor timeline for one vehicle](https://developer.cartrack.com/docs/fleet-api/get-sensor-timeline-for-one-vehicle)

## How to Retrieve Sensor Timeline Data

1. Identify the vehicle registration and the sensor type you want to query.
2. Choose a time range. The range between `filter[start_timestamp]` and `filter[end_timestamp]` cannot exceed 31 days.
3. Call `GET /vehicles/{registration}/sensors/timeline` with `filter[sensor]`, `filter[start_timestamp]`, and `filter[end_timestamp]`.
4. Use the `value` and `raw_value` fields in each record to interpret the sensor state (see below).
5. Paginate through results using the `page` and `limit` parameters if the response spans multiple pages.

## Understanding the Response

Each record in the response contains:

| Field | Type | Description |
|-------|------|-------------|
| `sensor_id` | integer | Internal sensor type identifier |
| `sensor_name` | string | Human-readable sensor name |
| `sensor_no` | integer | Sensor number assigned to the vehicle |
| `sensor_type` | string | `analog` or `digital` |
| `event_ts` | string | Timestamp of the sensor reading |
| `raw_value` | string | The literal value reported by the sensor hardware |
| `value` | string | A numeric index mapped from `raw_value` (see country-specific notes below) |

For most sensors, `raw_value` is the primary field to use. The `value` field is a positional index into a fixed mapping table defined per sensor type and is most relevant for sensors that report named states (such as the Taxi sensor).

## Country-Specific Notes

### Portugal — Taxi sensor

Portuguese taxi operators use a taximeter sensor (`sensor_no` 901) connected to the Cartrack device. The taximeter sends state codes as strings; the API maps these to a numeric `value` index for consistency.

| `value` | `raw_value` | Meaning |
|---------|-------------|---------|
| `0` | `DESLIGADO` | Taximeter off / out of service |
| `1` | `LIVRE` | Free / available for hire |
| `2` | `1` | Hardware-specific taximeter code |
| `3` | `3` | Hardware-specific taximeter code |
| `4` | `5` | Hardware-specific taximeter code |
| `5` | `6` | Hardware-specific taximeter code |
| `6` | `C` | Hardware-specific taximeter code |
| `7` | `P` | Hardware-specific taximeter code |
| `8` | `-` | Unknown / no data |

`DESLIGADO` (off) and `LIVRE` (free) are the standard, well-understood states. The exact meaning of the hardware-specific codes (`1`, `3`, `5`, `6`, `C`, `P`) depends on the taximeter model and should be confirmed with the taximeter vendor.

---

# Vehicle Temperature Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/vehicle-temperature-services

This page explains how vehicle temperature data is reported through the Fleet API, covering the available temperature sources, which endpoints to use for different use cases, and how temperature alerts are delivered.

## Temperature Sources

The Fleet API exposes two categories of temperature data:

| Category | Fields | Where it comes from |
|----------|--------|---------------------|
| Cargo / cabin temperature probes | `temp1`, `temp2`, `temp3`, `temp4` | Up to four external temperature sensors wired to the Cartrack device, commonly used for refrigerated transport and cold chain monitoring |
| Engine and unit temperatures | `water_temp` (coolant), `oil_temp`, `unit_temp` | Read from the vehicle's CAN bus (coolant and oil) or from the Cartrack device itself (unit temperature) |

All temperature values are returned in **Celsius** as decimal numbers. A field is `null` when the corresponding sensor is not fitted or not reporting.

:::warning
Temperature sensor availability depends on the hardware installed in the vehicle. If no temperature probes are fitted, the `temp1` to `temp4` fields return `null`. Contact your Cartrack account manager if you are unsure which sensors are installed on your fleet.
:::

## Which Endpoint Should I Use?

Use this mapping based on what you want to accomplish:

| Goal | Endpoint |
|------|----------|
| Get the latest temperature reading for all vehicles | [Get Vehicles Temperature Data](https://developer.cartrack.com/docs/fleet-api/get-vehicles-temperature-data) |
| Get historical temperature readings for a period | [Get Vehicles Temperature Data](https://developer.cartrack.com/docs/fleet-api/get-vehicles-temperature-data) |
| Get temperature together with position, fuel, and odometer in one call | [Get Vehicles Status](https://developer.cartrack.com/docs/fleet-api/get-vehicles-status-location-fuel-odometer-and-more) |
| Get engine coolant and oil temperature per event | [Get Events for All Vehicles](https://developer.cartrack.com/docs/fleet-api/get-events-for-all-vehicles) / [Get Events for One Vehicle](https://developer.cartrack.com/docs/fleet-api/get-events-for-one-vehicle) |
| Retrieve triggered temperature alert notifications | [Get Alerts Notifications](https://developer.cartrack.com/docs/fleet-api/get-alerts-notifications) |

## 1) Dedicated Temperature Endpoint

### What It Means

`GET /topics/vehicles/temperature` is the recommended endpoint for temperature monitoring. It returns the readings from the four temperature probes for all vehicles in the account, and operates in two modes:

- **Latest mode**: omit both `filter[start_timestamp]` and `filter[end_timestamp]` to get the most recent temperature reading per vehicle, provided data was reported within the last 2 months.
- **History mode**: provide a time range to get all readings within it. The range is limited to a maximum **24-hour** period. If only one timestamp is given, the other defaults to 24 hours before or after it.

Use `filter[registration]` to restrict the response to a single vehicle.

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `vehicle_id` | integer | Cartrack vehicle identifier |
| `registration` | string | The vehicle's registration |
| `temp1` to `temp4` | number or null | Temperature reading from sensors 1 to 4, in Celsius |
| `event_ts` | string | When the reading was recorded by the device |
| `recieved_ts` | string | When the reading was received by Cartrack |

If `recieved_ts` is significantly later than `event_ts`, the vehicle was likely in an area with poor network coverage and the data was transmitted with a delay. Keep this in mind when monitoring time-sensitive cold chain thresholds.

### Sub-User Access

This endpoint supports Topic-Based Access Control. Grant the `TEMPERATURE` topic to a sub-user to give it the same temperature data access as the account administrator, without exposing the rest of the account.

### Developer Considerations

- History queries are limited to 24 hours per request. For longer periods, issue multiple requests with consecutive windows.
- Results are paginated: use the `page` and `limit` parameters to iterate through large fleets.
- In latest mode, vehicles that have not reported temperature data in the last 2 months are not returned.

## 2) Temperature in Vehicle Status

`GET /vehicles/status` includes the `temp1` to `temp4` fields as part of each vehicle's last known state, alongside position, ignition, fuel, and odometer. This is a point-in-time snapshot, not a history.

Use it when you already poll vehicle status for a live dashboard and want to display current temperatures without an extra API call.

## 3) Engine Temperatures via Events

The events endpoints (`GET /vehicles/events` and `GET /vehicles/{registration}/events`) return the full event stream from the vehicle. Each event includes the probe readings plus the engine-related temperatures:

| Field | Description |
|-------|-------------|
| `temp1` to `temp4` | Temperature probes 1 to 4, in Celsius |
| `water_temp` | Engine coolant temperature, in Celsius |
| `oil_temp` | Engine oil temperature, in Celsius |
| `unit_temp` | Internal temperature of the Cartrack device, in Celsius |

Engine coolant and oil temperatures depend on CAN bus support for the vehicle model and return `null` when not available.

## 4) Temperature Alerts

Temperature-related alerts are configured on the account (through Fleetweb or your Cartrack account manager) and can then be retrieved through the API:

1. Call [Get Alerts Notification Types](https://developer.cartrack.com/docs/fleet-api/get-alerts-notification-types) to list the alert types available on your account. Temperature-related types include `COOLANT_TEMPERATURE`, `ENGINE_TEMPERATURE`, `TEMPERATURE_DIAGNOSTIC`, and the geofence-scoped probe alerts `GEOFENCE_ALERTS_TEMP1_HIGH_WITH_IGNITION_ON` to `GEOFENCE_ALERTS_TEMP4_LOW_WITH_IGNITION_ON` (a high and a low variant per probe).
2. Call [Get Alerts Notifications](https://developer.cartrack.com/docs/fleet-api/get-alerts-notifications) with `filter[alert_type]` set to the relevant type to retrieve the triggered notifications for a period (limited to 31 days per request).

:::info
Creating temperature alerts through the API is not currently supported. The alert creation endpoints cover other alert types (geofence, ignition, and [PTO and panic sensors](https://developer.cartrack.com/docs/fleet-api/create-sensor-alert)); temperature thresholds are configured on the account itself.
:::

## Recommended Integration Pattern

1. For **cold chain monitoring**: poll `GET /topics/vehicles/temperature` in latest mode at your refresh interval, and compare `temp1` to `temp4` against your thresholds. Check `event_ts` to make sure the reading is recent before acting on it.
2. For **temperature history and auditing**: pull `GET /topics/vehicles/temperature` with consecutive 24-hour windows and store the readings on your side.
3. For **live fleet dashboards**: read the `temp1` to `temp4` fields from `GET /vehicles/status`, which you likely already poll for positions.
4. For **threshold breach notifications**: configure temperature alerts on the account, then poll `GET /alerts/notifications` filtered by the temperature alert types.
5. For **engine health monitoring**: use the events endpoints and track `water_temp` and `oil_temp` over time.

---

# Vehicle Events Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/vehicles-events-services

This page explains the vehicle events available in the Fleet API and how to retrieve them.

## Acronyms and Terms

- **API**: Application Programming Interface.
- **GPS**: Global Positioning System.

## Which Endpoint Should I Use?

Use these endpoints to retrieve event data:

- Single vehicle: [Get events for one vehicle](https://developer.cartrack.com/docs/fleet-api/get-events-for-one-vehicle)
- All vehicles: [Get events for all vehicles](https://developer.cartrack.com/docs/fleet-api/get-events-for-all-vehicles)

## How to Retrieve Vehicle Events

1. Choose whether you need data for one vehicle or all vehicles.
2. Query the events endpoint for the required time range.
3. Use `terminal_event_type_id` and `event_description` to identify the event type.
4. Map event IDs in responses using the table below.

## Vehicle Event Types

:::warning Important Disclaimer
The events reported depend on the hardware installed in the vehicle, third-party data availability, and the installation procedure. If you have any questions, please request clarification from your Cartrack account manager during onboarding.
:::

_Interactive content, see https://developer.cartrack.com/docs/fleet-api-general/services/vehicles-events-services_

---

# Vision Services

Source: https://developer.cartrack.com/docs/fleet-api-general/services/vision-services

This page explains how to interact with Cartrack Vision cameras through the Fleet API, covering video clip requests, status tracking, livestreaming, and custom camera uploads.

:::warning Vision API subscription required
This service is available exclusively for accounts with the **Cartrack Vision API** option enabled. If you receive HTTP 403, contact your Cartrack customer success manager to enable access. After activation, allow 5 to 10 minutes for the configuration to propagate before making API calls.
:::

## Which Endpoint Should I Use?

Use this mapping based on what you want to accomplish:

| Goal | Endpoint |
|------|----------|
| Request a video clip from a vehicle camera | [Create Video Requests](https://developer.cartrack.com/docs/fleet-api/create-video-requests) |
| Retrieve downloaded video clips | [Get Video Requests](https://developer.cartrack.com/docs/fleet-api/get-video-requests) |
| Check the processing status of video requests | [Get Video Requests Status](https://developer.cartrack.com/docs/fleet-api/get-video-requests-status) |
| Get a real-time livestream link for a vehicle | [Video Livestream Requests](https://developer.cartrack.com/docs/fleet-api/video-livestream-requests) |
| Check whether a vehicle's cameras are currently online | [Get Vision Camera Online Status](https://developer.cartrack.com/docs/fleet-api/get-vision-camera-online-status) |
| Upload a single video from a custom camera device | [Upload Video](https://developer.cartrack.com/docs/fleet-api/upload-video) |
| Upload multiple videos from custom camera device(s) | [Bulk Upload Videos](https://developer.cartrack.com/docs/fleet-api/bulk-upload-videos) |

## 1) Requesting and Retrieving Video Clips

### How It Works

A video request is not an immediate download. When you submit a request, you are instructing the camera device to locate the requested footage on its local storage and upload it to the Cartrack server. The clip only becomes available to download once the camera has completed that upload.

This means the full flow depends on two things outside the API's control: the camera must be online with sufficient network coverage, and the requested footage must still exist on the device's local storage. If the camera has poor or no connectivity at the time of the request, it will retry automatically and the clip will remain in Pending until it can be fully uploaded.

### How Video Requests Are Created

Video requests can be created from three different sources. `GET /vision/videos/requests` returns all requests regardless of origin. You will see requests you did not create via the API.

| Source | How |
|--------|-----|
| Fleet API | `POST /vision/videos/requests` (programmatic, from your integration) |
| Camera AI | Automatic. The DVR triggers a request when it detects a configured event (fatigue, distraction, cell phone usage, etc.) |
| Fleetweb | Manual. A fleet operator requests a clip through the web portal |

### Clip Lifecycle

After a request is created, its `status_id` progresses through several states. The `url` field is `null` until the clip reaches status `3` (Complete).

```mermaid
sequenceDiagram
    participant Origin as API / Fleetweb / Camera AI
    participant API as Fleet API
    participant Cam as DVR Camera

    Origin->>API: Create video request
    API-->>Origin: status_id: 1 (Pending), url: null

    loop Poll GET /vision/videos/requests
        Origin->>API: Check status_id
        API-->>Origin: status_id: 1 or 2, url: null
    end

    Note over Cam: Camera comes online with network coverage
    API->>Cam: Request footage segment
    Cam->>API: Upload footage
    API-->>API: status_id → 3, url populated

    Origin->>API: GET /vision/videos/requests
    API-->>Origin: status_id: 3 (Complete), url: "https://..."
```

Key status codes to handle in your integration:

| status_id | Label | Meaning |
|-----------|-------|---------|
| 1 | Pending | Request queued, waiting for camera to upload |
| 2 | In Progress | Camera is uploading the footage |
| 3 | Complete | Footage is ready. `url` is populated |
| 5 | Does Not Exist | Requested time range not found on camera storage |
| 6 | Timeout | Camera did not respond within the allowed window |

### Downloading the Clip

Once a request reaches `Complete`, its `url` is a ready-to-use link to the footage. The URL is **durable** - fetch it immediately, or store it in your own system and retrieve it later. Treat the URL as **opaque**: do not parse it or depend on its host or path structure.

If your application plays the clip back in a browser rather than just downloading it, the same origin restriction described under [Browser Playback and CORS](#browser-playback-and-cors) applies. Fetch the clip through your own backend and re-serve it to your frontend rather than pointing browser JS at the `url` directly.

### Limitations

**Network coverage.** The camera must be online and have sufficient network connectivity to upload footage. If the vehicle is in a low-coverage area when the request is placed, it will remain in Pending until coverage is restored. There is no guarantee of when, or whether, that happens.

**FIFO local storage.** DVR cameras store footage locally with a fixed capacity. When storage is full, the oldest footage is overwritten. If you place a request for footage from several days ago and the camera has been recording continuously since, that segment may no longer exist on the device. This results in a `Does Not Exist` (status 5) or `Timeout` (status 6) outcome. Request footage as soon as possible after the event of interest.

### Polling Pattern

To track a clip from creation to completion, poll `GET /vision/videos/requests` and inspect the `status_id` field on each request. Poll at a reasonable interval; every 30 to 60 seconds is sufficient. Stop polling when `status_id` reaches a terminal state (`3`, `5`, or `6`).

`GET /vision/videos/status` is a static reference table that returns the full list of status codes and their descriptions. It is not a per-request status endpoint and does not need to be polled.

## 2) Video Livestream

### What It Means

Request a real-time livestream link for a specific vehicle. The API returns a URL your application can use to display a live camera feed.

### Response

The response is an HTTP `200` with two arrays: `data` (cameras that started streaming) and `failed_cameras` (cameras that could not, each with a `status` and a human-readable `message`). A request can partially succeed, so **`200` does not mean every camera is streaming** - always read both arrays. Even when every requested camera fails, the HTTP status is still `200` with an empty `data` array; a non-`200` means the request itself failed, not an individual camera.

Each entry in `data` carries an `is_hls` flag: `true` when its `url` is an HLS playlist, `false` for a WebSocket stream. The streaming format is fixed per account, so all cameras in a response share the same `is_hls` value.

For HLS streams, each `data` entry also includes an `expires_at` timestamp for when that URL stops working; request a fresh livestream before then to keep watching. WebSocket entries have `expires_at: null`. Treat the `url` as opaque and do not depend on its host or path.

### Error: Camera Not Online

If the vehicle's DVR camera is currently offline, the API returns HTTP `409`:

```json
HTTP 409
{"error":{"code":409,"message":"Livestream unavailable: Digital Video Recorder is offline"}}
```

This indicates the camera device itself is unreachable; the Fleet API is functioning normally. A `409` here is a device-state conflict, not a server error, so **do not retry it in a loop.** Surface it to the user as a camera availability issue and let them decide when to retry.

To avoid the `409` altogether, check the camera's current state with `GET /vision/status` before requesting a livestream. See [Camera Online Status](#4-camera-online-status).

### Developer Considerations

- Livestream links are short-lived. For HLS streams, `expires_at` tells you exactly when a URL stops working; request a fresh one before then. Do not cache links across sessions, and treat them as opaque (do not depend on host or path).
- The link is tied to the vehicle registration passed in the path (`/vision/livestream/{registration}`).
- If a vehicle has multiple cameras, the response may include multiple stream links in `data`, and any that could not start in `failed_cameras`.
- Handle `409` from this endpoint as a camera state issue, not a server failure. Do not retry it in a loop; let the user trigger the retry manually.

### Browser Playback and CORS

The livestream `url` is meant to be relayed through your own backend, not handed directly to browser JavaScript (hls.js, Video.js, a `<video>` tag) on your own website. The streaming backend enforces an origin check on the actual media request, separate from the URL itself. A request with no `Origin` header, or an `Origin` on `*.cartrack.com`, succeeds; any other `Origin` is rejected with `403` and no CORS header - which browsers surface as an opaque CORS failure rather than a readable error.

There is currently no self-service way to get your domain allowed for direct browser playback. Fetch the `.m3u8` playlist and its segments server-side and re-serve them to your own frontend, so the browser stays same-origin against your own domain. Do not assume cross-origin browser playback will work without prior arrangement.

## 3) Uploading Video from Custom Camera Devices

### What It Means

If your fleet uses third-party camera hardware that is not a native Cartrack Vision device, you can push recorded video into Cartrack Vision using the upload endpoints. This allows non-Cartrack cameras to be integrated into the same video management workflow.

### Single vs. Bulk Upload

- **Single upload** (`POST /vision/video/upload`): Upload one video file per request. Best for real-time or low-volume ingest.
- **Bulk upload** (`POST /vision/video/bulk-upload`): Upload multiple video files in a single request. Best for batch ingest from a device that stores footage locally and syncs periodically.

### Developer Considerations

- Ensure the vehicle registration in the upload payload matches an active contract with the Vision API VAS enabled, or the upload will be rejected.
- For bulk uploads, treat each file's result individually — a partial failure does not necessarily reject the entire batch.
- Validate file format and size requirements against the API schema before uploading to avoid unnecessary rejections.

## 4) Camera Online Status

### What It Means

`GET /vision/status` returns the current online state of the Vision cameras on the account, one entry per camera-capable vehicle. Use it to find out whether a camera can be reached right now, before placing a video request or asking for a livestream.

### Status Values

| status | Meaning |
|--------|---------|
| `online` | The device is connected and at least one camera channel is currently active |
| `offline` | The device is connected with no active channel, is not currently reporting status, or has never sent status data |
| `standby` | The device is connected but idle. This is a normal state, not a fault |

Each entry also carries a `cameras` array giving the per-channel state, so a vehicle can be `online` overall while one of its channels is not.

A vehicle appears in the response as soon as its hardware is camera-capable, even if its device has never reported a status. In that case `status` is `offline` and `cameras` is an empty array, because the number of channels on the device is not known yet. A vehicle whose hardware has no camera at all is never returned.

### Filtering

The response covers the whole account by default and is paginated with `filter[page]` and `filter[limit]`. Narrow it with:

| Filter | Behavior |
|--------|----------|
| `filter[vehicle_id]` | Exact vehicle ID |
| `filter[registration]` | Case-insensitive exact match, not a partial match |
| `filter[status]` | `online`, `offline` or `standby`, case-insensitive |
| `filter[camera_id]` | A single channel from `1` to `8`, instead of every channel |

`filter[camera_id]` behaves differently from the others. A vehicle whose device is not known to have that channel installed is dropped from the response entirely, even though it would have appeared as `offline` without the filter. So an absent vehicle under this filter means "no such channel", not "channel offline".

### Streaming Protocol Support

This endpoint currently supports accounts on the HLS video streaming protocol only. An account on the WebSocket protocol receives HTTP `422`. Support for WebSocket accounts is planned for a future release. The protocol is fixed per account, so this is an account-level outcome rather than something that varies per request.

### Developer Considerations

- The endpoint is rate limited to 6 requests per minute, which is stricter than most of the API. See [Rate Limiting](https://developer.cartrack.com/docs/fleet-api-general/rate-limiting). Set `limit` as high as your fleet needs (up to the max of `1000`) and filter client-side rather than polling per vehicle — at 6 requests/minute, paging through more than a page or two per check eats your whole budget fast.
- Treat this as a point-in-time reading. A camera can drop off between the status check and the livestream request, so still handle the livestream `409`.
- `standby` is not an error. Do not surface it to users as a fault.
- An `offline` vehicle with an empty `cameras` array has simply never reported. It is not the same as a device that reported every channel down, and it is worth distinguishing in your UI.

## Recommended Integration Pattern

1. Confirm the Vision API VAS is active on the target account before integrating (test with any Vision endpoint; a 403 means the VAS is not yet configured).
2. Check camera availability with `GET /vision/status` before acting on a specific vehicle, so a request is not placed against a device that cannot answer.
3. For clip retrieval: submit the request, poll for status, then fetch the clip once it reaches a ready state.
4. For livestream: request a fresh link per session and do not reuse expired links.
5. For custom camera uploads: match video metadata (vehicle registration, timestamp) precisely to ensure footage is correctly associated in the Cartrack platform.

---

# Use Cases

Source: https://developer.cartrack.com/docs/fleet-api-general/use-cases

The Cartrack Fleet API offers a diverse range of services designed to cater to various operational needs across your fleet management spectrum. Below are a few use cases for our API, segmented by themes to help you understand how you can integrate these into your systems for better fleet oversight and enhanced operational efficiency:

## Vehicle Management, Fuel Monitoring, Trip Reporting, and Events

- **Vehicles API**: Gain real-time data on your fleet, including vehicle status updates, locations, and operational metrics. For instance, use the `/vehicles/status` endpoint for a comprehensive overview of all your vehicles, helping you monitor their condition and availability.
- **Trips API**: Access detailed trip data such as route information, driving behaviors, and idle times. This API is invaluable for tracking driver performance and vehicle usage, essential for optimizing routes and improving fuel efficiency.
- **Fuel API**: Monitor fuel levels and usage across your fleet. Whether you are gathering data directly from the CAN bus or using analog sensors, the fuel API helps you track fuel consumption accurately, manage costs, and prevent fuel fraud. See [Fuel Services](/docs/fleet-api-general/services/fuel-services) for detailed concepts and endpoint mapping.
- **Driver Identification Services**: Understand how drivers are associated to vehicles using default assignment, RFID driver tags, mobile app assignment, and linkage APIs. See [Driver Identification Services](/docs/fleet-api-general/services/driver-identification-services) for driver-resolution behavior and endpoint mapping.
- **Positions and Trip Services**: Retrieve live location state, historical GPS positions, and trip start/end location information. See [Positions and Trip Services](/docs/fleet-api-general/services/positions-route-services) for endpoint mapping by use case.
- **Vehicle Events Services**: Understand event types emitted by vehicles and how to retrieve them from events endpoints. See [Vehicle Events Services](/docs/fleet-api-general/services/vehicles-events-services) for the complete event-type table and integration guidance.
- **Vehicle Sensors Services**: Retrieve the historical timeline of sensor readings for a vehicle, filtered by sensor type and time range. Useful for auditing, reporting, and dashboards. See [Vehicle Sensors Services](/docs/fleet-api-general/services/vehicle-sensors-services) for supported sensors and integration guidance.
- **Mileage and Odometer Services**: Track total distance travelled per vehicle over any period, retrieve per-trip distance breakdowns, and read current odometer values. Understand the difference between CAN bus and GPS-derived odometer data and how to handle odometer resets. See [Mileage and Odometer Services](/docs/fleet-api-general/services/mileage-odometer-services) for endpoint mapping and integration guidance.
- **Vehicle Temperature Services**: Monitor cargo temperature probes and engine temperatures across your fleet, retrieve latest or historical readings, and receive temperature alert notifications. Ideal for refrigerated transport and cold chain compliance. See [Vehicle Temperature Services](/docs/fleet-api-general/services/vehicle-temperature-services) for endpoint mapping and integration guidance.

## Remote Vehicle Interaction

- **Commands API**: Send commands directly to vehicles for functions like locking or unlocking doors, an essential feature for enhancing vehicle security and operational flexibility. The type of commands available can vary based on the hardware installed in your vehicles.

## Geofencing for Asset Management

- **Geofences API**: Define virtual perimeters for real-time monitoring of your assets. Track your vehicles as they enter or leave designated areas, helping you manage asset utilization, secure vehicles, and optimize operational zones. (`/geofences[...]`)

## Delivery Management

- **Delivery Job Services**: Create delivery jobs from ERP or dispatch systems with clear confirmation patterns for both batch and single-job flows. See [Delivery Job Services](/docs/fleet-api-general/services/delivery-job-services) for endpoint mapping and failure-handling guidance.

## Video and Camera Management

- **Vision Services**: Request recorded video clips from Cartrack Vision cameras, track clip processing status, retrieve livestream links, and upload footage from custom third-party camera devices. Note that Vision API access requires the **Cartrack Vision API** option to be enabled on the account — contact your Cartrack customer success manager if you receive HTTP 403. See [Vision Services](/docs/fleet-api-general/services/vision-services) for endpoint mapping and integration guidance.

## Fleet Cost Management with MiFleet

- **MiFleet Services API**: Utilize advanced analytics and business intelligence to reduce operational costs and enhance decision-making. Monitor and manage expenses related to accidents, insurance, maintenance, and more. Note that MiFleet is an add-on service requiring an additional subscription. (`/mifleet[...]`)

These use cases are just the tip of the iceberg. Each API is designed to provide specific functionalities that can be integrated into your existing systems, providing you with the tools you need to manage your fleet more effectively. Whether you're a developer tasked with enhancing fleet system integrations or a business manager looking to streamline operations, Cartrack’s Fleet API is your gateway to a smarter fleet management solution.

---

# Webhooks

Source: https://developer.cartrack.com/docs/fleet-api-general/webhook-notification

The Cartrack Fleet API provides webhook notifications to allow your system to receive real-time updates for various events. Webhooks enable seamless integration by automatically pushing event data to your specified endpoint whenever an event occurs.

### Supported Webhook Flows

As of today, the API supports a limited set of webhook events. Webhooks are not available for all system events.

Currently supported webhook flow:

- <strong>Bulk Upload Delivery Jobs</strong>: Triggered when the jobs creation process is completed

No other webhook events or data schemas are supported at this time. Additional webhook flows may be introduced in future releases.

### Security and Verification

All webhook requests sent from Cartrack will include the X-Webhook-Signature HTTP header. This signature allows you to verify that the request is genuinely from Cartrack and has not been tampered with.

The signature is generated using the HMAC-SHA256 algorithm with the following components:

- Secret Key: Your API key.
- Payload: The raw JSON request body (as a string before any decoding or parsing).

#### Signature Generation Process

1. Encode the JSON payload (raw content) as a UTF-8 string.
2. Hash the payload using HMAC-SHA256 with your API key as the secret.

Example (PHP):

```php
$secret = 'your_api_key';
$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', json_encode($payload), $secret);   

if (hash_equals($signature, $_SERVER['X-Webhook-Signature'])) {
    // Verified request
} else {
    // Invalid signature
}
```

It is recommended to always verify the webhook signature before processing any webhook request to ensure data integrity and security.

---

# Introduction

Source: https://developer.cartrack.com/docs/introduction

Welcome to Cartrack's developer documentation. This site gives you the exact information needed to connect to our fleet platform and to build secure vehicle-access experiences.

We currently provide three integration options:

- **[Fleet API](/docs/fleet-api-general/overview)** — for programmatic fleet operations such as tracking, commands, and data retrieval.
- **[Mobile SDKs (Android and iOS)](/docs/mobile-sdks/overview)** — for secure, Bluetooth-based vehicle access and telemetry in your mobile apps.
- **[Telematics API](/docs/telematics-data-ingestion/overview)** — for delivering telematics events from your own devices or platform into Cartrack. Currently in beta and enabled for a limited number of partners and customers.

What you can expect:

- Clear prerequisites, authentication flows, and environment details up front.
- Versioned REST APIs with changelog visibility so you know when behavior shifts.
- SDK implementation guidance focused on reliability, offline handling, and secure key management.
- Example requests and responses that reflect real-world payloads.

If something is unclear or missing, please raise an issue through your account team so we can address it quickly.

---

# BleAction

Source: https://developer.cartrack.com/docs/mikey-android/ble-action

**Enum Class**: `BleAction`

Represents action that can be instructed to peripheral

## Properties

### name: String
Represents as a callback to show the result from the BleTerminal process.

### ordinal: Int
Represents current connected terminalId.

## Available Actions

### LOCK
```kotlin
LOCK
```
Send lock action to terminal

### UNLOCK  
```kotlin
UNLOCK
```
Send unlock action to terminal

### UNLOCK_NOKEYFOB
```kotlin
UNLOCK_NOKEYFOB
```
Send unlock with no key fob action to terminal

### HEADLIGHT
```kotlin
HEADLIGHT  
```
Send headlight action to terminal

### HORN
```kotlin
HORN
```
Send horn action to terminal

### GET_LOCK_STATE
```kotlin
GET_LOCK_STATE
```
Get the current state of vehicle's lock status - possible value - Lock/Unlock

### VEHICLE_GET_CONFIG
```kotlin
VEHICLE_GET_CONFIG
```
Get the current state of vehicle's status

### VEHICLE_GET_STATUS
```kotlin
VEHICLE_GET_STATUS
```
Get the current state of vehicle's ignition status - possible value - on/off

## Functions

### valueOf(value: String): BleAction
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

**Throws** IllegalArgumentException if this enum type has no constant with the specified name

### values(): `Array<BleAction>`
Returns an array containing the constants of this enum type, in the order they're declared. This method may be used to iterate over the constants.

## Action Categories

### Control Actions
- `LOCK` - Lock the vehicle doors
- `UNLOCK` - Unlock the vehicle doors  
- `UNLOCK_NOKEYFOB` - Unlock without requiring key fob presence

### Signaling Actions
- `HEADLIGHT` - Flash vehicle headlights
- `HORN` - Sound vehicle horn

### Status Actions
- `GET_LOCK_STATE` - Retrieve current lock/unlock status
- `VEHICLE_GET_CONFIG` - Get comprehensive vehicle statistics
- `VEHICLE_GET_STATUS` - Get vehicle ignition and status information

## See Also

- [BleTerminal](./ble-terminal.md) - For sending actions
- [BleListener](./ble-listener.md) - For handling action results
- [LockState](./lock-state.md) - For lock state values

---

# BleConnectionState

Source: https://developer.cartrack.com/docs/mikey-android/ble-connection-state

**Enum Class**: `BleConnectionState`

Represents BLE Connection State

## Properties

### name: String

### ordinal: Int

## Connection States

### CONNECTED
```kotlin
CONNECTED
```
Ble Terminal has connected to the device and ready to send action

### DISCONNECTED
```kotlin
DISCONNECTED  
```
Ble Terminal is disconnected

### CONNECTING
```kotlin
CONNECTING
```
Ble Terminal is in the process of connecting

## Functions

### valueOf(value: String): BleConnectionState
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

**Throws** IllegalArgumentException if this enum type has no constant with the specified name

### values(): `Array<BleConnectionState>`
Returns an array containing the constants of this enum type, in the order they're declared.

## See Also

- [BleTerminal](./ble-terminal.md) - For connection methods
- [BleListener](./ble-listener.md) - For connection callbacks

---

# BleError

Source: https://developer.cartrack.com/docs/mikey-android/ble-error

**Sealed Class**: `BleError`

Error Handler related to BLE Connection

## Properties

### actionCode: Int
Action code associated with the error

### errorCode: Int  
Error code identifier

### localizedDescription: String
Human-readable description of the error

## Parameters

- `errorCode` - Error code identifier
- `localizedDescription` - Human-readable error description  
- `actionCode` - Action code associated with the error

## Error Types

### BluetoothDisabled
```kotlin
object BluetoothDisabled : BleError
```
- Bluetooth is disabled
- ErrorCode: 2
- Description: Phone: Bluetooth is disabled, please go to settings to enable it

### BluetoothUnauthorized  
```kotlin
object BluetoothUnauthorized : BleError
```
- Bluetooth permission is not granted. Ask user to grant permission from phone settings
- ErrorCode: 1
- Description: Phone: Bluetooth permission is not granted, please go to settings to grant permission

### BluetoothUnsupported
```kotlin
object BluetoothUnsupported : BleError  
```
- Device does not support Bluetooth Low Energy
- ErrorCode: 3
- Description: Phone: Device does not support Bluetooth Low Energy

### KeyInvalid
```kotlin
object KeyInvalid : BleError
```
- Authentication key in Shared Preference is invalid
- ErrorCode: 6
- Description: BLE: Authentication key is invalid

### KeyNotFound
```kotlin
object KeyNotFound : BleError
```
- Authentication key not found in Shared Preference
- ErrorCode: 5
- Description: Shared Preference: Authentication key not found

### LocationUnauthorized
```kotlin
object LocationUnauthorized : BleError
```
- Location permission is not granted
- ErrorCode: 9
- Description: Phone: Location permission is not granted, please go to settings - to grant permission

### NotConnected
```kotlin
object NotConnected : BleError
```
- Not connected to Ble Terminal. Call BleTerminal.connect() to connect first
- ErrorCode: 8
- Description: Not connected to Ble Terminal. Please connect first.

### SaveAuthKeyFailed
```kotlin
object SaveAuthKeyFailed : BleError
```
- Failed to save authentication key in Shared Preference
- ErrorCode: 4
- Description: Shared Preference: Failed to save the key in Shared Preference

### TerminalNotFound
```kotlin
object TerminalNotFound : BleError
```
- Unable to discover Ble Terminal, terminal might be out of range
- ErrorCode: 7
- Description: BLE Scan: Terminal not found

### CtgError
```kotlin
class CtgError(ctgError: CtgError?) : BleError
```
Failed due to Terminal action, refer to CtgError

### GattError
```kotlin
class GattError(gattError: GattError?) : BleError
```
Gatt Error. Called when BluetoothGatt onConnectionStateChange return other than GATT_SUCCESS.

## See Also

- [CtgError](./ctg-error.md) - Terminal-specific errors
- [GattError](./gatt-error.md) - GATT connection errors
- [BleListener](./ble-listener.md) - For error handling callbacks

---

# BleListener

Source: https://developer.cartrack.com/docs/mikey-android/ble-listener

**Interface**: `BleListener`

Represents a listener for events and state changes related to a BleTerminal. This interface provides methods that will be invoked by the BleTerminal to notify the listener about connection status, data received, errors, etc.

## Methods

#### onError(bleError: BleError)
```kotlin
abstract fun onError(bleError: BleError)
```
Called when an error occurs during a BleTerminal operation.

**Parameters:**
- `bleError` - The [BleError](./ble-error.md) that occurred.

#### onReconnect()
```kotlin
abstract fun onReconnect()
```
Called when bluetooth gatt return GATT_ERROR or GATT_FAILURE, after reconnect 3 times then return BleError.GATTError.

#### onRemoveAuthKeySuccess()
```kotlin
abstract fun onRemoveAuthKeySuccess()
```
Called when the authentication key is successfully removed.

#### onSaveAuthKeySuccess(terminal: BleTerminal, authKey: String)
```kotlin
abstract fun onSaveAuthKeySuccess(terminal: BleTerminal, authKey: String)
```
Called when the authentication key is successfully saved.

**Parameters:**
- `terminal` - The [BleTerminal](./ble-terminal.md) instance
- `authKey` - The authentication key that was saved.

#### onSignalStrength(strength: BleSignalStrength, rssiValue: Int)
```kotlin
abstract fun onSignalStrength(strength: BleSignalStrength, rssiValue: Int)
```
Called when the signal strength changes.

**Parameters:**
- `strength` - The new [BleSignalStrength](./ble-signal-strength.md).
- `rssiValue` - Raw RSSI value

#### onTerminalCommandResult(action: BleAction)
```kotlin
abstract fun onTerminalCommandResult(action: BleAction)
```
Called when a terminal command returns a result.

**Parameters:**
- `action` - The [BleAction](./ble-action.md) that was executed.

#### onTerminalConnected(terminal: BleTerminal)
```kotlin
abstract fun onTerminalConnected(terminal: BleTerminal)
```
Called when the [BleTerminal](./ble-terminal.md) successfully connects to a device.

**Parameters:**
- `terminal` - The [BleTerminal](./ble-terminal.md) that was connected.

#### onTerminalDisconnected(terminal: BleTerminal)
```kotlin
abstract fun onTerminalDisconnected(terminal: BleTerminal)
```
Called when terminal is disconnected.

**Parameters:**
- `terminal` - The [BleTerminal](./ble-terminal.md) that was connected.

#### onTerminalDidGetVehicleStats(command: Command, stats: GetVehicleStats)
```kotlin
abstract fun onTerminalDidGetVehicleStats(command: Command, stats: GetVehicleStats)
```
Called when fetching vehicle statistics.

**Parameters:**
- `command` - The command triggering the fetch operation.
- `stats` - The callback to receive the vehicle stat.

#### onTerminalDidGetVehicleStatus(command: Command, status: GetVehicleStatus)  
```kotlin
abstract fun onTerminalDidGetVehicleStatus(command: Command, status: GetVehicleStatus)
```
Called when fetching vehicle status.

**Parameters:**
- `command` - The command triggering the fetch operation.
- `status` - The callback to receive the vehicle status.

## Error Types

Common `BleError` types you may encounter:

- `BleError.KeyNotFound` - Authentication key not found
- `BleError.KeyInvalid` - Authentication key is invalid  
- `BleError.TerminalNotFound` - Terminal not in range or not discoverable
- `BleError.BluetoothDisabled` - Bluetooth is turned off
- `BleError.BluetoothUnauthorized` - Bluetooth permission not granted
- `BleError.LocationUnauthorized` - Location permission not granted
- `BleError.NotConnected` - Not connected to terminal
- `BleError.GattError` - GATT connection error
- `BleError.CtgError` - CTG device specific error

## See Also

- [BleTerminal](./ble-terminal.md) - For terminal operations
- [BleService](./ble-service.md) - For SDK initialization
- [Error Handling](./ble-error.md) - For detailed error information

---

# BleService

Source: https://developer.cartrack.com/docs/mikey-android/ble-service

**Class**: `BleService(context: Context)`

Serves as the main entry point for interacting with the Bluetooth Low Energy (BLE) SDK.

Before using any BLE functionality, you must initialize the SDK by calling `BleService.configure()`

## Types

### Companion
[object Companion](./ble-service.md#companion)

## Constructor

### BleService(context: Context)
Creates a new instance of BleService.

**Parameters:**
- `context` - The application context.

## Static Methods (Companion Object)

### configure()
```kotlin
fun configure(context: Context): BleService
```
Configures the BleService. This function should be called first.

### getTerminal(terminalId: String)
```kotlin
fun getTerminal(terminalId: String): BleTerminal
```
Get an instance of BleTerminal associated with the given terminal ID.

**Parameters:**
- `terminalId` - The unique identifier for the desired BLE terminal.

**Returns:** [BleTerminal](./ble-terminal.md) instance

### isConfigured()
```kotlin
fun isConfigured(): Boolean
```
Checks if the given [BleTerminal](./ble-terminal.md) instance is configured.

**Returns:** `true` if configured, `false` otherwise

### clear()
```kotlin
fun clear()
```
Clears the configured instance.

## See Also

- [BleTerminal](./ble-terminal.md) - For terminal operations
- [BleListener](./ble-listener.md) - For handling callbacks

---

# BleSignalStrength

Source: https://developer.cartrack.com/docs/mikey-android/ble-signal-strength

**Enum Class**: `BleSignalStrength`

Represents signal strength based on The Received Signal Strength Indicator (RSSI)

## Properties

### name: String
Represents as a callback to show the result from the BleTerminal process.

### ordinal: Int
Represents current connected terminalId.

## Signal Levels

### UNKNOWN
```kotlin
UNKNOWN
```
Initial state

### STRONG
```kotlin
STRONG
```
Signal to terminal is strong

### GOOD
```kotlin
GOOD
```
Signal to terminal is good

### WEAK
```kotlin
WEAK
```
Signal to terminal is weak

## Functions

### valueOf(value: String): BleSignalStrength
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values(): `Array<BleSignalStrength>`
Returns an array containing the constants of this enum type, in the order they're declared.

## RSSI Values

The signal strength enum is derived from RSSI (Received Signal Strength Indicator) values:

- **STRONG**: Typically RSSI > -60 dBm
- **GOOD**: Typically RSSI between -60 to -70 dBm  
- **WEAK**: Typically RSSI < -70 dBm
- **UNKNOWN**: No RSSI data available yet

## See Also

- [BleListener](./ble-listener.md) - For signal strength callbacks
- [BleTerminal](./ble-terminal.md) - For connection management

---

# BleTerminal

Source: https://developer.cartrack.com/docs/mikey-android/ble-terminal

**Class**: `BleTerminal(context: Context, terminalId: String)`

Represents a terminal that interact with the bluetooth BleCentral and peripheral BlePeripheral to send commands to the CTG device.

## Constructor

### BleTerminal(context: Context, terminalId: String)
Creates a new BleTerminal instance.

**Parameters:**
- `context` - Android application context  
- `terminalId` - Unique identifier for the terminal

## Properties

### bleListener: BleListener? = null
Represents as a callback to show the result from the BleTerminal process.

### terminalId: String
Represents current connected terminalId.

## Methods

### Authentication Methods

#### saveAuthKey
```kotlin
fun saveAuthKey(key: String)
```
Encrypts the authentication key and saves it to Shared Preferences.

#### getAuthKey
```kotlin
fun getAuthKey(): String?
```
Retrieves the encrypted authentication key from Shared Preferences, decrypts it, and returns it.

**Returns:** The decrypted authentication key, or `null` if not found

#### removeAuthKey
```kotlin
fun removeAuthKey()
```
Removes the authentication key from Shared Preferences.

#### hasKey
```kotlin
fun hasKey(): Boolean
```
Checks if a terminal authentication key is available for secure communication.

**Returns:** `true` if key exists, `false` otherwise

### Connection Methods

#### scanAndConnectToPeripheral
```kotlin
fun scanAndConnectToPeripheral(timeout: Long = 10000)
```
Connects to a BleTerminal device.

This function initiates the connection process by first validating the provided authKey and then scanning for available BLE devices. Upon finding a matching device, it establishes a connection and performs authentication.

**Error Handling**: The function returns a BleError in the following scenarios:

- BleError.KeyNotFound: The authKey is not found.

- BleError.KeyInvalid: The authKey has an invalid length (expected 64 characters).

- BleError.BluetoothUnsupported: The device does not support Bluetooth.

- BleError.BluetoothUnauthorized: Bluetooth permissions are not granted.

- BleError.LocationUnauthorized: Location permissions are not granted (required for BLE scanning).

- BleError.TerminalNotFound: Unable to find the target BleTerminal device.

**Successful Connection**: Upon successful connection and authentication, the BleListener.onTerminalConnected callback is invoked.

**Parameters:**
- `timeoutSeconds` The duration to wait for a connection to be established.

**Callbacks:**
- On success: `BleListener.onTerminalConnected()`
- On error: `BleListener.onError()` with various `BleError` types

#### disconnect()
```kotlin
fun disconnect()
```
Disconnects the peripheral from the [BleTerminal](./ble-terminal.md).

This function initiates the disconnection process and triggers a callback to BleListener.onTerminalDisconnected upon successful disconnection.

### Status Methods

#### getBleConnectionState()
```kotlin
fun getBleConnectionState(): BleConnectionState
```
Retrieves the Bluetooth Low Energy (BLE) connection state of the device.

This function indicates whether the Android device is currently connected, connecting, or disconnected from the specified BLE device.

Possible values are:
- BleConnectionState.CONNECTED: Indicates an active connection to the device.
- BleConnectionState.CONNECTING: Indicates an ongoing connection attempt.
- BleConnectionState.DISCONNECTED: Indicates no active connection to the device.

This function should be called before initiating a BLE connection or disconnection to ensure the desired operation is performed in the correct state.

**Returns:** The current BLE connection state as a [BleConnectionState](./ble-connection-state.md) enum.

#### getLockState()
```kotlin
fun getLockState(): LockState  
```
Gets the current lock state of the vehicle.

**Returns:** Current [LockState](./) (locked/unlocked)

The lock state of the vehicle. Possible values are:
- LOCKED: The vehicle is locked.
- UNLOCKED: The vehicle is unlocked.
- UNKNOWN: The lock state of the vehicle is unknown.

### Action Methods

#### sendAction(action: BleAction)
```kotlin
fun sendAction(action: BleAction)
```
Executes a Bluetooth Low Energy (BLE) action on the connected peripheral.

**Parameters:**
- `action` - The BLE action to execute

**Available Actions:**
- `BleAction.LOCK` - Lock the vehicle
- `BleAction.UNLOCK` - Unlock the vehicle
- `BleAction.UNLOCK_NOKEYFOB` - Unlock without key fob
- `BleAction.HEADLIGHT` - Flash headlights
- `BleAction.HORN` - Sound horn
- `BleAction.GET_LOCK_STATE` - Get current lock state
- `BleAction.VEHICLE_GET_CONFIG` - Get vehicle configuration
- `BleAction.VEHICLE_GET_STATUS` - Get vehicle ignition status

**Callbacks:**
- Result: `BleListener.onTerminalCommandResult()`
- Error: `BleListener.onError()`

## See Also

- [BleService](./ble-service.md) - For SDK initialization
- [BleListener](./ble-listener.md) - For handling callbacks
- [BLE Actions and States](./ble-action.md) - For available actions and states

---

# CtgError

Source: https://developer.cartrack.com/docs/mikey-android/ctg-error

**Sealed Class**: `CtgError`

Error Handler related to CTG Terminal

## Parameters

- `errorCode` - Error code identifier
- `localizedDescription` - Human-readable error description
- `actionCode` - Action code associated with the error

## Error Types

### Fail
```kotlin
class Fail(val actionCode: Int) : CtgError
```
Terminal response failed, default return value

### InvalidKey
```kotlin
object InvalidKey : CtgError
```
- Terminal response failed with invalid key
- ErrorCode: 21
- Description: Terminal error: Invalid key

### NoKey
```kotlin
object NoKey : CtgError
```
- Terminal response failed with no key
- ErrorCode: 24
- Description: Terminal error: No key

### NoScript
```kotlin
object NoScript : CtgError
```
- Terminal response failed with no script
- ErrorCode: 27
- Description: Terminal error: No script

### ScriptFail
```kotlin
object ScriptFail : CtgError
```
- Terminal response failed with script fail
- ErrorCode: 26
- Description: Terminal error: Script failed

### Timeout
```kotlin
object Timeout : CtgError
```
- Terminal response failed with time out
- ErrorCode: 22
- Description: Terminal error: Timeout

### Unsuccessful
```kotlin
object Unsuccessful : CtgError
```
- Terminal response failed with unsuccessful
- ErrorCode: 25
- Description: Terminal error: Unsuccessful

### TooManyRequest
```kotlin
object TooManyRequest : CtgError
```
- Terminal response failed with exceed maximum 3 concurrent commands. Any additional commands can be sent once one of the 3 previously sent commands is completed
- ErrorCode: 28
- Description: Terminal error: Exceed maximum 3 concurrent commands

## Properties

### actionCode: Int
Action code associated with the error

### errorCode: Int
Error code identifier

### localizedDescription: String
Human-readable description of the error

## See Also

- [BleError](./ble-error.md) - Parent error class
- [GattError](./gatt-error.md) - GATT-specific errors
- [BleListener](./ble-listener.md) - For error handling callbacks

---

# GattError

Source: https://developer.cartrack.com/docs/mikey-android/gatt-error

**Sealed Class**: `GattError`

Gatt Error. Called when BluetoothGatt onConnectionStateChange return other than GATT_SUCCESS.

## Parameters

- `errorCode` - Error code identifier
- `localizedDescription` - Human-readable error description  

## Error Types

### BleHciConnectionTimeout
```kotlin
object BleHciConnectionTimeout : GattError
```
Could not establish a connection in specified period. Maybe when distance for connect is so long or device is currently connected to something else

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 8
- locailzedDescription: BLE_HCI_CONNECTION_TIMEOUT

### BleHciConnFailedToBeEstablished
```kotlin
object BleHciConnFailedToBeEstablished : GattError
```
The BLE connection failed to be established. This could be due to a variety of reasons, such as the device being out of range, the device being turned off, or a problem with the BLE stack on either device

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 62
- locailzedDescription: BLE_HCI_CONN_FAILED_TO_BE_ESTABLISHED

### BleHciConnIntervalUnacceptable
```kotlin
object BleHciConnIntervalUnacceptable : GattError
```
The connection interval you requested is unacceptable to the BLE device

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 59
- locailzedDescription: BLE_HCI_CONN_INTERVAL_UNACCEPTABLE

### BleHciConnTerminatedDueToMicFailure
```kotlin
object BleHciConnTerminatedDueToMicFailure : GattError
```
The BLE connection was terminated due to a microphone failure. This could indicate a hardware issue with the microphone or a problem with the audio processing on the device

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 61
- locailzedDescription: BLE_HCI_CONN_TERMINATED_DUE_TO_MIC_FAILURE

### BleHciControllerBusy
```kotlin
object BleHciControllerBusy : GattError
```
The BLE controller is busy and can't handle your request

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 58
- locailzedDescription: BLE_HCI_CONTROLLER_BUSY

### BleHciDifferentTransactionCollision
```kotlin
object BleHciDifferentTransactionCollision : GattError
```
A different BLE transaction collided with the current one

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 42
- locailzedDescription: BLE_HCI_DIFFERENT_TRANSACTION_COLLISION

### BleHciDirectedAdvertiserTimeout
```kotlin
object BleHciDirectedAdvertiserTimeout : GattError
```
The directed advertising procedure timed out before a connection could be established

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 60
- locailzedDescription: BLE_HCI_DIRECTED_ADVERTISER_TIMEOUT

### BleHciInstantPassed
```kotlin
object BleHciInstantPassed : GattError
```
The instant you specified has already passed

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 40
- locailzedDescription: BLE_HCI_INSTANT_PASSED

### BleHciLocalHostTerminatedConnection
```kotlin
object BleHciLocalHostTerminatedConnection : GattError
```
Your device terminated the BLE connection

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 22
- locailzedDescription: BLE_HCI_LOCAL_HOST_TERMINATED_CONNECTION

### BleHciPairingWithUnitKeyUnsupported
```kotlin
object BleHciPairingWithUnitKeyUnsupported : GattError
```
The BLE device doesn't support pairing with a unit key

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 41
- locailzedDescription: BLE_HCI_PAIRING_WITH_UNIT_KEY_UNSUPPORTED

### BleHciRemoteDevTerminationDueToLowResources
```kotlin
object BleHciRemoteDevTerminationDueToLowResources : GattError
```
The BLE device terminated the connection because it's low on resources

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 20
- locailzedDescription: BLE_HCI_REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES

### BleHciRemoteDevTerminationDueToPowerOff
```kotlin
object BleHciRemoteDevTerminationDueToPowerOff : GattError
```
The BLE device terminated the connection because it's powering off

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 21
- locailzedDescription: BLE_HCI_REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF

### BleHciRemoteUserTerminatedConnection
```kotlin
object BleHciRemoteUserTerminatedConnection : GattError
```
The user on the other end terminated the BLE connection

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 19
- locailzedDescription: BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION

### BleHciStatusCodeCommandDisallowed
```kotlin
object BleHciStatusCodeCommandDisallowed : GattError
```
The BLE device doesn't allow the command you're trying to send

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 12
- locailzedDescription: BLE_HCI_STATUS_CODE_COMMAND_DISALLOWED

### BleHciStatusCodeInvalidBtleCommandParameters
```kotlin
object BleHciStatusCodeInvalidBtleCommandParameters : GattError
```
The parameters you're using for the BLE command are invalid

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 18
- locailzedDescription: BLE_HCI_STATUS_CODE_INVALID_BTLE_COMMAND_PARAMETERS

### BleHciStatusCodeInvalidLmpParameters
```kotlin
object BleHciStatusCodeInvalidLmpParameters : GattError
```
The parameters for the Link Manager Protocol (LMP) are invalid

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 30
- locailzedDescription: BLE_HCI_STATUS_CODE_INVALID_LMP_PARAMETERS

### BleHciStatusCodeLmpPduNotAllowed
```kotlin
object BleHciStatusCodeLmpPduNotAllowed : GattError
```
The LMP Protocol Data Unit (PDU) isn't allowed

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 36
- locailzedDescription: BLE_HCI_STATUS_CODE_LMP_PDU_NOT_ALLOWED

### BleHciStatusCodeLmpResponseTimeout
```kotlin
object BleHciStatusCodeLmpResponseTimeout : GattError
```
The LMP response timed out

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 34
- locailzedDescription: BLE_HCI_STATUS_CODE_LMP_RESPONSE_TIMEOUT

### BleHciStatusCodeUnspecifiedError
```kotlin
object BleHciStatusCodeUnspecifiedError : GattError
```
An unspecified error occurred with the BLE connection

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 31
- locailzedDescription: BLE_HCI_STATUS_CODE_UNSPECIFIED_ERROR

### BleHciUnsupportedRemoteFeature
```kotlin
object BleHciUnsupportedRemoteFeature : GattError
```
The BLE device doesn't support a feature that your device needs

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 26
- locailzedDescription: BLE_HCI_UNSUPPORTED_REMOTE_FEATURE

### Error
```kotlin
class Error(status: Int) : GattError
```
GATT error did not recover

### GattAuthFail
```kotlin
object GattAuthFail : GattError
```
Authentication failed when attempting to connect to the BLE device. This could be due to an incorrect password or pairing key

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 137
- locailzedDescription: GATT_AUTH_FAIL

### GATTBusy
```kotlin
object GATTBusy : GattError
```
The BLE device is busy and cannot handle the request at this time. This could be due to the device processing other requests or performing other tasks

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 132
- locailzedDescription: GATT_BUSY

### GattConnectionCongested
```kotlin
object GattConnectionCongested : GattError
```
The BLE connection is congested. This could be due to too many devices being connected to the device or too much data being transferred

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 143
- locailzedDescription: GATT_CONNECTION_CONGESTED

### GattConnectionTimeout
```kotlin
object GattConnectionTimeout : GattError
```
The BLE connection timed out. This could be due to the device being out of range or the device being turned off

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 147
- locailzedDescription: GATT_CONNECTION_TIMEOUT

### GATTDbFull
```kotlin
object GATTDbFull : GattError
```
The BLE device's database is full. This could prevent the device from storing new data or updating existing data

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 131
- locailzedDescription: GATT_DB_FULL

### GATTError
```kotlin
object GATTError : GattError
```
A generic GATT error occurred. This is a catch-all error that could indicate a variety of problems

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 133
- locailzedDescription: GATT_ERROR

### GattFailure
```kotlin
object GattFailure : GattError
```
A generic GATT failure occurred. This is a catch-all error that could indicate a variety of problems

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 257
- locailzedDescription: GATT_FAILURE

### GattIllegalParameter
```kotlin
object GattIllegalParameter : GattError
```
An illegal parameter was passed to the GATT function. This could be due to an incorrect value being passed or a parameter being missing

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 135
- locailzedDescription: GATT_ILLEGAL_PARAMETER

### GattInsufficientAuthentication
```kotlin
object GattInsufficientAuthentication : GattError
```
Insufficient authentication for a given operation

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 5
- locailzedDescription: GATT_INSUFFICIENT_AUTHENTICATION

### GattInsufficientEncryption
```kotlin
object GattInsufficientEncryption : GattError
```
The connection to the BLE device isn't secure enough

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 15
- locailzedDescription: GATT_INSUFFICIENT_ENCRYPTION

### GATTInternalError
```kotlin
object GATTInternalError : GattError
```
An internal error occurred on the BLE device. This is a generic error that could indicate a variety of problems

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 129
- locailzedDescription: GATT_INTERNAL_ERROR

### GattInvalidAttributeLength
```kotlin
object GattInvalidAttributeLength : GattError
```
The data you're trying to send or receive is the wrong length

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 13
- locailzedDescription: GATT_INVALID_ATTRIBUTE_LENGTH

### GattInvalidOffset
```kotlin
object GattInvalidOffset : GattError
```
A read or write operation was requested with an invalid offset

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 7
- locailzedDescription: GATT_INVALID_OFFSET

### GATTNoRessources
```kotlin
object GATTNoRessources : GattError
```
The BLE device does not have enough resources to complete the request. This could be due to the device being low on memory or processing power

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 128
- locailzedDescription: GATT_NO_RESSOURCES

### GattReadNotPermitted
```kotlin
object GattReadNotPermitted : GattError
```
GATT read operation is not permitted

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 2
- locailzedDescription: GATT_READ_NOT_PERMITTED

### GattRequestNotSupported
```kotlin
object GattRequestNotSupported : GattError
```
The given request is not supported

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 6
- locailzedDescription: GATT_REQUEST_NOT_SUPPORTED

### GattWriteNotPermitted
```kotlin
object GattWriteNotPermitted : GattError
```
GATT write operation is not permitted

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 3
- locailzedDescription: GATT_WRITE_NOT_PERMITTED

### GATTWrongState
```kotlin
object GATTWrongState : GattError
```
The BLE device is in the wrong state to complete the request. This could be due to the device not being connected or not being in the correct mode

**Properties**
- errorCode: Int
- localizedDescription: String

**Parameters** 
- errorCode: 130
- locailzedDescription: GATT_WRONG_STATE

## See Also

- [BleError](./ble-error.md) - Main BLE error handling
- [BleListener](./ble-listener.md) - Error callback interface

---

# GetVehicleStats

Source: https://developer.cartrack.com/docs/mikey-android/get-vehicle-stats

**Data Class**: `GetVehicleStats`

Model for vehicle stats

## Constructor

```kotlin
fun GetVehicleStats(
    odometer: Int?, 
    engineHours: Int?, 
    engineRPM: Int?, 
    fuelLevel: Int?, 
    hazardsIsOn: Boolean?, 
    indicators: String?, 
    brakesIsActive: Boolean?, 
    handBrakeIsActive: Boolean?, 
    lightsIsOn: Boolean?, 
    reverseGearIsActive: Boolean?, 
    driverDoorIsOpen: Boolean?, 
    passengerDoorIsOpen: Boolean?, 
    driverSeatbeltIsEngage: Boolean?, 
    passengerSeatbeltIsEngage: Boolean?, 
    hornIsActive: Boolean?
)
```

## Parameters

- `odometer` - Odometer reading
- `engineHours` - Engine hours
- `engineRPM` - Engine RPM
- `fuelLevel` - Fuel level
- `hazardsIsOn` - Hazards status
- `indicators` - Indicator status
- `brakesIsActive` - Brakes status
- `handBrakeIsActive` - Hand brake status
- `lightsIsOn` - Lights status
- `reverseGearIsActive` - Reverse gear status
- `driverDoorIsOpen` - Driver door status
- `passengerDoorIsOpen` - Passenger door status
- `driverSeatbeltIsEngage` - Driver seatbelt status
- `passengerSeatbeltIsEngage` - Passenger seatbelt status
- `hornIsActive` - Horn status

## Properties

### brakesIsActive: Boolean?
Brakes value return in Boolean, `true` is Active, `false` is Off

### driverDoorIsOpen: Boolean?
Driver door value return in Boolean, `true` is Open, `false` is Closed

### driverSeatbeltIsEngage: Boolean?
Driver seatbelt value return in Boolean, `true` is Engage, `false` is Not Engage

### engineHours: Int?
Engine Hours value return in `Int`

### engineRPM: Int?
Engine PRM value return in `Int`

### fuelLevel: Int?
Fuel Level value return in `Int`

### handBrakeIsActive: Boolean?
Hand Brake value return in Boolean, `true` is Active, `false` is Off

### hazardsIsOn: Boolean?
Hazards value return in Boolean, `true` is On, `false` is Off

### hornIsActive: Boolean?
Horn value return in Boolean, `true` is Active, `false` is Off

### indicators: String?
Indicators value return in String

### lightsIsOn: Boolean?
Lights value return in Boolean, `true` is On, `false` is Off

### odometer: Int?
Odometer value return in `Int`

### passengerDoorIsOpen: Boolean?
Passenger door value return in Boolean, `true` is Open, `false` is Closed

### passengerSeatbeltIsEngage: Boolean?
Passenger seatbelt value return in Boolean, `true` is Engage, `false` is Not Engage

### reverseGearIsActive: Boolean?
Reverse gear value return in Boolean, `true` is Active, `false` is Off

## See Also

- [GetVehicleStatus](./get-vehicle-status.md) - Vehicle status information
- [BleAction](./ble-action.md) - Available actions including GET_VEHICLE_STATS
- [BleTerminal](./ble-terminal.md) - For executing actions
- [BleListener](./ble-listener.md) - For handling responses

---

# GetVehicleStatus

Source: https://developer.cartrack.com/docs/mikey-android/get-vehicle-status

**Data Class**: `GetVehicleStatus`

Model for vehicle stats

## Constructor

```kotlin
fun GetVehicleStatus(ignitionState: Boolean?)
```

## Parameters

- `ignitionState` - Ignition state of the vehicle

## Properties

### ignitionState: Boolean?
Ignition State return in Boolean, `true` is On, `false` is Off

## See Also

- [GetVehicleStats](./get-vehicle-stats.md) - Detailed vehicle statistics
- [BleAction](./ble-action.md) - Available actions including GET_VEHICLE_STATUS  
- [BleTerminal](./ble-terminal.md) - For executing actions
- [BleListener](./ble-listener.md) - For handling responses

---

# Android SDK: Getting started

Source: https://developer.cartrack.com/docs/mikey-android/getting-started

This guide explains how to install the Cartrack BLE Lock SDK for Android and run the basic connection flow against a compatible BLE terminal.

## Installation

The SDK package is provided by Cartrack on request. If you do not have it yet, see [Request SDK access](../mobile-sdks/request-sdk.mdx).

- Add the latest **CartrackBleLock_Android_SDK** `.aar` file (provided to you by Cartrack) to your Android project (for example, under a `libs/` directory).
- In your project-level `build.gradle`, add `flatDir { dirs 'libs' }`.

```kotlin
allprojects {
  repositories {
    ...
    flatDir {
      dirs 'libs'
    }
  }
}
```

- In your app-level `build.gradle`, add the `.aar` file dependency.

```kotlin
 dependencies {
  implementation fileTree(include: ['*.aar'], dir: 'libs')
  implementation(name: 'blesdk-release_v3.0.3.aar', ext: 'aar')
}
```

- For Android 12 (API 31) or higher, you must declare Bluetooth permissions.
- Update your app-level `AndroidManifest.xml`.

```xml
<manifest>
    <uses-permission android:name="android.permission.BLUETOOTH"
                     android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
        
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    ...
</manifest>
```

## Core Classes

### [BleService](./ble-service.md)

The main entry point for the Cartrack BLE SDK. Use this class to initialize the SDK and obtain terminal instances.

**Key Methods:**
* [BleService.configure()](./ble-service.md#configure) - Configures the BleService. This function should be called first.
- [BleService.getTerminal()](./ble-service.md#getterminalterminalid-string) - Get an instance of BleTerminal associated with the given terminal ID.
* [BleService.isConfigured()](./ble-service.md#isconfigured) - Checks if the given BleTerminal instance is configured.
* [BleService.clear()](./ble-service.md#clear) - Clears the configured instance.

### [BleTerminal](./ble-terminal.md)

Represents a terminal that communicates with CTG devices via Bluetooth Low Energy.

**Key Methods:**
- [BleTerminal.scanAndConnectToPeripheral](./ble-terminal.md#scanandconnecttoperipheral) - Connects to a BleTerminal device.
- [BleTerminal.sendAction](./ble-terminal.md#sendactionaction-bleaction) - Executes a Bluetooth Low Energy (BLE) action on the connected peripheral.
- [BleTerminal.saveAuthKey](./ble-terminal.md#saveauthkey) - Encrypts the authentication key and saves it to Shared Preferences.
- [BleTerminal.disconnect](./ble-terminal.md#disconnect) - Disconnects the peripheral from the BleTerminal.
- [BleTerminal.getAuthKey](./ble-terminal.md#getauthkey) - Retrieves the encrypted authentication key from Shared Preferences, decrypts it, and returns it.
- [BleTerminal.getBleConnectionState](./ble-terminal.md#getbleconnectionstate) - Retrieves the Bluetooth Low Energy (BLE) connection state of the device.
- [BleTerminal.getLockState](./ble-terminal.md#getlockstate) - Gets the current lock state of the vehicle.
- [BleTerminal.hasKey](./ble-terminal.md#haskey) - Checks if a terminal authentication key is available for secure communication.
- [BleTerminal.removeAuthKey](./ble-terminal.md#removeauthkey) - Removes the authentication key from Shared Preferences.

### [BleListener](./ble-listener.md)

Interface for handling BLE events and callbacks.

**Key Callbacks:**
- [BleListener.onError()](./ble-listener.md#onerrorbleerror-bleerror) - Called when an error occurs during a BleTerminal operation.
- [BleListener.onReconnect()](./ble-listener.md#onreconnect) - Called when the Bluetooth GATT layer returns `GATT_ERROR` or `GATT_FAILURE`. After three reconnect attempts, the SDK returns `BleError.GATTError`.
- [BleListener.onRemoveAuthKeySuccess()](./ble-listener.md#onremoveauthkeysuccess) - Called when the authentication key is successfully removed.
- [BleListener.onSaveAuthKeySuccess()](./ble-listener.md#onsaveauthkeysuccessterminal-bleterminal-authkey-string) - Called when the authentication key is successfully saved.
- [BleListener.onSignalStrength()](./ble-listener.md#onsignalstrengthstrength-blesignalstrength-rssivalue-int) - Called when the signal strength changes.
- [BleListener.onTerminalCommandResult()](./ble-listener.md#onterminalcommandresultaction-bleaction) - Called when a terminal command returns a result.
- [BleListener.onTerminalConnected()](./ble-listener.md#onterminalconnectedterminal-bleterminal) - Called when the BleTerminal successfully connects to a device.
- [BleListener.onTerminalDidGetVehicleStats()](./ble-listener.md#onterminaldidgetvehiclestatscommand-command-stats-getvehiclestats) - Called when fetching vehicle stat.
- [BleListener.onTerminalDidGetVehicleStatus()](./ble-listener.md#onterminaldidgetvehiclestatuscommand-command-status-getvehiclestatus) - Called when fetching vehicle status.
- [BleListener.onTerminalDisconnected()](./ble-listener.md#onterminaldisconnectedterminal-bleterminal) - Called when terminal is disconnected.

## How to Use

> **All examples require `import CartrackBleLockSDK` somewhere in the source file.**

### Initialize CartrackBleLockSDK

Initialize CartrackBleLockSDK with Context:

#### V2.4

```kotlin
BleService.configure(Context, vendorId, apiKey, countryCode)
```

#### V3.0

```kotlin
BleService.configure(Context)
```

Before starting to get the authentication key, you can create a `BleTerminal` variable outside the function:

```kotlin
var bleTerminal: BleTerminal
```

Get an instance of BleTerminal:

```kotlin
bleTerminal = BleService.getTerminal(terminalID)
```

### Save Authentication Key

Save the authentication key with `BleTerminal.saveAuthKey()`:

```kotlin
bleTerminal.saveAuthKey()
```

### Get Authentication Key

Get the authentication key with `BleTerminal.getAuthKey()`:

```kotlin
bleTerminal.getAuthKey()
```

> This action requires network connection thus performing it earlier is encouraged before connecting to terminal.

### Connect to Ble Terminal

Connect to Ble Terminal with `BleTerminal.scanAndConnectToPeripheral()`:

#### V2.4

```kotlin
bleTerminal.scanAndConnectToPeripheral()
```

Under the hood, this scans peripherals around, connects and authenticates
If successful, then you will get a response through BleListener.onTerminalConnected
Else BleListener.onError if anything wrong happens:

* ErrorHandler.BleConnectionError.KeyNotFound
* ErrorHandler.BleConnectionError.KeyInvalid
* ErrorHandler.BleConnectionError.BluetoothUnsupported
* ErrorHandler.BleConnectionError.BluetoothUnauthorized > only if your app did not request the required permission
* ErrorHandler.BleConnectionError.LocationUnauthorized > only if your app did not request the required permission
* ErrorHandler.BleConnectionError.BluetoothPairingFailed > the system returned a connection error
* ErrorHandler.BleConnectionError.TerminalNotFound > 30 seconds timeout

#### V3.0

```kotlin
bleTerminal.scanAndConnectToPeripheral()
```

Under the hood, this scans peripherals around, connects and authenticates
If successful, then you will get a response through BleListener.onTerminalConnected
Else BleListener.onError if anything wrong happens:

* BleError.KeyNotFound
* BleError.KeyInvalid
* BleError.BluetoothUnsupported
* BleError.BluetoothUnauthorized > only if your app did not request the required permission
* BleError.LocationUnauthorized > only if your app did not request the required permission
* BleError.TerminalNotFound > the system returned a connection error
* BleError.TerminalNotFound > 30 seconds timeout
* BleError.GATTError > BluetoothGattCallback.onConnectionStateChange return other than GATT_SUCCESS

### Connect to Ble Terminal with Timeout

Set connection timeout by add duration (second) in `Long`. Default timeout is 10 seconds:

```kotlin
bleTerminal.scanAndConnectToPeripheral(20)
```

### Disconnect from Ble Terminal

Disconnect from Ble Terminal with `BleTerminal.disconnect()`:

```kotlin
bleTerminal.disconnect()
```

> This function will send a disconnect command to the terminal.

### Fetch Authentication Key

Fetch authentication key from API `BleTerminal.fetchAuthKey()` from shared preferences:

```kotlin
bleTerminal.fetchAuthKey()
```

### Remove Authentication Key

Remove the authentication key with `BleTerminal.removeAuthKey()` from shared preferences:

```kotlin
bleTerminal.removeAuthKey()
```

> This function will not affect the authentication key on the server side.

### Terminal Signal Update

Called periodically to update the BLE signal strength to Ble Terminal:

```kotlin
bleListener.onSignalStrength(BleSignalStrength, rssiValue)
```

### Check Authentication Key

Called to checks if a terminal authentication key is available for secure communication:

```kotlin
bleListener.hasKey()
```

### Send Ble Action to Terminal

Send lock action to terminal `BleAction.LOCK`:

```kotlin
bleTerminal.sendAction(BleAction.LOCK)
```

Send unlock action to terminal with `BleAction.UNLOCK`:

```kotlin
bleTerminal.sendAction(BleAction.UNLOCK)
```

Send headlight action to terminal with `BleAction.HEADLIGHT`:

```kotlin
bleTerminal?.sendAction(BleAction.HEADLIGHT)
```

Send horn action to terminal with `BleAction.HORN`:

```kotlin
bleTerminal.sendAction(BleAction.HORN)
```

Get the current state of vehicle\'s lock status - possible value - `locked`/`unlocked` with `BleAction.GET_LOCK_STATE`:

```kotlin
bleTerminal.sendAction(BleAction.GET_LOCK_STATE)
```

Send unlock with no key fob action to terminal  with `BleAction.UNLOCK_NOKEYFOB`:

```kotlin
bleTerminal.sendAction(BleAction.UNLOCK_NOKEYFOB)
```

Get the current state of vehicle\'s status  with `BleAction.VEHICLE_GET_CONFIG`:

```kotlin
bleTerminal.sendAction(BleAction.VEHICLE_GET_CONFIG)
```

> Consist of `odometer`, `engineHours`, `engineRPM`, `fuelLevel`, `hazardsIsOn`, `indicators`, `brakesIsActive`, `handBrakeIsActive`, `lightsIsOn`, `driverDoorIsOpen`, `passengerDoorIsOpen`, `driverSeatbeltIsEngage`, `passengerSeatbeltIsEngage`, `hornIsActive` field.

Get the current state of vehicle\'s ignition status - possible value - `on`/`off`  with `BleAction.VEHICLE_GET_STATUS`:

```kotlin
bleTerminal.sendAction(BleAction.VEHICLE_GET_STATUS)
```

#### V2.4

The response for all `BleAction` will be in `BleListener.onTerminalCommandResult(bleAction: BleAction)` and `BleListener.onError(ErrorHandler.BleActionError/ErrorHandler.CtgError)`

#### V3.0

The response for all `BleAction` will be in `BleListener.onTerminalCommandResult(bleAction: BleAction)` and `BleListener.onError(BleError/BleError.CtgError)`

## Possible error in Ble

### [BleError](./ble-error.md)

> **Error Handler related to BLE Connection.**

* [BluetoothUnauthorized](./ble-error.md#bluetoothunauthorized) - Bluetooth permission is not granted. Ask user to grant permission from phone settings
* [BluetoothDisabled](./ble-error.md#bluetoothdisabled) - Bluetooth is disabled
* [BluetoothUnsupported](./ble-error.md#bluetoothunsupported) - Device does not support Bluetooth Low Energy
* [SaveAuthKeyFailed](./ble-error.md#saveauthkeyfailed) - Failed to save authentication key in Shared Preference
* [KeyNotFound](./ble-error.md#keynotfound) - Authentication key not found in Shared Preference
* [KeyInvalid](./ble-error.md#keyinvalid) - Authentication key in Shared Preference is invalid
* [TerminalNotFound](./ble-error.md#terminalnotfound) - Unable to discover Ble Terminal, terminal might be out of range
* [NotConnected](./ble-error.md#notconnected) - Not connected to Ble Terminal. Call BleTerminal.connect() to connect first
* [LocationUnauthorized](./ble-error.md#locationunauthorized) - Location permission is not granted
* [GattError](./ble-error.md#gatterror) - Gatt Error. Called when BluetoothGatt onConnectionStateChange return other than GATT_SUCCESS.
* [CtgError](./ctg-error.md) - Failed due to Terminal action, refer to CtgError

### [CtgError](./ctg-error.md)

> **Error Handler related to CTG Terminal.**

* [InvalidKey](./ctg-error.md#invalidkey) - Terminal response failed with invalid key
* [Timeout](./ctg-error.md#timeout) - Terminal response failed with time out
* [Fail](./ctg-error.md#fail) - Terminal response failed, default return value
* [NoKey](./ctg-error.md#nokey) - Terminal response failed with no key
* [Unsuccessful](./ctg-error.md#unsuccessful) - Terminal response failed with unsuccessful
* [ScriptFail](./ctg-error.md#scriptfail) - Terminal response failed with script fail
* [NoScript](./ctg-error.md#noscript) - Terminal response failed with no script
* [TooManyRequest](./ctg-error.md#toomanyrequest) - Terminal response failed with exceed maximum 3 concurrent commands. Any additional commands can be sent once one of the 3 previously sent commands is completed

### GattError

> **Gatt Error. Called when BluetoothGatt onConnectionStateChange return other than GATT_SUCCESS.**

* [GattReadNotPermitted](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-read-not-permitted/index.html): GATT read operation is not permitted
* [GattWriteNotPermitted](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-write-not-permitted/index.html): GATT write operation is not permitted
* [GattInsufficientAuthentication](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-insufficient-authentication/index.html): Insufficient authentication for a given operation
* [GattRequestNotSupported](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-request-not-supported/index.html): The given request is not supported
* [GattInvalidOffset](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-invalid-offset/index.html): A read or write operation was requested with an invalid offset
* [BleHciConnectionTimeout](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-connection-timeout/index.html): Could not establish a connection in specified period. Maybe when distance for connect is so long or device is currently connected to something else.
* [BleHciStatusCodeCommandDisallowed](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-status-code-command-disallowed/index.html): The BLE device doesn\'t allow the command you\'re trying to send
* [GattInvalidAttributeLength](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-invalid-attribute-length/index.html): The data you\'re trying to send or receive is the wrong length
* [GattInsufficientEncryption](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-insufficient-encryption/index.html): The connection to the BLE device isn\'t secure enough
* [BleHciStatusCodeInvalidBtleCommandParameters](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-status-code-invalid-btle-command-parameters/index.html): The parameters you\'re using for the BLE command are invalid
* [BleHciRemoteUserTerminatedConnection](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-remote-user-terminated-connection/index.html): The user on the other end terminated the BLE connection
* [BleHciRemoteDevTerminationDueToLowResources](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-remote-dev-termination-due-to-low-resources/index.html): The BLE device terminated the connection because it\'s low on resources
* [BleHciRemoteDevTerminationDueToPowerOff](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-remote-dev-termination-due-to-power-off/index.html): The BLE device terminated the connection because it\'s powering off
* [BleHciLocalHostTerminatedConnection](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-local-host-terminated-connection/index.html): Your device terminated the BLE connection
* [BleHciUnsupportedRemoteFeature](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-unsupported-remote-feature/index.html): The BLE device doesn\'t support a feature that your device needs
* [BleHciStatusCodeInvalidLmpParameters](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-status-code-invalid-lmp-parameters/index.html): The parameters for the Link Manager Protocol (LMP) are invalid
* [BleHciStatusCodeUnspecifiedError](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-status-code-unspecified-error/index.html): An unspecified error occurred with the BLE connection
* [BleHciStatusCodeLmpResponseTimeout](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-status-code-lmp-response-timeout/index.html): The LMP response timed out
* [BleHciStatusCodeLmpPduNotAllowed](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-status-code-lmp-pdu-not-allowed/index.html): The LMP Protocol Data Unit (PDU) isn\'t allowed
* [BleHciInstantPassed](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-instant-passed/index.html): The instant you specified has already passed
* [BleHciPairingWithUnitKeyUnsupported](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-pairing-with-unit-key-unsupported/index.html): The BLE device doesn\'t support pairing with a unit key
* [BleHciDifferentTransactionCollision](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-different-transaction-collision/index.html): A different BLE transaction collided with the current one
* [BleHciControllerBusy](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-controller-busy/index.html): The BLE controller is busy and can\'t handle your request
* [BleHciConnIntervalUnacceptable](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-conn-interval-unacceptable/index.html): The connection interval you requested is unacceptable to the BLE device
* [BleHciDirectedAdvertiserTimeout](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-directed-advertiser-timeout/index.html): The directed advertising procedure timed out before a connection could be established
* [BleHciConnTerminatedDueToMicFailure](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-conn-terminated-due-to-mic-failure/index.html): The BLE connection was terminated due to a microphone failure. This could indicate a hardware issue with the microphone or a problem with the audio processing on the device.
* [BleHciConnFailedToBeEstablished](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-ble-hci-conn-failed-to-be-established/index.html): The BLE connection failed to be established. This could be due to a variety of reasons, such as the device being out of range, the device being turned off, or a problem with the BLE stack on either device
* [GATTNoRessources](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-g-a-t-t-no-ressources/index.html): The BLE device does not have enough resources to complete the request. This could be due to the device being low on memory or processing power
* [GATTInternalError](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-g-a-t-t-internal-error/index.html): An internal error occurred on the BLE device. This is a generic error that could indicate a variety of problems
* [GATTWrongState](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-g-a-t-t-wrong-state/index.html): The BLE device is in the wrong state to complete the request. This could be due to the device not being connected or not being in the correct mode
* [GATTDbFull](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-g-a-t-t-db-full/index.html): The BLE device\'s database is full. This could prevent the device from storing new data or updating existing data
* [GATTBusy](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-g-a-t-t-busy/index.html): The BLE device is busy and cannot handle the request at this time. This could be due to the device processing other requests or performing other tasks
* [GATTError](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-g-a-t-t-error/index.html): A generic GATT error occurred. This is a catch-all error that could indicate a variety of problems
* [GattIllegalParameter](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-illegal-parameter/index.html): An illegal parameter was passed to the GATT function. This could be due to an incorrect value being passed or a parameter being missing
* [GattAuthFail](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-auth-fail/index.html): Authentication failed when attempting to connect to the BLE device. This could be due to an incorrect password or pairing key
* [GattConnectionCongested](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-connection-congested/index.html): The BLE connection is congested. This could be due to too many devices being connected to the device or too much data being transferred
* [GattConnectionTimeout](./-mi-key%20-android%20-s-d-k/com.cartrack.blesdk.enumerations/-gatt-error/-gatt-connection-timeout/index.html): The BLE connection timed out. This could be due to the device being out of range or the device being turned off
* **GattFailure**: A generic GATT failure occurred
* **Error**: GATT error did not recover

## API Reference

For complete API documentation with detailed method signatures, parameters, and examples, see:

- **[BleService](./ble-service.md)** - SDK initialization and configuration
- **[BleTerminal](./ble-terminal.md)** - Terminal operations and vehicle control
- **[BleListener](./ble-listener.md)** - Event handling and callbacks

## Next Steps

1. **Set up your development environment** by following the installation steps above.
2. **Implement error handling** using the error types documented above.
3. **Test with a physical device** to ensure reliable BLE connectivity.

---

# LockState

Source: https://developer.cartrack.com/docs/mikey-android/lock-state

**Enum Class**: `LockState`

Represents vehicle door LOCK/UNLOCK current state

## Lock States

### LOCKED
```kotlin
LOCKED
```
When the vehicle door is locked

### UNLOCKED
```kotlin
UNLOCKED
```
When the vehicle door is unlocked

### UNKNOWN
```kotlin
UNKNOWN
```
When current state is unknown or has not received yet by the BLE. In case of that we need to refresh the state

## Functions

### valueOf(value: String): LockState
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

**Throws** IllegalArgumentException if this enum type has no constant with the specified name

### values(): `Array<LockState>`
Returns an array containing the constants of this enum type, in the order they're declared.

## See Also

- [BleAction](./ble-action.md) - For lock/unlock actions
- [BleTerminal](./ble-terminal.md) - For getting lock state
- [BleListener](./ble-listener.md) - For state update callbacks

---

# Android

Source: https://developer.cartrack.com/docs/mikey-android/



---

# Overview

Source: https://developer.cartrack.com/docs/mikey-android/overview

The Mikey Android SDK enables mobile applications to communicate with compatible Cartrack in‑vehicle terminals over Bluetooth Low Energy (BLE) for short‑range vehicle access and status retrieval.

## What you can do

- Connect to a nearby BLE terminal associated with a vehicle.
- Perform supported actions (for example, lock and unlock).
- Retrieve supported vehicle status and statistics.
- Receive connection state, signal strength, and action callbacks.

## Where to start

- The SDK package is provided on request: see [Request SDK access](../mobile-sdks/request-sdk.mdx).
- Follow the Getting Started guide to install the SDK and run your first connection flow.
- Use the API Reference pages for details on the core classes and enumerations.

## Important notes

- BLE capabilities, permissions, and behavior vary by Android version and device.
- Command availability depends on vehicle hardware and provisioning.

---

# Release Notes

Source: https://developer.cartrack.com/docs/mikey-android/release-notes

:::info
SDK packages are provided on request. See [Request SDK access](../mobile-sdks/request-sdk.mdx).
:::

### V3.0.3

#### New Features

* Implemented `reverse gear` in `Vehicle Status`
* Created an enum class `GattError` to represent GATT errors with descriptive names and descriptions

#### Bug Fixes

* Corrected the `VehicleStatus.lightIsOn` to display the accurate value
* Resolved slow connection issues
* Addressed ANR (Application Not Responding) problems related to connection
* Prevented heartbeat calls when an action has not received a response to avoid timeout

#### Improvements

* Added new log message for `onConnectionStateChange` to provide information about the GATT status and connection state: `GattStatus = [gatt description], Connection State = [Connect/Disconnect]`

### V3.0.2

#### New Features

* Reintroduced `BleTerminal.hasKey()`
* Added `BleError.LocationUnauthorised` to return an error when the user disallows location permission
* Added `BleError.CtgError.TooManyRequest` to return an error when exceeding more than 3 concurrent commands
* Added `BleError.GATTError` to return Bluetooth Gatt errors

#### Bug Fixes

* Fixed SDK failure to compile
* Fixed `BleListener.onSignalStrength` to read the RSSI for a connected remote device

### V3.0.1

* Added `BleError.LocationUnauthorised` to return an error when the user disallows location permission

### V3.0

Notice: This version has breaking changes

#### Before

The management of Bluetooth keys was handled by the SDK, which communicated with the Cartrack servers from the initial version to version 2.4:

* Obtaining the key
* Key randomisation

This increased complexity for mobile integrations, and keys could only be fetched (or randomized) while the smartphone had the app open. In many cases, users may be in environments with limited cellular connectivity (for example, parking garages), which made the process cumbersome.

#### After

This new SDK is more straightforward, and we have exported the key management into the Cartrack Fleet API. Using the API, you can now fetch the BlueTooth keys ahead of time and reuse them for multiple bookings. Have a look at the following endpoints:

* GET /mikey/:registration, to get the key for a given vehicle registration
* GET /mikey, to get the keys for all your vehicles
* POST /mikey/:registration, to randomise the key for a given vehicle registration

* **API documentation:** [https://developer.cartrack.com/fleet-api](https://developer.cartrack.com/fleet-api)

To enhance security, it is advisable to randomize keys periodically. We suggest rotating keys when there is enough time between two users, allowing the vehicle to receive the new key and the user to load it on their phone.

You can then provide the key to the user’s smartphone using the SDK key functions.

* `BleListener.onSaveAuthKeySuccess` called when save authentication key successfully
* `BleTerminal.saveAuthKey`, `BleTerminal.getAuthKey` and `BleTerminal.removeAuthKey` to handle authentication key

##### Release details

* Remove `VendorId`,`API key`and`country code`
* Remove `Random Key`,`Fetch Key`,`Save Key`and`Remove Key` from API
* Combine `BleConnectionError`,`BleActionError`and`BleKeyError` to `BleError`
* Remove unused `Error`
* Added connection timeout parameter for `scanAndConnectToPeripheral`

### V2.4.2

* Added `ErrorHandler.BleConnectionError.LocationUnauthorised` to return an error when the user disallows location permission

### V2.4.1

* Reintroducing `BleTerminal.hasKey()`

### 2.4

* Added `ErrorHandler` to handle all possible errors
* Added `ErrorHandler.BleConnectionError` to indicate bluetooth connection and authentication failures and provide an error type
* Added `ErrorHandler.BleActionError` to indicate when a BLE action failed and provide an error type
* Added `ErrorHandler.CtgError` to indicate when a terminal action failed and provide an error type
* Added `BleListener.onError` to return all error from `BleListener`
* Added `BleAction.VEHICLE_GET_STATUS` to get the current state of the vehicle’s ignition
* Removed `BleListener.onTerminalConnectionFailed` and merge it to `BleListener.onError`
* Changed `BleListerner.onGetAuthKey` to `BleListener.onGetAuthKeySuccess` to return success API, failure will return in `BleListener.onError`
* Changed `BleListerner.onRemoveAuthKey` to `BleListener.onRemoveAuthKeySuccess` to return success API, failure will return in `BleListener.onError`
* Changed `BleListerner.onRandomAuthKey` to `BleListener.onRandomAuthKeySuccess` to return success API, failure will return in `BleListener.onError`
* Moved errors so that they are returned in `BleListener.onError`
* Added `BleListener.onTerminalDidGetVehicleStatus` for showing `IgnitionState`
* Updated error code and localized description for Error Handler

### V2.3

* Added a function `BleAction.unlockNoKeyFob` to send an unlock command `Unlock_0` that doesn\'t activate the key fob. The driver won\'t be able to start the engine.
* Receive `BleAction.unlockNoKeyFob` response in `BleTerminalDelegate.bleTerminalDidAction(terminal:action:error:)`

### V2.2.1

* Add BleTerminal.removeAuthKey() to remove authentication key from local memory
* Add BleListener.onRemoveAuthKey(error: String?, success: Boolean?) to receive a call back when removeAuthKey() called
* Add BleTerminal.randomAuthKey() to random the terminal authentication key , call back will be received in BleListener.onGetAuthKey (error: String?, success: Boolean?)
* We now have two separate functions removeAuthKey and randomAuthKey, please consider it when upgrading to this new version.
* The Shared Preference will only save one authentication key with a static name. If you want to use another it for a different vehicle or a new authentication key, you will need to remove the current authentication key before fetching the new one.
* Bugfix for the default url

### V2.2

* Add a new parameter apiUrl in BleService.configure().
* Add BleService.setApiUrl(apiUrl: String) for changing the apiUrl at runtime.
* Add BleService.setDefaultApiUrl() for changing the apiUrl to the default apiUrl at runtime.

### V2.1

* Fix unicode characters which fail to convert to proper bytes.

### V2.0

* Add a new parameter countryCode in BleService.configure().
  * Please refer to iban.com/country-codes for the country code alpha-2 format.
* Add BleService.clear() for clearing BleService instance.

### V1.5

* Fix a situation where the terminal name is null on specific smartphones, causing a crash

### V1.4

* Fix an issue where the SDK fails to fetch the key, when the smartphone does not have stable connection

### V1.3

* Fix a crash when phone goes outside of the terminal BLE antenna\'s range

### V1.2

* Add BleTerminal.getBleConnectionState() to indicate the state of the BLE
* Fix an intermittent CRC fail at the connection between smartphone and terminal

### V1.1

* Add BleTerminal.getLockState() to indicate vehicle’s lock state
* Add BleAction.GET_LOCK_STATE action to get the latest vehicle’s lock state

### V1.0

* Initial release

---

# BleAction

Source: https://developer.cartrack.com/docs/mikey-ios/ble-action

**Enum**: `BleAction`

Ble Terminal actions list

## Cases

### lock

```swift
case lock
```

Send lock action to terminal

### unlock

```swift
case unlock
```

Send unlock action to terminal

### headlight

```swift
case headlight
```

Send headlight action to terminal

### horn

```swift
case horn
```

Send horn action to terminal

### lockState

```swift
case lockState
```

Get the current state of vehicle's lock status (Lock/Unlock)

### unlockNoKeyFob

```swift
case unlockNoKeyFob
```

Send unlock with no key fob action to terminal

### ignitionState

```swift
case ignitionState
```

Get the current state of vehicle's ignition status (on/off)

## See Also

- [BleTerminal](./ble-terminal.md) - For sending actions
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For receiving action results
- [LockState](./lock-state.md) - Lock state after lock/unlock actions
- [IgnitionState](./ignition-state.md) - Ignition state after ignitionState action

---

# BLECentral

Source: https://developer.cartrack.com/docs/mikey-ios/ble-central

**Extension**: `BLECentral`

```swift
extension BLECentral: CBCentralManagerDelegate
```

```swift
extension BLECentral: CBPeripheralDelegate
```

## See Also

- [BleService](./ble-service.md) - SDK entry point
- [BleTerminal](./ble-terminal.md) - Terminal interaction interface

---

# BleConnectionState

Source: https://developer.cartrack.com/docs/mikey-ios/ble-connection-state

**Enum**: `BleConnectionState`

Ble Terminal connection states

## Cases

### disconnected

```swift
case disconnected
```

Ble Terminal is disconnected

### connecting

```swift
case connecting
```

Ble Terminal is connecting

### connected

```swift
case connected
```

Ble Terminal has connected to the device and ready to send action

## See Also

- [BleTerminal](./ble-terminal.md) - For connection methods and state property
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For connection callbacks

---

# BleError

Source: https://developer.cartrack.com/docs/mikey-ios/ble-error

**Enum**: `BleError`

Ble error types

**Conforms to**: `Error`, `CustomNSError`

## Properties

### errorDomain: String

```swift
public static var errorDomain: String { get }
```

The error domain for BLE errors

### actionCode: Int

```swift
public var actionCode: Int { get }
```

The action code only use for [CtgError](./ctg-error.md), for other error will return -1

### errorCode: Int

```swift
public var errorCode: Int { get }
```

Error code

### localizedDescription: String

```swift
public var localizedDescription: String { get }
```

Error description

## Error Cases

### bluetoohUnauthorized

```swift
case bluetoohUnauthorized
```

- **Error Code:** 1
- **Description:** Phone: Bluetooth permission is not granted, please go to settings to grant permission

### bluetoothDisabled

```swift
case bluetoothDisabled
```

- **Error Code:** 2
- **Description:** Phone: Bluetooth is disabled, please go to settings to enable it

### bluetoohUnsupported

```swift
case bluetoohUnsupported
```

- **Error Code:** 3
- **Description:** Phone: Device does not support Bluetooh Low Energy

### saveAuthKeyFailed

```swift
case saveAuthKeyFailed
```

- **Error Code:** 4
- **Description:** Keychain: Failed to save the key in keychain

### keyNotFound

```swift
case keyNotFound
```

- **Error Code:** 5
- **Description:** Keychain: Authentication key not found

### keyInvalid

```swift
case keyInvalid
```

- **Error Code:** 6
- **Description:** BLE: Authentication key is invalid

### terminalNotFound

```swift
case terminalNotFound
```

- **Error Code:** 7
- **Description:** BLE Scan: Terminal not found

### notConnected

```swift
case notConnected
```

- **Error Code:** 8
- **Description:** Not connected to Ble Terminal

### ctgError(Int, Int, String)

```swift
case ctgError(Int, Int, String)
```

Failed due to Terminal action, refer to `CtgError`

- **Parameters:**
  - Action code (Int)
  - Error code (Int)
  - Description (String)

## See Also

- [CtgError](./ctg-error.md) - Terminal-specific error codes
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For receiving error callbacks
- [BleTerminal](./ble-terminal.md) - Terminal operations that can produce errors

---

# BleService

Source: https://developer.cartrack.com/docs/mikey-ios/ble-service

**Class**: `BleService`

The entry point for the Cartrack BLE Lock SDK. Call `BleService.getTerminal(terminalID:)` with a Terminal ID to obtain a `BleTerminal` instance.

## Methods

### getTerminal(terminalID:)

Get an instance of BleTerminal

```swift
public static func getTerminal(terminalID: String) -> BleTerminal
```

#### Parameters

- `terminalID: String` - Terminal ID with maximum length of 11 characters

#### Returns

`BleTerminal` - An instance of BleTerminal for the specified terminal ID

## See Also

- [BleTerminal](./ble-terminal.md) - Terminal interaction interface
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For handling terminal events

---

# BleSignalStrength

Source: https://developer.cartrack.com/docs/mikey-ios/ble-signal-strength

**Enum**: `BleSignalStrength`

Ble Terminal signal strength

## Cases

### unknown

```swift
case unknown
```

Initial state

### strong

```swift
case strong
```

Signal to terminal is strong

### good

```swift
case good
```

Signal to terminal is good

### weak

```swift
case weak
```

Signal to terminal is weak

## See Also

- [BleTerminal](./ble-terminal.md) - For signal strength property
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For signal update callbacks

---

# BleTerminal

Source: https://developer.cartrack.com/docs/mikey-ios/ble-terminal

**Class**: `BleTerminal`

Provide interaction to Ble Terminal. Call `BleService.getTerminal(terminalID:)` to get an instance of BleTerminal.

## Properties

### delegate: BleTerminalDelegate?

```swift
public weak var delegate: BleTerminalDelegate?
```

The object that acts as the delegate of the Ble Terminal

### hasKey: Bool

```swift
public var hasKey: Bool { get }
```

Indicate whether terminal authentication key is available

### authKey: String?

```swift
public var authKey: String? { get }
```

Indicate the terminal authentication key

### connectionState: BleConnectionState

```swift
public private(set) var connectionState: BleConnectionState { get }
```

Indicate current connection state to Ble Terminal

### signalStrength: BleSignalStrength

```swift
public private(set) var signalStrength: BleSignalStrength { get }
```

Indicate current signal strength to Ble Terminal

### terminalID: String

```swift
public private(set) var terminalID: String { get }
```

Terminal ID

### lockState: LockState

```swift
public private(set) var lockState: LockState { get }
```

Indicate current vehicle door lock state, updated upon connect, lock, unlock, and lockState action

### ignitionState: IgnitionState

```swift
public private(set) var ignitionState: IgnitionState { get }
```

Indicate current vehicle ignition state, updated upon ignitionState action

## Methods

### saveAuthKey(authKey:)

```swift
public func saveAuthKey(authKey: String)
```

Save authentication key to keychain

#### Parameters

- `authKey: String` - Authentication key

#### Returns

Via delegate function `BleTerminalDelegate.bleTerminalDidSavedKey(terminal:error:)`

### removeAuthKey()

```swift
public func removeAuthKey()
```

Remove authentication key from keychain. Call this when vehicle rental is done

### connect(timeout:)

```swift
public func connect(timeout: Float = 10.0)
```

Connect to Ble Terminal

#### Parameters

- `timeout: Float` - How many seconds to wait for connection (default: 10.0)

#### Returns

Via delegate function `BleTerminalDelegate.bleTerminalDidConnect(terminal:error:)`

### disconnect()

```swift
public func disconnect()
```

Disconnect from Ble Terminal

#### Returns

Via delegate function `BleTerminalDelegate.bleTerminalDisconnected(terminal:)`

### getVehicleStats()

```swift
public func getVehicleStats()
```

Get vehicle stats from Ble Terminal

#### Returns

Via delegate function `BleTerminalDelegate.bleTerminalDidGetVehicleStats(terminal:vehicleStats:error:)`

### sendAction(_:)

```swift
public func sendAction(_ action: BleAction)
```

Send action to Ble Terminal. Avoid calling this if signal is weak, ask user to get closer to terminal first

#### Parameters

- `action: BleAction` - The action to send to the terminal

#### Returns

Via delegate method `BleTerminalDelegate.bleTerminalDidAction(terminal:action:error:)`

## See Also

- [BleService](./ble-service.md) - For obtaining terminal instances
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For handling callbacks
- [BleAction](./ble-action.md) - Available actions
- [BleConnectionState](./ble-connection-state.md) - Connection states
- [BleSignalStrength](./ble-signal-strength.md) - Signal strength levels
- [LockState](./lock-state.md) - Lock state values
- [IgnitionState](./ignition-state.md) - Ignition state values

---

# BleTerminalDelegate

Source: https://developer.cartrack.com/docs/mikey-ios/ble-terminal-delegate

**Protocol**: `BleTerminalDelegate : AnyObject`

Delegate methods that will be called when Ble terminal received responses or changed states

## Methods

### bleTerminalDidSavedKey(terminal:error:)

```swift
func bleTerminalDidSavedKey(terminal: BleTerminal, error: BleError?)
```

Called when `saveAuthKey()` function call has received response or error

#### Parameters

- `terminal: BleTerminal` - The terminal instance
- `error: BleError?` - Error if save failed, nil if successful

### bleTerminalDidConnect(terminal:error:)

```swift
func bleTerminalDidConnect(terminal: BleTerminal, error: BleError?)
```

Called when `connect()` function call has received response or error

#### Parameters

- `terminal: BleTerminal` - The terminal instance
- `error: BleError?` - Error if connection failed, nil if successful

### bleTerminalDidAction(terminal:action:error:)

```swift
func bleTerminalDidAction(terminal: BleTerminal, action: BleAction, error: BleError?)
```

Called when `sendAction()` function call has received response or error

#### Parameters

- `terminal: BleTerminal` - The terminal instance
- `action: BleAction` - The action that was executed
- `error: BleError?` - Error if action failed, nil if successful

### bleTerminalDisconnected(terminal:)

```swift
func bleTerminalDisconnected(terminal: BleTerminal)
```

Called when Ble Terminal get disconnected

#### Parameters

- `terminal: BleTerminal` - The terminal instance

### bleTerminalSignalUpdate(rssi:strength:)

```swift
func bleTerminalSignalUpdate(rssi: Int, strength: BleSignalStrength)
```

Called periodically to update the BLE signal strength to Ble Terminal

#### Parameters

- `rssi: Int` - The RSSI value in dBm
- `strength: BleSignalStrength` - The interpreted signal strength level

### bleTerminalDidGetVehicleStats(terminal:vehicleStats:error:)

```swift
func bleTerminalDidGetVehicleStats(terminal: BleTerminal, vehicleStats: VehicleStats?, error: BleError?)
```

Called when `getVehicleStats()` function has received response or error

#### Parameters

- `terminal: BleTerminal` - The terminal instance
- `vehicleStats: VehicleStats?` - The vehicle statistics if successful
- `error: BleError?` - Error if request failed, nil if successful

## See Also

- [BleTerminal](./ble-terminal.md) - Terminal interface
- [BleError](./ble-error.md) - Error types
- [BleAction](./ble-action.md) - Available actions
- [VehicleStats](./vehicle-stats.md) - Vehicle statistics model
- [BleSignalStrength](./ble-signal-strength.md) - Signal strength levels

---

# CtgError

Source: https://developer.cartrack.com/docs/mikey-ios/ctg-error

**Enum**: `CtgError`

Terminal action failed error types

**Conforms to**: `Error`, `CustomNSError`

## Properties

### errorCode: Int

```swift
public var errorCode: Int { get }
```

Error code

### localizedDescription: String

```swift
public var localizedDescription: String { get }
```

Error description

## Error Cases

### invalidKey

```swift
case invalidKey
```

- **Error Code:** 21
- **Description:** Terminal error: Invalid key

### timeout

```swift
case timeout
```

- **Error Code:** 22
- **Description:** Terminal error: Timeout

### fail

```swift
case fail
```

- **Error Code:** 23
- **Description:** Terminal error: Failed (default return value)

### noKey

```swift
case noKey
```

- **Error Code:** 24
- **Description:** Terminal error: No key

### unsuccessful

```swift
case unsuccessful
```

- **Error Code:** 25
- **Description:** Terminal error: Unsuccessful

### scriptFail

```swift
case scriptFail
```

- **Error Code:** 26
- **Description:** Terminal error: Script failed

### noScript

```swift
case noScript
```

- **Error Code:** 27
- **Description:** Terminal error: No script

### unknownState

```swift
case unknownState
```

- **Error Code:** 28
- **Description:** Terminal error: Unknown state

## See Also

- [BleError](./ble-error.md) - Main BLE error handling (contains ctgError case)
- [BleAction](./ble-action.md) - Actions that can result in CTG errors
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For receiving error callbacks

---

# iOS SDK: Getting started

Source: https://developer.cartrack.com/docs/mikey-ios/getting-started

This guide explains how to install the Cartrack BLE Lock SDK for iOS and run the basic connection flow against a compatible BLE terminal.

## Installation

The SDK package is provided by Cartrack on request. If you do not have it yet, see [Request SDK access](../mobile-sdks/request-sdk.mdx).

- Add the **CartrackBleLock.xcframework** folder (provided to you by Cartrack) to your Xcode project.
- In **Project Settings → Frameworks, Libraries, and Embedded Content**, set **CartrackBleLock.xcframework** to **Embed & Sign**.

## Overview

The Cartrack BLE Lock SDK provides a simple and secure way to:
- Connect to BLE-enabled vehicle terminals
- Lock and unlock vehicles remotely
- Control vehicle features (headlights, horn)
- Monitor vehicle status and statistics
- Receive real-time connection and signal strength updates

## Core Components

### [BleService](./ble-service.md)
The entry point for the SDK. Use `BleService.getTerminal(terminalID:)` to obtain a `BleTerminal` instance for interacting with a specific vehicle terminal.

### [BleTerminal](./ble-terminal.md)
Provides direct interaction with a BLE terminal. Handles connection management, authentication, and command execution.

### [BleTerminalDelegate](./ble-terminal-delegate.md)
Protocol for receiving callbacks from BLE terminal events, including connection state changes, action results, and vehicle statistics updates.

### [VehicleStats](./vehicle-stats.md)
Data model containing comprehensive vehicle statistics including odometer, fuel level, door states, and more.

## Quick Start

> **All examples require `import CartrackBleLockSDK` in the source file.**
>
> **Before connecting, initialize `BleTerminal` and save the authentication key.**
>
> **Your class must conform to `BleTerminalDelegate` to receive callbacks.**

### 1. Initialize BleTerminal

Initialize `BleTerminal` variable to get an instance of BleTerminal and set the delegate:

```swift
var bleTerminal: BleTerminal

bleTerminal = BleService.getTerminal(terminalID: "SBS1234X")
bleTerminal.delegate = self
```

### 2. Save Authentication Key

Save the authentication key with `BleTerminal.saveAuthKey(authKey:)`:

```swift
bleTerminal?.saveAuthKey(authKey: "<Authentication Key>")
```

> The authentication key is saved in the keychain.

> **IMPORTANT:** The authentication key must be saved before connecting to the BLE terminal.

The response for `BleTerminal.saveAuthKey(authKey:)` will be in `BleTerminalDelegate.bleTerminalDidSavedKey(terminal:error:)`:

```swift
func bleTerminalDidSavedKey(terminal: BleTerminal, error: BleError?) {
    if let error = error {
      self.showMessage(title: "Save Key Failed", message: "\(error.errorCode) \(error.localizedDescription)")
    } else {
      self.showMessage(title: "Save Key Successful", message: "Successful save authentication key!")
    }
}
```

### 3. Check Authentication Key

Check whether an authentication key exists in the keychain with `BleTerminal.hasKey`:

```swift
bleTerminal?.hasKey
```

> Output: `true` or `false`

### 4. Get Authentication Key

Get the authentication key from the keychain with `BleTerminal.authKey`:

```swift
bleTerminal?.authKey
```

> Output: `<Authentication Key>` or `nil`

### 5. Connect to Ble Terminal

Connect to Ble Terminal with `BleTerminal.connect()`:

```swift
bleTerminal?.connect()
```

> By default `timeout` in `BleTerminal.connect(timeout:)` is 10 sec.

Alternatively, if you want to extend the timeout:

```swift
bleTerminal?.connect(timeout: 20)
```

> `BleTerminal.connect()` and `BleTerminal.connect(timeout:)` are the same function. If the key exists in the keychain, the SDK sends the connect command to the terminal; otherwise it returns `BleError.keyNotFound`.

The response for `BleTerminal.connect(timeout:)` will be in `BleTerminalDelegate.bleTerminalDidConnect(terminal:error:)`:

```swift
func bleTerminalDidConnect(terminal: BleTerminal, error: BleError?) {
    if let error = error {
      showMessage(title: "Failed to connect", message: "\(error.errorCode) \(error.localizedDescription)")
    } else {
      showMessage(title: "Connect Successful", message: "")
    }
}
```

### 6. Disconnect from Ble Terminal

Disconnect from Ble Terminal with `BleTerminal.disconnect()`:

```swift
bleTerminal?.disconnect()
```

> This function will send a disconnect command to the terminal.

The response for `BleTerminal.disconnect()` will be in `BleTerminalDelegate.bleTerminalDisconnected(terminal:)`:

```swift
func bleTerminalDisconnected(terminal: BleTerminal) {
    showMessage(title: "", message: "Disconnected")
}
```

### 7. Terminal Signal Update

Called periodically to update the BLE signal strength to Ble Terminal:

```swift
func bleTerminalSignalUpdate(rssi: Int, strength: BleSignalStrength) {
    rssiLabel.text = "RSSI: \(rssi) dBm (\(strength))"
}
```

### 8. Remove Authentication Key

Remove the authentication key in the keychain with `BleTerminal.removeAuthKey()`:

```swift
bleTerminal?.removeAuthKey()
```

> Call this function when vehicle rental is done.

> The authentication key in the keychain will be removed.

### 9. Send Ble Action to Terminal

Send lock action to terminal:

```swift
bleTerminal?.sendAction(.lock)
```

Send unlock action to terminal:

```swift
bleTerminal?.sendAction(.unlock)
```

Send headlight action to terminal:

```swift
bleTerminal?.sendAction(.headlight)
```

Send horn action to terminal:

```swift
bleTerminal?.sendAction(.horn)
```

Get the current state of vehicle's lock status - possible value - `locked`/`unlocked`:

```swift
bleTerminal?.sendAction(.lockState)
```

> The default value of `BleTerminal.lockState` is `LockState.unknown`, send `BleAction.lockState` action to refresh the state.

Send unlock with no key fob action to terminal:

```swift
bleTerminal?.sendAction(.unlockNoKeyFob)
```

Get the current state of vehicle's ignition status - possible value - `on`/`off`:

```swift
bleTerminal?.sendAction(.ignitionState)
```

> The default value of `BleTerminal.ignitionState` is `IgnitionState.unknown`, send `BleAction.ignitionState` action to refresh the state.

The response for all `BleAction` will be in `BleTerminalDelegate.bleTerminalDidAction(terminal:action:error:)`:

```swift
func bleTerminalDidAction(terminal: BleTerminal, action: BleAction, error: BleError?) { 
    if let error = error {
      showMessage(title: "Action Failed", message: "[\(error.actionCode)] get vehicle stats Failed\nReason: [\(error.errorCode)] \(error.localizedDescription)")
    } else {
        switch action {
        case .lock:
            showMessage(title: "Action", message: "Lock Action Success\nLock state: [\(terminal.lockState)]")
        case .unlock:
            showMessage(title: "Action", message: "Unlock Action Success\nLock state: [\(terminal.lockState)]")
        case .horn:
            showMessage(title: "Action", message: "Horn Action Success")
        case .headlight:
            showMessage(title: "Action", message: "Headlight Action Success")
        case .lockState:
            showMessage(title: "Action", message: "Vehicle's door is \(terminal.lockState)")
        case .unlockNoKeyFob:
          showMessage(title: "Action", message: "Unlock with No Key Fob Action Success\nLock state: [\(terminal.lockState)]")
        case .ignitionState:
          showMessage(title: "Action", message: "Vehicle's ignition state is \(terminal.ignitionState)")
        @unknown default:
            break
        }
    }
}
```

### 10. Get Vehicle Stats from Terminal

Send vehicle stats to Terminal:

```swift
bleTerminal?.getVehicleStats()
```

The response for `BleTerminal.getVehicleStats()` will be in `BleTerminalDelegate.bleTerminalDidGetVehicleStats(terminal:vehicleStats:error:)`:

```swift
func bleTerminalDidGetVehicleStats(terminal: BleTerminal, vehicleStats: VehicleStats?, error: BleError?) {
  if let error = error {
    showMessage(title: "Action Failed", message: "[\(error.errorCode)] get vehicle stats Failed\nReason: \(error.localizedDescription)")
  } else {
      print(vehicleStats?.odometer)
      print(vehicleStats?.fuelLevel)
  }
}
```

## API Reference

### Core Classes
- [BleService](./ble-service.md) - SDK entry point
- [BleTerminal](./ble-terminal.md) - Terminal interaction interface
- [VehicleStats](./vehicle-stats.md) - Vehicle statistics data model

### Protocols
- [BleTerminalDelegate](./ble-terminal-delegate.md) - Event handling protocol

### Enumerations
- [BleAction](./ble-action.md) - Available terminal actions
- [BleConnectionState](./ble-connection-state.md) - Connection states
- [BleSignalStrength](./ble-signal-strength.md) - Signal strength levels
- [BleError](./ble-error.md) - Error types
- [CtgError](./ctg-error.md) - Terminal-specific errors
- [LockState](./lock-state.md) - Vehicle lock states
- [IgnitionState](./ignition-state.md) - Vehicle ignition states
- [IndicatorState](./indicator-state.md) - Vehicle indicator states

## Best Practices

### Connection Management
- Always check `hasKey` before attempting to connect
- Use appropriate timeout values (default 10 seconds recommended)
- Handle disconnection events gracefully

### Signal Strength Monitoring
- Monitor signal strength via `bleTerminalSignalUpdate` delegate method
- Avoid sending actions when signal is `.weak`
- Prompt users to move closer to the vehicle when signal is poor

### Error Handling
- Always handle errors in delegate callbacks
- Check for specific error types to provide better user feedback
- Use `error.localizedDescription` for user-facing error messages

### Resource Cleanup
- Call `removeAuthKey()` when rental period ends
- Call `disconnect()` when done with terminal interaction
- Properly manage delegate lifecycle to avoid memory leaks

## Next Steps

- Review the [BleService](./ble-service.md) documentation for SDK initialization
- Learn about [BleTerminal](./ble-terminal.md) methods and properties
- Understand [BleTerminalDelegate](./ble-terminal-delegate.md) callbacks
- Explore [BleError](./ble-error.md) handling strategies

---

# IgnitionState

Source: https://developer.cartrack.com/docs/mikey-ios/ignition-state

**Enum**: `IgnitionState`

Vehicle ignition `on/off` state

## Cases

### unknown

```swift
case unknown
```

Unknown state, send `.ignitionState` action to refresh the state

### on

```swift
case on
```

The current state of vehicle's ignition is on

### off

```swift
case off
```

The current state of vehicle's ignition is off

## See Also

- [BleTerminal](./ble-terminal.md) - For ignitionState property
- [BleAction](./ble-action.md) - For ignitionState action
- [VehicleStats](./vehicle-stats.md) - For engine-related statistics
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For action callbacks

---

# IndicatorState

Source: https://developer.cartrack.com/docs/mikey-ios/indicator-state

**Enum**: `IndicatorState : Int`

Indicator states for `VehicleStats.indicators`

## Properties

### description: String

```swift
public var description: String { get }
```

Indicator description: `Off`, `Left`, `Right`, `Both`

## Cases

### off = 0

```swift
case off = 0
```

The current state of vehicle's Indicator is `off`

### left

```swift
case left
```

The current state of vehicle's Indicator is `left`

### right

```swift
case right
```

The current state of vehicle's Indicator is `right`

### both

```swift
case both
```

The current state of vehicle's Indicator is `both`

## See Also

- [VehicleStats](./vehicle-stats.md) - Contains indicators property
- [BleTerminal](./ble-terminal.md) - For getting vehicle stats
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For receiving stats in callback

---

# LockState

Source: https://developer.cartrack.com/docs/mikey-ios/lock-state

**Enum**: `LockState`

Vehicle door `lock/unlock` state

## Cases

### unknown

```swift
case unknown
```

Unknown state, send `.lockState` action to refresh the state

### locked

```swift
case locked
```

The current state of vehicle's door is locked

### unlocked

```swift
case unlocked
```

The current state of vehicle's door is unlocked

## See Also

- [BleTerminal](./ble-terminal.md) - For lockState property
- [BleAction](./ble-action.md) - For lock/unlock/lockState actions
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For action callbacks

---

# Logger

Source: https://developer.cartrack.com/docs/mikey-ios/logger

**Class**: `Logger`

```swift
public class Logger
```

## Properties

### isLoggingEnabled

```swift
public static var isLoggingEnabled: Bool
```

## Methods

### log(_:)

```swift
public static func log(_ message: String)
```

## See Also

- [BleService](./ble-service.md) - SDK entry point
- [BleTerminal](./ble-terminal.md) - Terminal interaction interface

---

# iOS

Source: https://developer.cartrack.com/docs/mikey-ios/



---

# Overview

Source: https://developer.cartrack.com/docs/mikey-ios/overview

The Mikey iOS SDK enables iOS applications to communicate with compatible Cartrack in‑vehicle terminals over Bluetooth Low Energy (BLE) for short‑range vehicle access and status retrieval.

## What you can do

- Connect to a nearby BLE terminal associated with a vehicle.
- Perform supported actions (for example, lock and unlock).
- Retrieve supported vehicle status and statistics.
- Receive connection state, signal strength, and action callbacks via the delegate protocol.

## Where to start

- The SDK package is provided on request: see [Request SDK access](../mobile-sdks/request-sdk.mdx).
- Follow the Getting Started guide to add the SDK to your Xcode project and run your first connection flow.
- Use the API Reference pages for details on the core classes, protocols, and enumerations.

## Important notes

- BLE behavior may vary depending on the iOS version and device.
- Command availability depends on vehicle hardware and provisioning.

---

# Release Notes

Source: https://developer.cartrack.com/docs/mikey-ios/release-notes

:::info
SDK packages are provided on request. See [Request SDK access](../mobile-sdks/request-sdk.mdx).
:::

### V3.0.1

* Fixed `VehicleStats.lightsIsOn` displaying an incorrect value
* Fixed improper state handling when an invalid key is detected, ensuring the internal timer stops immediately after returning the invalidKey error (Error Code 21) to prevent subsequent timeout errors.
* Added `VehicleStats.reverseGearIsActive` to get the status of reverse gear
* Support terminal IDs up to 14 characters

### V3.0

**Notice: This version has breaking changes.**

#### Before

From the first SDK version until version 2.4.1, the Bluetooth keys were managed by the SDK, communicating with the Cartrack servers:

* Obtaining the key
* Key randomisation

#### After

This new SDK is simpler, and the keys can be managed at [Cartrack Fleet API](https://developer.cartrack.com/fleet-api) level. Using the API, you can fetch the Bluetooth keys ahead of time and reuse them for multiple bookings. Have a look at the following endpoints:

* GET /mikey/:registration to get the key for a given vehicle registration
* GET /mikey, to get the keys for all your vehicles
* POST /mikey/:registration, to randomise the key for a given vehicle registration

For improved security, you can randomise keys at your convenience. We recommend changing keys only when there is enough time between two users so the vehicle can receive the new key and the user can load it on the phone.

##### Release details

* Added `BleTerminal.authKey` to indicate the terminal authentication key
* Added `BleTerminal.saveAuthKey(authKey:)` to save authentication key to keychain
* Added `BleError.actionCode` to indicate the action code. The action code only use for `CtgError`, for other error will return `-1`
* Removed `BleService.configure(vendorID:apiKey:countryCode:apiUrl:)`
* Removed `BleTerminal.getAuthKey()`
* Removed `BleTerminal.randomAuthKey()`
* Removed `BleTerminalDelegate.bleTerminalDidGetKey(terminal:error:)`
* Removed `BleTerminalDelegate.bleTerminalDidRandomAuthKey(terminal:error:)`
* Removed unused error and combine `BleConnectionError`, `BleActionError`, and `BleKeyError` to `BleError`
* Updated error code in `BleError` and `CtgError`

### V2.4.1

* Support terminal IDs up to 12 characters
* Fixed a bug affecting rare scenarios where the advertised BLE name is changed
* Fixed `VehicleStats.lightsIsOn` display an incorrect value
* Added `VehicleStats.reverseGearIsActive` to get the status of reverse gear

### V2.4

* Added upper case method in `terminalID`, convert the string to upper case by default
* Added upper case method in `countryCode`, convert the string to upper case by default
* Added `BleKeyError.saveKeyFailed` to return the error for the key when failed to save in keychain
* Added `BleKeyError.responseError(_:_:)` to return the error from API
* Added `BleKeyError.serverError(_:_:)` to return the error from server
* Added `BleConnectionError.bleKeyError(_:_:)` to return the error from Ble key
* Added `CtgError` to indicate terminal action failed error types
* Added `BleKeyError` and `CtgError` error response in `BleConnectionError`
* Added `CtgError` error response in `BleActionError`
* Added `VehicleStats` class for vehicle stats
* Added `IndicatorState` for indicators in `VehicleStats`
* Added a function `BleTerminal.getVehicleStats()` to get vehicle stats from Ble Terminal
* Added `BleAction.ignitionState` to get the current state of vehicle's ignition
* Added `BleTerminal.ignitionState` to indicate current vehicle's ignition state
* Receive `BleTerminal.getVehicleStats()` response in `BleTerminalDelegate.bleTerminalDidGetVehicleStats(terminal:vehicleStats:error:)`
* Updated error code and localized description for `BleConnectionError`, `BleActionError`, `BleKeyError` and `CtgError`

### V2.3

* Added a function `BleAction.unlockNoKeyFob` to send an unlock command `Unlock_0` that doesn't activate the key fob. The driver won't be able to start the engine.
* Receive `BleAction.unlockNoKeyFob` response in `BleTerminalDelegate.bleTerminalDidAction(terminal:action:error:)`

### V2.1.1

* Bugfix for `BleService.configure(vendorID:apiKey:countryCode:apiUrl:)`
* Added `BleTerminal.randomAuthKey()` to random the terminal authentication key
* Added `BleTerminalDelegate.bleTerminalDidRandomAuthKey(terminal:error:)` protocol to receive a response or error from `BleTerminal.randomAuthKey()`
* Updated `BleTerminal.removeAuthKey()` to remove the authentication key from keychain without random authentication key
* The keychain will only save one authentication key with a static name. If wish to use another terminal id or new authentication key, must remove the current authentication key before fetching the new authentication key.

### V2.1

* Added a new parameter `apiUrl` in `BleService.configure(vendorID:apiKey:countryCode:apiUrl:)`
* Use `BleService.configure(vendorID:apiKey:countryCode:)` for default API URL
* Use `BleService.configure(vendorID:apiKey:countryCode:apiUrl:)` for custom API URL

### V2.0

* Add a new parameter `countryCode` in `BleService.configure(vendorID:apiKey:countryCode:)` Please refer to https://iban.com/country-codes for the country code alpha-2 format.

### V1.2

* Fixed intermittent CRC fail during connection

### V1.1

* Added `BleTerminal.lockState` to indicate vehicle's lock state
* Added `BleAction.lockState` action to get the latest vehicle's lock state

### V1.0

* Initial release

---

# VehicleStats

Source: https://developer.cartrack.com/docs/mikey-ios/vehicle-stats

**Class**: `VehicleStats`

Model for vehicle stats

## Properties

### odometer: Double

```swift
public var odometer: Double
```

Odometer value return in `km`

### engineHours: Int

```swift
public var engineHours: Int
```

Engine Hours value return in `hour`

### engineRPM: Int

```swift
public var engineRPM: Int
```

Engine RPM value return in `Int`, RPM `x1000`

### fuelLevel: Int

```swift
public var fuelLevel: Int
```

Fuel Level value return in `Int`

### hazardsIsOn: Bool

```swift
public var hazardsIsOn: Bool
```

Hazards value return in Boolean, `true` is On, `false` is Off

### indicators: IndicatorState

```swift
public var indicators: IndicatorState
```

Indicators value: `Off`, `Left`, `Right`, `Both`

### brakesIsActive: Bool

```swift
public var brakesIsActive: Bool
```

Brakes value return in Boolean, `true` is Active, `false` is Inactive

### handBrakeIsActive: Bool

```swift
public var handBrakeIsActive: Bool
```

Hand Brake value return in Boolean, `true` is Active, `false` is Inactive

### lightsIsOn: Bool

```swift
public var lightsIsOn: Bool
```

Lights value return in Boolean, `true` is On, `false` is Off

### reverseGearIsActive: Bool

```swift
public var reverseGearIsActive: Bool
```

Reverse Gear value return in Boolean, `true` is Active, `false` is Inactive

### driverDoorIsOpen: Bool

```swift
public var driverDoorIsOpen: Bool
```

Driver door value return in Boolean, `true` is Open, `false` is Closed

### passengerDoorIsOpen: Bool

```swift
public var passengerDoorIsOpen: Bool
```

Passenger door value return in Boolean, `true` is Open, `false` is Closed

### driverSeatbeltIsEngage: Bool

```swift
public var driverSeatbeltIsEngage: Bool
```

Driver seatbelt value return in Boolean, `true` is Engage, `false` is Not Engage

### passengerSeatbeltIsEngage: Bool

```swift
public var passengerSeatbeltIsEngage: Bool
```

Passenger seatbelt value return in Boolean, `true` is Engage, `false` is Not Engage

### hornIsActive: Bool

```swift
public var hornIsActive: Bool
```

Horn value return in Boolean, `true` is Active, `false` is Inactive

## See Also

- [BleTerminal](./ble-terminal.md) - For requesting vehicle stats
- [BleTerminalDelegate](./ble-terminal-delegate.md) - For receiving stats in callback
- [IndicatorState](./indicator-state.md) - Indicator state enumeration

---

# Overview

Source: https://developer.cartrack.com/docs/mobile-sdks/overview

Mikey is Cartrack’s mobile SDK for integrating vehicle access control into your applications. It enables secure, short-range communication with compatible in‑vehicle hardware and provides access to a subset of vehicle features through the Cartrack platform.

## Features

### Vehicle access control

The Android and iOS SDKs enable secure communication with the vehicle to execute actions such as **Lock** and **Unlock**. Availability and effective range depend on the vehicle hardware and environmental conditions.

### Access management

Manage user permissions to allow or restrict access to vehicles based on your requirements.

### Vehicle data insights

Access near real-time vehicle information, including:

- Central locking system status
- Fuel or EV battery level
- Geolocation
- Odometer readings
- More data points as needed

## Getting started

The SDK packages are provided on request: see [Request SDK access](./request-sdk.mdx).

Use the platform guides below for setup and integration:

- [Android SDK](../applications/mikey-android)
- [iOS SDK](../applications/mikey-ios)
- [Fleet API documentation](../applications/fleet-api) for additional remote control and management options

---

# Request SDK access

Source: https://developer.cartrack.com/docs/mobile-sdks/request-sdk

The Mikey mobile SDK for Android and iOS is provided on request.

Fill in the form below and submit your request. Our team will review it and
get back to you with the SDK package and integration guidance.

_Interactive content, see https://developer.cartrack.com/docs/mobile-sdks/request-sdk_

---

# Telematics Event Specification

Source: https://developer.cartrack.com/docs/telematics-data-ingestion/events

:::info[Beta]
Telematics data ingestion is in beta and is enabled for a limited number of partners and customers, so its behaviour may still change.

If you are interested in sending telematics data to Cartrack, reach out to your Cartrack contact person to discuss access.
:::

Use this schema when sending telematics events to Cartrack.

## API reference

The ingestion endpoint also has an interactive OpenAPI reference, hosted per region. Both regions serve the same contract, so use the one for the host you send to:

- Africa: [Data Ingestion reference](https://docs-af-webhooks-prod.cartrack.com/api/telematics-ingest#tag/Data-Ingestion)
- Asia: [Data Ingestion reference](https://docs-as-webhooks-prod.cartrack.com/api/telematics-ingest#tag/Data-Ingestion)

## Important notes

- Time must be in **UTC**, ISO-8601 format
- Enforce **event uniqueness** (e.g., via `provider_event_id`)
- Validate that `event_ts <= ingested_at + tolerance` (ingestion time is server-side)
- Version the schema or route to support future changes
- Odometer unit is **kilometers**

## Example payload

```json
{
  "event_type": "PERIODIC",
  "event_ts": "2026-01-19T08:42:15Z",

  "chassis_number": "ABC12345678901234",
  "registration": "XX00XXGP",

  "source": {
    "provider": "third_party_x",
    "device_id": "IMEI123456789",
    "provider_event_id": "evt-984739287",
    "provider_received_ts": "2026-01-19T08:42:18Z"
  },

  "position": {
    "latitude": 1.3521,
    "longitude": 103.8198,
    "altitude": 15
  },

  "telemetry": {
    "speed": 54,
    "ignition": true,
    "rpm": 2200,
    "odometer": 45231.4
  }
}
```

## Field definitions

### Top-level fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| event_type | string | yes | `IGNITION_ON`, `IGNITION_OFF`, `PERIODIC` |
| event_ts | ISO-8601 UTC | yes | Time when event occurred on device |
| chassis_number | string | yes | Vehicle Identification Number (VIN), **exactly 17 characters** |
| registration | string | optional | Vehicle registration (number plate), max 100 characters. See [Vehicle registration](#vehicle-registration) |
| source | object | yes | Identifies the event origin |
| position | object | conditional | Required for location events |
| telemetry | object | optional | Vehicle signals |

### Vehicle registration

`chassis_number` is the required identifier and is what every event is matched on. `registration` is optional and identifies the same vehicle by its number plate.

Send it when you have it. For a vehicle Cartrack does not yet track, the plate you send will be used when the vehicle is created, instead of a generated placeholder that your fleet would otherwise see next to its real plates. This is rolling out progressively, so a vehicle created today may still show the placeholder.

- **Optional.** Omitting it changes nothing else about how your events are processed.
- **Blank counts as omitted.** An empty or whitespace-only value is discarded and the event is still accepted, so there is no need to filter out vehicles you hold no plate for.
- **Normalized on arrival.** Leading and trailing whitespace is trimmed and the value is upper-cased, matching how Cartrack stores plates. Punctuation and inner spacing are preserved, so `ab-12 cd` is stored as `AB-12 CD`.
- **Must be the vehicle's real plate.** A plate already in use on another vehicle will not be applied, and the placeholder is used instead.
- **Used at creation.** It will not rename a vehicle Cartrack already tracks. Tell Cartrack support if a plate needs changing on an existing vehicle.

### `source`

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| provider | string | yes | Logical source name |
| device_id | string | optional | IMEI, serial, etc. |
| provider_event_id | string | recommended | Used for idempotency |
| provider_received_ts | ISO-8601 UTC | optional | When provider received the event |

### `position`

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| latitude | number | yes | Decimal degrees |
| longitude | number | yes | Decimal degrees |
| altitude | number | optional | Meters above sea level |

### `telemetry`

| Field | Type | Required | Units / Notes |
|-------|------|----------|---------------|
| speed | number | yes | km/h |
| ignition | boolean | yes | `true` = ON |
| rpm | number | optional | Revolutions per minute |
| odometer | number | yes | Kilometers |

## Event-type expectations

These are the event types supported today. `event_type` is validated against this list, so an event carrying any other value is rejected. More types will be added progressively, so check this page or ask your Cartrack contact person before building around a type that is not listed yet.

| Event type | Position | Telemetry |
|------------|----------|-----------|
| IGNITION_ON | required | Marks the beginning of a trip |
| IGNITION_OFF | required | Marks the end of a trip |
| PERIODIC | required | Recommended. Used to plot the path taken by the vehicle |

---

# Telematics Data Ingestion

Source: https://developer.cartrack.com/docs/telematics-data-ingestion/overview

:::info[Beta]
Telematics data ingestion is in beta and is enabled for a limited number of partners and customers, so its behaviour may still change.

If you are interested in sending telematics data to Cartrack, reach out to your Cartrack contact person to discuss access.
:::

This page describes how customers or third-party data providers can deliver telematics events into Cartrack.

## Who this is for

- Partners sending vehicle location and telemetry from their own devices/platforms
- Customers consolidating data from multiple hardware vendors
- Integrators evaluating payload and delivery requirements ahead of onboarding

## What you send

- JSON events conforming to the telemetry schema in the [Event specification](/docs/telematics-data-ingestion/events)
- Payloads must be in UTC and ISO-8601 timestamps
- Each event must be unique; include a stable provider-level identifier to avoid duplicates
- The sending side can be the device itself (formatted per Cartrack requirements) or a provider’s intermediary server that forwards events on behalf of devices

## Delivery expectations

1. Send events over HTTPS to the ingestion endpoint for your region:
	- Africa: `https://af-webhooks-prod.cartrack.com/api/data/ingest/telematics`
	- Asia: `https://as-webhooks-prod.cartrack.com/api/data/ingest/telematics`
2. Authenticate using the `X-API-KEY` header that Cartrack provides for your tenant.
3. Post one JSON event per request.
4. Expect HTTP status codes to reflect acceptance; validation errors will be returned with detail.

## Authentication

- Include `X-API-KEY: <your-key>` on every request. Keys are provisioned by Cartrack.
- Treat the key as a secret

## Data quality guardrails

- `chassis_number` (VIN) is the primary key used to match vehicles across systems. Create the vehicle in Cartrack before sending events for it: an event carrying a VIN that Cartrack does not track is accepted at the endpoint but is not processed, so nothing appears in Fleetweb for that vehicle. Automatic enrollment of unknown VINs is enabled per provider account rather than being available by default, so do not rely on it unless Cartrack has confirmed it for your account.
- Enforce uniqueness using `provider_event_id` or a composite you control
- Ensure `event_ts` is not in the future.
- Use kilometers for odometer values; speed should be in km/h

## Flowchart

```mermaid
flowchart TD
	subgraph CartrackPlatform[Cartrack platform]
		B[HTTPS POST /telematics-ingest]
		C{Validate payload}
		D[Queued for processing]
        F[Vehicle data available in Fleetweb]
	end
	style CartrackPlatform fill:#f97316,fill-opacity:0.2,stroke:#d35400,color:#000,stroke-width:2
	A[Provider device or intermediary server] --> B
	B --> C
	C -- ok --> D
	C -- invalid --> E[Return 4xx with details]
	D --> F
```

## Next steps

Review the detailed [Event specification](/docs/telematics-data-ingestion/events) for field-by-field requirements and an example payload.

The interactive OpenAPI reference for the ingestion endpoint is hosted per region. Both regions serve the same contract, so use the one for the host you send to:

- Africa: [Data Ingestion reference](https://docs-af-webhooks-prod.cartrack.com/api/telematics-ingest#tag/Data-Ingestion)
- Asia: [Data Ingestion reference](https://docs-as-webhooks-prod.cartrack.com/api/telematics-ingest#tag/Data-Ingestion)

---

# Cartrack Fleet API changelog

Source: https://developer.cartrack.com/docs/fleet-api-general/changelog

The latest 20 releases. Older releases: https://developer.cartrack.com/changelog/versions/index.json

## Version 1.26.0930.1 (2026-09-30)

### New Features

- **[Vehicle Commands]:** Added `PUT /vehicles/{registration}/start-inhibit` and `GET /vehicles/start-inhibit/status`. Send `start_inhibit: true` to immobilise a vehicle so it cannot be powered on, and `false` to release it; the status endpoint reports the same field with the same meaning. `start_inhibit: null` means the state cannot be established and is not the same as `false`. A vehicle is listed only when it has an active contract and a terminal fitment that supports the command, a subuser sees only the vehicles granted to it, and `limit` is capped at 100 per page.
- **[Geofences]:** Added `POST /geofences/bulk` and `DELETE /geofences`. `POST /geofences/bulk` creates up to 100 geofences in a single request; each item accepts the same parameters as `POST /geofences` and is validated and created independently, so one invalid item does not reject the rest, and the response returns the IDs of the geofences created. `DELETE /geofences` deletes up to 1000 geofences by ID in a single request and reports the outcome of each ID independently. Both endpoints accept up to 10 requests per minute.

### Improvements

- **[Vehicle Commands]:** `PUT /vehicles/{registration}/immobilise` and `GET /vehicles/immobilise/status` are no longer listed in the API reference. Both keep serving their existing callers; new integrations should use the start-inhibit endpoints above.
- **[Delivery]:** Documented how subuser credentials behave on the Delivery endpoints. Subuser credentials cannot write to Delivery: every `POST`, `PUT` and `DELETE` under `/delivery/` returns HTTP `403 Forbidden`. Most Delivery reads accept them and return the whole account's data with no filtering by subuser, while a few require the main account's api_key and also return `403 Forbidden`. To act on behalf of a subuser, authenticate with the main account's api_key and set `subuser_id`, as a request body field on the delivery jobs and drivers create and update endpoints, and as a column in the uploaded file on `POST /delivery/jobs/bulk-upload`. The `403 Forbidden` responses on the Delivery endpoints now explain the subuser case instead of carrying the generic message.
- **[General]:** HTTP `500 Internal Server Error` responses now include `error.reason`, a machine-readable value that identifies the class of failure: `db_statement_timeout`, `db_unavailable`, `db_resource_exhausted`, `db_error`, `cache_unavailable`, `dependency_unavailable` or `internal_error`. The status code remains `500` for every class.
- **[Health]:** `GET /health` now accepts 2 requests every 20 seconds, up from 1 request every 5 minutes, so it can be polled by uptime monitors.
- **[Trips]:** `GET /trips/{registration}` now accepts a `page` of 1 or more and a `limit` from 1 to 1000, the same range as `GET /trips` and `GET /trips/elapsed`. A `limit` above 1000, or a `page` or `limit` of 0, now returns HTTP `422 Unprocessable Entity`. Use `page` to retrieve more than 1000 trips.
- **[Vehicles]:** On `POST /fuel/level`, `POST /fuel/consumed`, `GET /vehicles/{registration}/events`, `POST /vehicles/soc`, `GET /vehicles/{registration}/soc`, `POST /vehicles/range`, `GET /vehicles/{registration}/range` and `POST /vehicles/ev-consumption`, a `page` or `limit` of 0 now returns HTTP `422 Unprocessable Entity`, and `POST /fuel/level` now enforces its published maximum `limit` of 1000.
- **[Drivers]:** The phone code and phone number of a driver may total at most 20 characters on `POST /drivers`, `PUT /drivers/{driver_id}`, `POST /delivery/drivers` and `PUT /delivery/drivers/{driver_id}`. A longer value returns HTTP `422 Unprocessable Entity`.
- **[General]:** Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Vehicles]:** Fixed an issue where `GET /vehicles/{registration}/odometer` returned an HTTP 5xx error.
- **[Vehicles]:** Fixed an issue where `GET /vehicles/{registration}/status`, `GET /vehicles/{registration}/events` and `GET /vehicles/{registration}/sensors/timeline` returned HTTP `200` instead of HTTP `404 Not Found` for the registration `0`.
- **[Geofences]:** Fixed an issue where `POST /geofences` and `PUT /geofences/{geofence_id}` returned an HTTP 5xx error, or HTTP `200` without saving the geometry, for a malformed `polygon`. Both now return HTTP `422 Unprocessable Entity`.
- **[Groups]:** Fixed an issue where `PUT` and `DELETE` on `/vehicles/groups/{group_id}`, `/vehicles/{registration}/groups/{group_id}`, `/geofences/groups/{group_id}` and `/geofences/{geofence_id}/groups/{group_id}` returned an HTTP 5xx error when `group_id` was not a number. They now return HTTP `422 Unprocessable Entity`.
- **[Settings]:** Fixed an issue where `PUT` and `DELETE` on `/settings/vehicles/custom-fields/{customFieldId}` and `/settings/drivers/custom-fields/{customFieldId}` returned an HTTP 5xx error when the ID was not a number. They now return HTTP `422 Unprocessable Entity`.
- **[Drivers]:** Fixed an issue where `POST /drivers`, `PUT /drivers/{driver_id}` and `POST /delivery/drivers` returned an HTTP 5xx error when the phone code and phone number together exceeded 20 characters.
- **[General]:** Fixed an issue where paginated endpoints, including `GET /trips` and `GET /trips/{registration}`, returned an HTTP 5xx error for a negative `page` or `limit`, or for a very large `page`.

## Version 1.26.0924.1 (2026-09-24)

### Improvements

- **[General]:** Repeated failed authentication attempts are now throttled. Once an account has failed authentication too many times from the same address, further requests from that address for that account receive HTTP `429 Too Many Requests` until the block expires, including requests that carry valid credentials. The response includes the `X-RateLimit-Retry-At` and `X-RateLimit-Retry-After-Seconds` headers, and `error.message` starts with `Too many failed authentication attempts`. Integrations must stop retrying on HTTP `401 Unauthorized` and correct the credentials instead: retrying a rejected password in a loop is what triggers the block. See the Rate Limiting guide for details.
- **[General]:** Reduced per-request overhead on every endpoint by no longer creating server-side session state for stateless API calls.
- **[General]:** Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Delivery]:** Fixed an issue where `GET /delivery/jobs` intermittently returned an HTTP 5xx error.

## Version 1.26.0923.1 (2026-09-23)

### New Features

- **[Drivers]:** Added typed driver custom field definitions and values: `GET`/`POST /settings/drivers/custom-fields` and `PUT`/`DELETE /settings/drivers/custom-fields/{customFieldId}` to manage field definitions, and `PUT /drivers/{driver_id}/custom-fields` to write values. Supports text, long description, number, date, time, date-time, single-select, and multi-select field types.
- **[Drivers]:** Added `custom_field_values` to `GET /drivers`, `GET /drivers/{driver_id}`, `POST /drivers` and `PUT /drivers/{driver_id}`. It returns every active driver custom field configured for your account together with this driver's value, and accepts values by definition id on create and update.

### Improvements

- **[Drivers]:** Deprecated the legacy positional `custom_fields` (`custom_1`..`custom_8`) on the driver endpoints. It is now translated from `custom_field_values`, and values sent in a request are still accepted for backward compatibility but no longer written. Use `custom_field_values` instead.
- **[Drivers]:** Corrected the documented response shape of `GET`/`PUT /drivers/{driver_id}` and `POST /drivers`: the driver is returned inside a `data` object.
- **[General]:** Reduced the occasional very slow responses that could affect any endpoint regardless of the request made.
- **[Trips]:** `ev_battery` is now always present on `GET /trips/{registration}`, returned as `null` on trips that carry no battery data, so the response shape no longer varies from trip to trip.
- **[Countries]:** Corrected the Eswatini server URL in the API reference to `https://fleetapi-sz.cartrack.com/rest`, and removed the Zanzibar server entry.
- **[General]:** Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Tachograph]:** Fixed an issue where `GET /tachographs/driving-times` returned an empty result for a subuser with a valid driver permission grant.
- **[Vehicles]:** Fixed an issue where `GET /vehicles/status` omitted vehicles that had no position description. Those vehicles are now returned, with `position_description` as an empty string.
- **[Trips]:** Fixed an issue where `GET /trips` and `GET /trips/{registration}` omitted trips that had no recorded start or end position.

## Version 1.26.0911.1 (2026-09-11)

### Improvements

- **[General]:** Various internal improvements and under-the-hood tweaks.

## Version 1.26.0908.1 (2026-09-08)

### New Features

- **[Carpool]:** Added read-only Carpool endpoints: `GET /carpool/bookings`, `GET /carpool/bookings/{booking_id}`, `GET /carpool/vehicles`, `GET /carpool/vehicles/categories`, `GET /carpool/drivers`.
- **[Vehicles]:** `GET /vehicles/{registration}/power-takeoff` now supports `filter[status]` and `sort_order`, with reliable ordering for latest-record retrieval.
- **[Vehicles]:** Added typed custom field definitions and values: `GET`/`POST /settings/vehicles/custom-fields` and `PUT`/`DELETE /settings/vehicles/custom-fields/{customFieldId}` to manage field definitions, and `GET`/`PUT /vehicles/{registration}/custom-fields` to read and write values. Supports text, long description, number, date, time, date-time, single-select, and multi-select field types.
- **[Vision]:** Added `GET /vision/status` to check a camera's online, standby, or offline status for camera-equipped vehicles on your account.
- **[Delivery]:** Added `planned_duration_time_minutes` to `GET /delivery/reports/drivers`, the dwell time planned for a driver's stops, to compare against the actual `duration_time_minutes`.

### Improvements

- **[Vehicles]:** `GET /vehicles/{registration}/power-takeoff` request params renamed to `start_timestamp`/`end_timestamp` (legacy `start_date`/`end_date` still accepted).
- **[Vehicles]:** Deprecated the legacy positional `custom_fields` (`custom_1`..`custom_7`) on `GET /vehicles` and `PUT /vehicles/{registration}`. `PUT /vehicles/{registration}` no longer writes it (still accepted for backward compatibility, but ignored); use `custom_field_values` instead.
- **[Delivery]:** Documented `length`, `width`, `height` item attributes (centimeters) on Create/Update Delivery Job.
- **[Delivery]:** Deprecated `weight_measure_id` and documented the `weight` unit (kilograms) on Delivery Job items.
- **[Delivery]:** Deprecated unmaintained driver fields `login_type`, `remember_token`, and `is_online`.
- **[Delivery]:** Deprecated `driver.token`; added the missing `driver` object to the `POST /delivery/jobs` response documentation.
- **[Delivery]:** Documented that `stops[].todos[].is_required` is always `true` and cannot be set by the client.
- **[Delivery]:** Documented job status `7` (Cancelled) on job list and filter responses.
- **[General]:** Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Vehicles]:** Fixed an issue where some endpoints could return another account's vehicle data due to missing account scoping.
- **[Legacy API]:** Fixed an issue where a legacy vehicle-lookup endpoint could return an HTTP 500 error for certain requests.
- **[Legacy API]:** Fixed an issue where certain legacy endpoints could return a malformed response instead of a standard error, or the wrong error code, for requests with invalid arguments.
- **[POIs]:** Fixed an issue where `GET /pois/{poi_id}` returned an HTTP 500 error for certain requests.
- **[Delivery]:** Fixed an issue where `PUT /delivery/jobs/{jobId}` returned an HTTP 500 error when a job item update only changed its `todos`.
- **[Delivery]:** Fixed an issue where `PUT /delivery/drivers/{driver_id}` allowed changing or removing an already-linked fleet driver, which could let an active driver stop counting toward seat usage.
- **[Drivers]:** Fixed an issue where fleet seat counts could include drivers not linked to fleet.
- **[Delivery]:** Fixed an issue where `GET /delivery/reports/drivers` could report an incorrect planned distance and travel time, and a `duration_time_minutes` of `0` for a full day of stops.

## Version 1.26.0824.1 (2026-08-24)

### New Features

- **[Geofences]:** `GET /geofences`, `GET /geofences/{geofence_id}` and `GET /geofences/visits` now expose `is_toll`. `GET /geofences` and `GET /geofences/visits` also accept `filter[is_toll]` to restrict results to toll (or non-toll) geofences.

### Bug Fixes

- **[Delivery]:** Fixed an issue where `GET /delivery/jobs` returned an HTTP 500 error.
- **[Trips]:** Fixed an issue where `GET /rest/trips` returned incorrect pagination metadata on page 2 and later.

## Version 1.26.0818.1 (2026-08-18)

### New Features

- **[Delivery]:** `POST /delivery/drivers` and `PUT /delivery/drivers/{driver_id}` now accept `fleet_driver_id`, allowing a delivery driver to be linked to an existing fleet driver instead of always creating a new one.

## Version 1.26.0805.1 (2026-08-05)

### New Features

- **[Vehicles]:** `GET /vehicles/events` now accepts `filter[terminal_event_type_id]`, `filter[event_id]`, `filter[vehicle_id]`, `filter[registration]` and `filter[chassis_number]`, so a result set can be narrowed to a single event type, a single event or a single vehicle. See `GET /vehicles/events/types` for the list of available event type IDs.
- **[Vehicles]:** `GET /vehicles/{registration}/events` now accepts `filter[terminal_event_type_id]` and `filter[event_id]`.

### Improvements

- **[AEMP]:** `CumulativeOperatingHours.Hour` now reports the vehicle's own hour-meter reading when the vehicle sends one, and falls back to the Cartrack-accumulated operating hours since fitment when it does not. `CumulativeOperatingHours.DateTime` reflects the reading that is returned. Because an hour-meter reading covers the whole life of the vehicle, including time before it was fitted, the value can be noticeably higher than before for the same vehicle.
- **[AEMP]:** `CumulativeIdleHours` is always Cartrack-accumulated since fitment. When `CumulativeOperatingHours` comes from the vehicle's hour meter, subtracting idle hours from operating hours no longer approximates productive hours.
- **[Delivery]:** `allowed_to_start_at` and `send_to_driver_at` now reject an empty string with a validation error on `POST /delivery/jobs`, `PUT /delivery/jobs/{job_id}` and `POST /delivery/jobs/bulk-upload`. Omit the field or send `null` to leave it unset.
- **[Delivery]:** A stop that cannot be resolved to a location is now rejected with a validation error on `POST /delivery/jobs`, `PUT /delivery/jobs/{job_id}` and `POST /delivery/jobs/bulk-upload`, instead of being resolved to an approximate one. Send valid coordinates, or an address complete enough to be geocoded.

### Bug Fixes

- **[Tachographs]:** Fixed an issue where `GET /tachographs` returned an empty list for some accounts.
- **[Tachographs]:** Fixed an issue where `GET /tachographs/download` could return a truncated or malformed attachment filename.
- **[Delivery]:** Fixed an issue where `POST /delivery/jobs` and `PUT /delivery/jobs/{job_id}` returned an HTTP 500 error.
- **[AEMP]:** Fixed an issue where `GET /aemp/iso15143-3/beta/equipment/{id}` returned an HTTP 500 error.

## Version 1.26.0729.1 (2026-07-29)

### Improvements

- **[Leads]:** The lead policy created by `POST /leads` is now linked to the lead that owns the vehicles' `lead_product_id` values. Requests mixing lead products from different leads are rejected with a validation error.

### Bug Fixes

- **[Leads]:** Fixed an issue where `POST /leads` returned an HTTP 500 error.

## Version 1.26.0728.1 (2026-07-28)

### Bug Fixes

- **[Vision]:** Fixed an issue where `POST /vision/videos/requests` could return an incorrect property name for the video end timestamp.

## Version 1.26.0724.1 (2026-07-24)

### New Features

- **[Vision]:** `POST /vision/livestream/{registration}` now returns an `expires_at` timestamp for each camera, so you know when to request a fresh livestream URL.
- **[Events]:** `GET /events` now reports additional event types, including camera detections (`BLIND_SPOT_LEFT`, `BLIND_SPOT_RIGHT`, `SUNGLASSES_DETECTED`, `NO_DRIVER_DETECTED`) and telematics events (`CRASH`, `POWER_EVENT`, `DISARM`, `GPS_JAMMING_START`/`_END`, `GSM_JAMMING_START`/`_END`, `HORN_ON`/`_OFF`, `EXCESS_IDLE`, `DRIVER_ID_TAG`). See the Vehicle Events Services page for the full list.

### Improvements

- **[Vision]:** Download URLs returned by `GET /vision/videos/requests` are now durable links you can fetch and store. Treat all Vision video URLs as opaque and do not depend on their host or path.
- Various internal improvements and under-the-hood tweaks.

## Version 1.26.0722.1 (2026-07-22)

### Improvements

- Various internal improvements and under-the-hood tweaks.

## Version 1.26.0716.1 (2026-07-16)

### New Features

- **[Drivers]:** `GET /drivers` and `GET /drivers/{driver_id}` now return the driver's tachograph `card_id`.

### Improvements

- **[Delivery]:** `POST /delivery/customers` now populates the customer address from the supplied coordinates when the address fields are omitted.
- **[Delivery]:** Deprecated legacy device fields in the `GET /delivery/jobs/{job_id}` response.
- **[Vision]:** `GET /vision/livestream/{registration}` is now rate limited to 10 requests per minute per vehicle.
- **[Vehicles]:** Documented the `409 Conflict` response returned by the vehicle command endpoints.
- Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Vehicles]:** Fixed an issue where `GET /vehicles` could return duplicate vehicles and an inflated vehicle count.
- **[Vehicles]:** Fixed an issue where `GET /vehicles/{registration}/events/idling` returned an HTTP 500 error.
- **[Vision]:** Fixed an issue where `GET /vision/livestream/{registration}` returned an HTTP 500 error.
- **[Trips]:** Fixed an issue where `GET /trips` returned an HTTP 500 error.

## Version 1.26.0622.1 (2026-06-22)

### Improvements

- Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Vehicles]:** Fixed an issue where `GET /vehicles/immobilise/status` returned an incorrect `immobilise_status` value.

## Version 1.26.0618.1 (2026-06-18)

### Improvements

- Various internal improvements and under-the-hood tweaks.

## Version 1.26.0616.1 (2026-06-16)

### Improvements

- **[Drivers]:** Empty string `last_name` is now accepted on `POST /drivers` and `PUT /drivers/{driver_id}` and treated as if the field had been omitted.
- Various internal improvements and under-the-hood tweaks.

## Version 1.26.0612.1 (2026-06-12)

### Improvements

- **[Delivery]:** Delivery job stop output now includes a `driver_ack_at` field with the timestamp at which the driver acknowledged the stop.
- **[Drivers]:** `last_name` is now optional in `POST /drivers`.
- **[Vision]:** The `POST /vision/livestream/{registration}` response now includes an `is_hls` field indicating whether the livestream URL is in HLS format.
- Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Delivery]:** Fixed an issue where `POST /delivery/jobs` and `PUT /delivery/jobs/{jobId}` returned an HTTP 500 error.
- **[Drivers]:** Fixed an issue where `POST /drivers` and `PUT /drivers/{driver_id}` returned an HTTP 500 error.
- **[Geofences]:** Fixed an issue where `GET /geofences` returned an HTTP 500 error.
- **[POIs]:** Fixed an issue where `GET /pois` returned an HTTP 500 error.
- **[Vehicles]:** Fixed an issue where `GET /vehicles/soc` and `GET /vehicles/{registration}/soc` returned an incorrect state of charge value for some vehicles.
- **[Vision]:** Fixed an issue where `POST /vision/livestream/{registration}` returned an HTTP 503 error while the camera was online.

## Version 1.26.0508.2 (2026-05-08)

### Improvements

- **[Sensors]:** Improved `POST /alerts/sensors` documentation and validation: `contact_type` is now listed as required, `registrations` is capped at 50 items, and descriptions for `sensor_type`, `geofence_id`, and `geofence_group_id` have been enhanced.
- Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Delivery]:** Fixed an issue where `POST /delivery/jobs`, `PUT /delivery/jobs/{jobId}`, and `PUT /delivery/jobs/assign/{driverId}` accepted deactivated drivers instead of returning an HTTP 422 error.
- **[Vehicles]:** Fixed an issue where `GET /vehicles/{registration}/events` returned an HTTP 500 error when `start_timestamp` and `end_timestamp` were equal.

## Version 1.26.0507.1 (2026-05-07)

### New Features

- **[Countries]:** Added support for Saudi Arabia (KSA).

### Improvements

- Various internal improvements and under-the-hood tweaks.

### Bug Fixes

- **[Delivery]:** Fixed an issue where `PUT /delivery/jobs/assign/{driverId}` returned an HTTP 500 error.
- **[Delivery]:** Fixed an issue where `DELETE /delivery/jobs/{jobId}` and `PUT /delivery/jobs/{jobId}` returned an HTTP 500 error.

## Version 1.26.0428.1 (2026-04-28)

### New Features

- **[Alerts]:** Introduced new endpoint `POST /alerts/sensors` to create sensor-based alerts for vehicle sensor events, supporting PTO (Power Take-Off) and PANIC sensor types with configurable trigger conditions.

### Improvements

- **[Generators]:** Extended `GET /generators/activity` response to include `registration` and `chassis_number` fields for easier vehicle identification.
- **[Delivery]:** Customer information updates now automatically propagate to all related delivery jobs, ensuring data consistency across the delivery workflow.
- **[Geofence Visits]:** Added sorting support to `GET /geofences/visits` for an improved user experience when browsing visit records.

### Bug Fixes

- **[Geofences]:** Fixed an issue where `PUT /geofences/{id}` returned an HTTP 500 error.
- **[Geofences]:** Fixed an issue where `POST /geofences` returned an HTTP 500 error.
- **[Trips]:** Fixed an issue where `PUT /trips/{registration}` returned an HTTP 500 error.
- **[Vehicle Events]:** Fixed an issue where `GET /vehicles/events` could return blank responses under certain conditions.
- **[Drivers]:** Fixed an issue where creating drivers for subusers could fail silently due to conflicting permission records.
- **[Delivery]:** Fixed an issue where push notifications were not delivered to drivers upon job creation.
- **[Leads]:** Fixed an issue where `POST /leads` returned an HTTP 500 error.
- **[Helpdesk]:** Fixed an issue where `POST /helpdesk/note` returned an HTTP 500 error.
- **[Topics]:** Fixed an issue where `GET /topics/vehicles/temperature` returned an HTTP 500 error.
- **[Vehicles]:** Fixed an issue where `PUT /vehicles/risk` returned an HTTP 500 error.