public-api-docs

Operations API Vehicle Guide

Overview

The Operations API vehicle endpoints are for building operator-side fleet tooling: fleet inventory, service-state management, vehicle troubleshooting, maintenance workflows, IoT module assignment, telemetry review, and controlled vehicle actions.

Use these endpoints when an operator, service agent, or internal automation needs to inspect or change fleet state across branches. For end-user app flows such as customer-facing vehicle discovery, availability maps, or rental start flows, use the User API.

For general Operations API positioning, traffic patterns, and data-ingestion guidance, start with the Operations API Guide.

Related reference: Operations API Operations API Guide Error Codes Pagination

Core Concepts

Vehicle

A vehicle represents one fleet asset in a branch. It contains operational identity such as code, license plate, position, category, branch assignment, rental state, service state, IoT module information, tags, and custom properties.

Custom operator tools usually use vehicles as the central object for fleet management screens, maintenance workflows, and support investigations.

Rental State vs Service State

Vehicle availability is not described by one field only. The two most important state groups are rental state and service state.

State group What it describes Examples
rentalState Whether the vehicle is currently involved in a rental lifecycle. AVAILABLE, RESERVATION, DRIVING, PARKING, DELIVERED
serviceStateV2 Whether the vehicle is operationally usable, under inspection, in service, out of order, or retired. FUNCTIONAL, INSPECT, RELOCATE, service states, out-of-order states, RETIRED, DEFLEETED

Do not decide vehicle availability from rentalState alone. A vehicle can be free from a rental perspective but still unavailable because of service state, battery level, connectivity, branch configuration, or a category rule.

Vehicle Availability

Vehicle availability is derived from several signals:

Operator tools should show the important state fields separately instead of hiding them behind one generic “available” label. This makes it easier for fleet teams to understand why a vehicle can or cannot be rented.

When A Vehicle Is Ready To Rent

A vehicle is ready to be rented only when all relevant availability gates pass. For an on-demand map or fleet availability view, the important checks are:

Check Ready-to-rent condition If it fails
Rental state rentalState is AVAILABLE. The vehicle is already reserved, driving, parking, or delivered for another booking/rental.
Service state serviceStateV2 is operational, such as FUNCTIONAL, INSPECT, or RELOCATE. The vehicle is out of order, in service, retired, defleeted, lost, impounded, waiting for parts, or otherwise not rentable.
Battery state batteryLevel is operational, normally HIGH or MEDIUM. The vehicle is blocked with BATTERY_TOO_LOW when the battery level is LOW, CRITICAL, or UNKNOWN.
IoT connectivity The vehicle is not marked offline. The vehicle is blocked with OFFLINE; commands and current state may not be reliable.
Charging restriction The vehicle is not required to remain on a charger. The vehicle is blocked with MUST_REMAIN_ON_CHARGER until it reaches the configured charging limit.
Category and branch rules The vehicle category is bookable and the branch/category configuration allows the workflow. The vehicle may be visible to operators but not available to users.

The API surfaces these blockers through available and unavailabilityReasons on vehicle responses where available. Treat available: false as the source for operator explanations, and use unavailabilityReasons to show why the vehicle cannot be rented.

The main unavailability reasons are:

Reason Meaning
OUT_OF_ORDER The service state is not operational.
BATTERY_TOO_LOW The vehicle battery level is too low or unknown for rental availability.
OFFLINE The IoT module or vehicle connectivity is offline.
MUST_REMAIN_ON_CHARGER The vehicle is charging and should remain on the charger until the configured limit is reached.

Battery And IoT State

Battery state and IoT state are separate signals, and both matter for map availability.

batteryLevel describes the vehicle’s main battery status. The common levels are:

Battery level Meaning for availability
HIGH Operational for rental.
MEDIUM Operational for rental.
LOW Usually not available on the user map; operator tools should route to charge or swap workflow.
CRITICAL Not available for rental; urgent charge/service workflow.
UNKNOWN Not enough reliable battery information; treat as not available for rental.

stateOfCharge is the numeric battery percentage where available. Category configuration can define thresholds such as medium, low, critical, and charging limit. Some categories can also use IoT-reported state of charge or IoT battery voltage instead of platform-derived values.

IoT state describes whether the vehicle can communicate with the platform and execute commands. Important fields include:

Signal Meaning for operator tools
module.state Shows whether an IoT module is assigned and ready, such as ASSIGNED, NOT_READY, UNASSIGNED, NEW, or RETIRED.
Vehicle offline flag Drives the OFFLINE availability blocker. Offline vehicles should not be treated as ready for rental.
iotStateOfCharge IoT-reported battery state of charge, when the category is configured to use it.
iotModuleLevel IoT module battery/voltage signal, useful for diagnosing module power issues.
powerState Whether the vehicle reports ON, OFF, or UNKNOWN; important for troubleshooting and some rental-end requirements.

For map and list UIs, show both the high-level availability result and the diagnostic state. For example, a vehicle can be FUNCTIONAL and AVAILABLE from a rental-state perspective, but still not ready to rent because it is offline, has low battery, or must remain on a charger.

Vehicle Categories

Vehicle categories define how vehicles of a type behave in the platform. They can contain:

Use category endpoints when building tools that need to show vehicle types, available actions, or category-specific operational fields. For detailed category configuration guidance, see the Operations API Vehicle Category Guide.

IoT Modules

Vehicles can be associated with IoT modules. The module is the connection point for commands, telemetry, vehicle state updates, and physical-asset communication.

Module assignment is an operational workflow. A custom tool should make the target vehicle and target module clear before association or removal, because changing the module can affect command execution, telemetry, and future rental operations.

Vehicle Actions And Commands

Vehicle operations are modeled at different levels:

Type Purpose
Command Sends a command to the vehicle or IoT integration, such as locate, start, stop, or open.
Activity Updates platform-side vehicle or workflow state.
Composite activity Runs a configured sequence of activities and commands.
Action Operator-facing abstraction that can combine configured behavior and permissions.

Where possible, build operator tooling around configured actions and activities. They reflect the operator’s category configuration and permission model better than hard-coding individual vehicle commands.

Common Operator Workflows

List Vehicles For A Branch

Use GET /vehicles.

Common inputs:

This endpoint is intended for operator search, fleet lists, support tooling, and operational review screens. For recurring fleet-data replication into another database, use Data Exports or the data warehouse instead.

Show Vehicles On An Operations Map

Use GET /vehicles/map.

This endpoint is optimized for operator map views and excludes vehicles that should not normally appear in active fleet operations, such as retired or virtual vehicles.

Use the map endpoint for fleet management and service operations. Customer-facing availability maps should use the User API.

For dashboard counters and fleet-health summaries, use GET /kpis instead of deriving totals from the map endpoint. KPI types such as AVAILABLE_VEHICLES, LOW_BATTERY_VEHICLES, OFFLINE_VEHICLES, VEHICLES_IN_SERVICE, and VEHICLES_WITH_OPEN_TASK are designed for operator overview screens.

Inspect One Vehicle

Use GET /vehicles/{id} when a tool needs the current vehicle object.

Use GET /vehicles/code/{code} when the operator workflow starts from a vehicle code scanned or entered by a service agent.

Use GET /vehicles/{id}/details for a richer operational detail view where the standard vehicle response is not enough.

Create Or Bulk Create Vehicles

Use POST /vehicles to create one vehicle.

Use POST /vehicles/bulk-create when onboarding multiple vehicles in one operator workflow.

Vehicle creation usually depends on branch, category, identity fields, and sometimes module setup. Tools should validate required business fields before submitting the request, because created vehicles can immediately become part of operational workflows.

Update Vehicle Metadata Or Operational State

Use PATCH /vehicles/{id} to update a vehicle by ID.

Use PATCH /vehicles?code={vehicleCode} to update a vehicle by code.

Use these endpoints for controlled updates such as changing service state, branch, category, position, license plate, legal inspection date, custom properties, or other documented vehicle fields.

Use DELETE /vehicles/{id}/legalInspectionDate when the legal inspection date should be removed.

Bulk Update Vehicles

Use the bulk endpoints for branch-scoped fleet operations:

Task Endpoint
Bulk update vehicles by query POST /vehicles/bulk-update
Bulk update explicit vehicles POST /vehicles/bulk-update-by-ids
Bulk update tags PATCH /vehicles/tags/bulk-update
Bulk create tasks POST /vehicles/tasks/bulk-create
Bulk create notes POST /vehicles/notes/bulk-create

Bulk updates are useful for operational actions such as changing service state, moving vehicles to a category, updating tags, or creating tasks for a selected fleet segment.

Refresh Vehicle State

Use these endpoints when an operator tool needs the platform to refresh stored vehicle state from the configured vehicle or IoT integration:

Scope Endpoint
One vehicle POST /vehicles/{id}/updateState
Branch fleet POST /vehicles/updateState/branch/{id}

After a refresh, re-fetch the vehicle before showing the next action.

Manage IoT Module Association

Use POST /vehicles/{id}/iot-module to associate a module with a vehicle.

Use DELETE /vehicles/{id}/iot-module to remove the current module association.

The association request accepts either a module ID or an external module ID. Provide exactly one identifier.

Review Telemetry, Activity, Logs, Tasks, And Damages

Use these endpoints for vehicle troubleshooting and support views:

Task Endpoint
Vehicle activity log GET /vehicles/{id}/activity
Vehicle telemetry GET /vehicles/{id}/telemetry
Vehicle log entries GET /vehicles/{id}/log-entries
Vehicle tasks GET /vehicles/{id}/tasks
Vehicle damages GET /vehicles/{id}/damages
Vehicle tasks and annotations for multiple vehicles POST /vehicles/details

These endpoints are useful for explaining state changes, diagnosing IoT issues, and building maintenance or support consoles.

Execute Vehicle Actions

Use configured vehicle actions when an operator should trigger behavior on a vehicle:

Task Endpoint
List available actions GET /vehicles-management/actions
Execute an action POST /vehicles/execute-action/{actionId}
Execute an activity POST /vehicles/execute-activity/{activityId}
Execute a composite activity POST /vehicles/execute-composite-activity/{compositeActivityId}
Execute a command POST /vehicles/execute-command

Execution endpoints accept either vehicleId or vehicleCode, depending on the endpoint. Provide exactly one vehicle identifier.

Vehicle actions and commands can affect a physical vehicle. Operator tools should show the selected vehicle, action, and expected effect before execution, and re-fetch vehicle state after completion.

Use Legacy Vehicle Command Shortcuts

The Operations API still exposes shortcut command endpoints such as POST /vehicles/{id}/locate, POST /vehicles/{id}/start, POST /vehicles/{id}/stop, POST /vehicles/{id}/openTailbox, and related command-specific paths.

For new tooling, prefer configured actions or POST /vehicles/execute-command where possible. The configured action model is easier to align with vehicle categories, permissions, and operator-specific workflows.

For discovering which actions or commands are available for a vehicle category, see the Operations API Vehicle Category Guide.

Retire A Vehicle

Use DELETE /vehicles/{id} to retire a vehicle.

Retiring a vehicle removes it from normal active fleet workflows. Custom tools should present this as a high-impact action and refresh fleet lists after completion.

Permissions And Settings

Vehicle tooling depends on the active user’s permissions, branch access, vehicle category configuration, and enabled operational features. A user may be able to view vehicles in a branch but not update service state, execute commands, assign IoT modules, or retire vehicles.

Common permission areas:

Workflow Permission consideration
List or inspect vehicles Vehicle read permissions on the relevant branch.
Create, update, bulk update, or retire vehicles Vehicle create/update/delete permissions on the branch.
Execute vehicle actions or commands Permission for the configured action/command and access to the vehicle branch.
Manage IoT module association Vehicle/module management permissions.
Manage categories, actions, activities, or custom commands Administrative vehicle configuration permissions.
Review tasks, damages, telemetry, or logs Domain-specific read permissions may apply in addition to vehicle access.

Use GET /roles/assignments/exists to check whether the current user has a relevant permission before showing high-impact actions, and still handle permission errors from the vehicle endpoint itself.

Settings and configuration that commonly affect vehicle workflows:

Area Why it matters
Vehicle category configuration Controls bookability, supported actions, commands, attributes, and vehicle-specific behavior.
Branch configuration Controls fleet visibility, operating constraints, stations, and local business rules.
Service-state and availability rules Determine whether a vehicle can be shown as operational or rentable.
Battery and charging thresholds Determine battery labels, low-battery blockers, and whether a vehicle must remain on a charger.
IoT/module configuration Determines which commands, telemetry, state updates, and IoT battery signals are available.
Maintenance and task configuration Affects service workflows, task creation, and operator work queues.

Use GET /settings when the tool already knows which DASHBOARD or SHARED setting keys it needs for a vehicle workflow. Use /settings-management to discover vehicle-related settings across areas and for administrative configuration workflows. Use category or management endpoints for vehicle-specific configuration. Do not assume the same commands, actions, or vehicle properties are enabled for every branch or vehicle category.

Most Relevant APIs

Task Endpoint
List vehicles GET /vehicles
Create vehicle POST /vehicles
Bulk create vehicles POST /vehicles/bulk-create
Get vehicle by ID GET /vehicles/{id}
Get vehicle by code GET /vehicles/code/{code}
Update vehicle by ID PATCH /vehicles/{id}
Update vehicle by code PATCH /vehicles?code={vehicleCode}
Retire vehicle DELETE /vehicles/{id}
Operations map list GET /vehicles/map
Bulk update by query POST /vehicles/bulk-update
Bulk update by IDs POST /vehicles/bulk-update-by-ids
Refresh one vehicle state POST /vehicles/{id}/updateState
Refresh branch vehicle states POST /vehicles/updateState/branch/{id}
Associate IoT module POST /vehicles/{id}/iot-module
Remove IoT module DELETE /vehicles/{id}/iot-module
Generate service Bluetooth token POST /vehicles/{id}/bluetooth/generate-token
Get telemetry GET /vehicles/{id}/telemetry
Get activity log GET /vehicles/{id}/activity
Get log entries GET /vehicles/{id}/log-entries
Get tasks GET /vehicles/{id}/tasks
Get damages GET /vehicles/{id}/damages
Execute vehicle action POST /vehicles/execute-action/{actionId}
Execute vehicle command POST /vehicles/execute-command
List vehicle categories GET /vehicles/categories
Manage vehicle categories GET/POST/PATCH/DELETE /vehicles/categories-management
List vehicle category actions GET /vehicles/categories/actions
List vehicle category commands GET /vehicles/categories/commands
Get fleet KPI counters GET /kpis
Check current user’s permission GET /roles/assignments/exists
Read relevant dashboard/shared settings by key GET /settings

Error Handling

Vehicle APIs can fail for technical or business reasons. Common categories:

Category Typical cause What the client should do
Permission errors Operator lacks access to the branch, vehicle, action, or category. Show a permission message and avoid retrying automatically.
Not found Vehicle, category, module, action, task, or branch is missing or outside accessible scope. Refresh local state and verify branch context.
Invalid state Requested change conflicts with current rental, service, module, or category state. Re-fetch the vehicle and show the current state before retrying.
Validation errors Required vehicle fields, module identifiers, or bulk-update filters are invalid. Keep the operator on the form and show field-level guidance.
Vehicle communication IoT command failed, timed out, or returned an unexpected status. Re-fetch telemetry and vehicle state before offering retry or support workflow.
Concurrent operation Another command or rental operation is affecting the vehicle. Wait briefly, refresh state, and only retry if the action still makes sense.

For specific codes, see Error Codes. Vehicle-related codes often start with V; module and command errors may also surface through vehicle communication errors.

Implementation Notes For Custom Tools

Review Notes

The following product decisions are reflected in this first draft: