public-api-docs

Operations API Rental Guide

Overview

The Operations API rental endpoints are for operator-side rental tooling: support consoles, fleet operations workflows, finance review, rental troubleshooting, and internal automations. Use them when an operator or service agent needs to inspect, create, cancel, end, or correct rentals across users and branches.

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

Booking vs Rental

A booking is a future reservation for a time window and usually a vehicle category. A rental is the live trip container. A rental can be created from a booking, or it can be created directly for an on-demand/free-floating trip.

Rental State

The Rental.state describes the rental container:

State	Meaning
`RESERVATION`	The vehicle is held for the user, but the trip has not started.
`ACTIVE`	The rental is in progress. The vehicle may be driving or parking.
`EXPIRED`	A reservation expired before it was started.
`CANCELLED`	A reservation was cancelled.
`ENDED`	The rental completed normally.
`ENDED_NO_MOVEMENT`	The rental started but ended without meaningful vehicle movement.

Rental Operations

Rental operations are state transitions performed on a rental. The important operation types are:

Operation	Typical source state	Effect
`START`	`RESERVATION`	Starts the rental and activates the vehicle.
`END`	`ACTIVE`	Ends the rental, runs end checks, updates vehicle state, and triggers billing.
`PARK`	`ACTIVE`	Switches an active rental into parking mode.
`DRIVE`	`ACTIVE`	Switches a parked active rental back into driving mode.
`RENEW_RESERVATION`	`RESERVATION`	Extends reservation time.
`OPEN_TAILBOX`	active or recently ended rental	Opens the vehicle tailbox if configured.

Administrative rental operations may allow overrides that are not available to end users. Treat these as operational interventions, not normal product flow.

Start Rental Requirements

Start rental requirements define what a user must satisfy before a rental can start. They are configured for a branch and vehicle category, so the effective requirements depend on both where the rental happens and which type of vehicle is being rented.

Typical requirements include user verification, accepted terms and conditions, payment method checks, rental authority, age or license checks, and payment pre-authorization. Credit-card or payment-method pre-authorization is part of this requirement model and is configured at the vehicle-category level.

This matters for operator tooling because a rental that looks valid from the vehicle and booking state can still fail to start if the user’s branch/category requirements are not fulfilled.

Common Operator Workflows

Find Rentals For A Branch

Use GET /rentals in the Operations API.

Required:

branchId

Useful filters:

includeChildBranches=true to include child branches.
searchText to search by first name, last name, license plate, or rental ID.
intersectTime to find rentals whose start/end window contains a timestamp.
includeOnDemandOnly=true to return rentals without a booking.
activeDeposit=true to find rentals with an active deposit.
rating and ratingDescription for support and feedback workflows.

The response is paginated. Read Pagination before building search or review workflows.

This endpoint is intended for operator-facing rental search and inspection. If your goal is to regularly copy rental history into your own database for reporting, analytics, BI, or internal business processes, use Data Exports or the data warehouse instead of polling the Operations API.

Inspect One Rental

Use GET /rentals/{rentalId} when a support or operations tool needs the current rental details, including related user, vehicle, branch, price, invoice, deposit, or state information available to the operator.

Use GET /rentals/{rentalId}/billing-overview when the tool needs the billing breakdown for support or finance workflows.

Use GET /rentals/{id}/routes when the tool needs rental route waypoints for trip reconstruction, support, or investigations.

Create A Rental As An Operator

Use POST /rentals.

This is an administrative flow for creating a rental for a user and vehicle. The request uses AdminAddRental, which extends the normal rental creation request with operator-specific user context.

Important behavior:

If startRentalState is omitted, Core defaults it to ACTIVE.
RESERVATION creates a reserved rental.
ACTIVE starts the rental immediately and can trigger start rental requirement checks, payment pre-authorization, vehicle commands, deposits, rental phases, and events.
The operator must have rental-create permission on the vehicle’s branch.

Use this endpoint carefully in custom tooling. Creating an active rental is not just a database insert; it can affect vehicle state and billing.

Cancel A Reservation

Use DELETE /rentals/{rentalId}.

This endpoint is for cancelling a rental that is still in RESERVATION. It finalizes the reservation, updates pricing where applicable, publishes rental events, and may release the vehicle for other bookings or rentals.

Do not use this endpoint to end an active trip. Use the rental operation endpoint with operationType: "END".

Paid Reservation Extensions

Paid reservation extensions are the operator-side configuration counterpart to the User API flow POST /rentals/{rentalId}/buy-reservation?minutes={minutes}. The User API sells minutes to the end user while the rental is still in RESERVATION; Operations-side tooling controls whether this makes sense commercially by configuring the free reservation window and the paid reservation price.

Reservation behavior is controlled by the Core setting rental.reservation with value type RENTAL_RESERVATION_SETTINGS. Important fields include:

Field	Purpose
`reservationMinutes`	Default free reservation duration when the user reserves without buying paid minutes.
`reservationMaxMinutes`	Maximum free reservation allowance in the reset window.
`bufferMinutes`	Window after which the user’s consumed free reservation allowance resets.
`blockRentalForSameVehicleMinutes`	Optional block before the same user can create a new rental/reservation on the same vehicle after ending.

Use GET /settings-management?key=rental.reservation&exactMatch=true to inspect the configured setting and POST /settings-management, PUT /settings-management/{id}, or PUT /settings-management/bulk for administrative setup where the tenant permits setting writes. Prefer branch-specific configuration when reservation behavior differs by branch.

Paid reservation minutes are priced through the on-demand/free-floating pricing configuration. Configure the reservation price in the relevant on-demand pricing bundle, publish the version, and assign it to the branch and vehicle category through on-demand pricing assignments. See Paid Reservation Pricing.

In customer-facing apps, fixed “reservation packages” such as 5, 10, or 15 minutes are usually UI choices that call the User API with the selected minutes value. They are not package/voucherable products unless the tenant intentionally wants a separate purchasable package model. Keep the package labels, prices, and allowed minute choices aligned with the active reservation pricing and branch policy.

Perform A Rental Operation

Use POST /rentals/{rentalId}/operation.

This endpoint is the administrative control point for START, END, PARK, DRIVE, RENEW_RESERVATION, and OPEN_TAILBOX.

Operational effects can include:

Vehicle commands through the configured IoT integration.
Rental phase changes used for pricing.
End-rental requirement checks.
Invoice and payment processing when the rental ends.
Deposit handling.
Platform events and audit records.

If another operation is already running for the same rental, the API can reject the request with a concurrent-processing error. Retry only after checking the rental’s current state.

End-Rental Requirements

End-rental requirements define what must be true before a rental can be completed. They are configured by branch and vehicle category, so different vehicle types or operating areas can enforce different end conditions.

Geofenced end-rental behavior can come from branch compatibility geometry and from Areas policies. New operator tools should use the Areas Guide for geofence management and treat branch businessArea or map overlay fields as read/display compatibility fields.

When a rental is ended, Core evaluates the configured requirements for that rental. A failed requirement means the rental should not be ended until the operator, service agent, or user resolves the condition, unless an administrative override is intentionally used.

For operator tooling, these requirements are useful because they explain why an END operation failed and what action is needed next. Some requirements are simple user or service-agent actions, such as closing doors or moving the vehicle into a business area. Others indicate a support or maintenance situation, such as missing equipment, unreliable location, or an unexpected vehicle/IoT state.

Requirement	What it checks	Typical operator action
`IN_BUSINESS_AREA`	Vehicle is inside an allowed end-rental business area.	Ask the user or service agent to move the vehicle into the allowed area.
`USER_IN_BUSINESS_AREA`	User/device location is inside an allowed end-rental business area.	Verify user location or handle as support case if location cannot be determined.
`NOT_IN_PROHIBITED_AREA`	Vehicle is not inside a no-end-rental area.	Move the vehicle out of the prohibited area.
`USER_NOT_IN_PROHIBITED_AREA`	User/device location is not inside a prohibited area.	Verify user location or handle as support case if location cannot be determined.
`VEHICLE_IN_STATION_AREA`	Vehicle is located in the configured station area.	Return the vehicle to the correct station area.
`VEHICLE_LOCKED_IN_STATION`	Vehicle is physically locked/docked in a station.	Dock or lock the vehicle correctly.
`IS_CHARGING`	Vehicle is plugged in or charging.	Connect the vehicle to the charger.
`TAILBOX_CLOSED`	Tailbox is closed.	Close the tailbox.
`HELMETS_PLUGGED_IN`	Helmets are present/plugged in.	Return and plug in helmets.
`EXISTING_HELMETS_PLUGGED_IN`	Helmets present at rental start are still present at rental end.	Investigate missing helmets before ending.
`EXISTING_RFID_CARD_HOLDER_CARDS_RETURNED`	RFID cards present at rental start are still present at rental end.	Investigate missing vehicle cards before ending.
`BIKE_LOCK_LOCKED`	Bike lock is locked.	Lock the bike lock.
`POWER_STATE_OFF`	Vehicle power state is off before ending or parking.	Turn off the vehicle.
`STATUS_TURNED_OFF`	Vehicle is off after the stop command is executed.	Treat as vehicle-state/IoT issue if the vehicle remains on.
`DOORS_CLOSED`	All vehicle doors are closed.	Close all doors.
`KEY_IN_HOLDER`	Vehicle key is back in the key holder.	Return the key to the holder.
`PARK_BRAKE_ON`	Parking brake is on.	Engage the parking brake.

Some requirements are self-service actions suitable to surface directly in operator tools, such as closing doors, returning a key, plugging in helmets, or moving a vehicle into the allowed area. Requirements involving missing equipment, unreliable location, vehicle communication, or unexpected vehicle state should usually be routed to a support or service workflow.

Release A Deposit

Use POST /rentals/{rentalId}/release-deposit.

This is for operator intervention when an active deposit should be released from the rental. It updates deposit state and publishes a deposit release event.

Check Start Requirements

Use GET /rental-requirements/start.

This endpoint helps an operator tool explain why a user can or cannot start a rental or booking. It evaluates the rental requirements configured for the branch and vehicle category, including requirements such as verification, payment method or pre-authorization, T&C, age, branch-level rules, business account context, and rental authority.

Typical inputs:

userId
branchId
vehicleCategoryId
userGroupId or userGroupCode for business rentals
bookingStartTime and bookingEndTime for booking-time-specific checks

Use this check before offering a manual start action or before creating an immediately active rental. If a requirement fails, show the failed requirement as an operator-facing explanation instead of treating the start failure as a generic rental error.

The same requirement model is also important for customer-facing rental start flows in the User API. This guide focuses on the operator use case: explaining blocked starts, resolving account or payment setup issues, and avoiding administrative rental creation that will immediately fail requirement checks.

Manage Rental Authority

Use the rental authority endpoints when operators need to grant or revoke a user’s right to rent on a branch:

Action	Endpoint
List users with rental authority on a branch	`GET /rental-authority?branchId={branchId}`
Grant authority	`POST /rental-authority?guserId={userId}&branchId={branchId}`
Revoke authority	`DELETE /rental-authority?guserId={userId}&branchId={branchId}`
Bulk grant/revoke	`PUT /rental-authority/bulk`

Rental authority is one of the checks that can block a rental from starting.

Work With Rental Additions

Rental additions are optional extras that can be sold to customers on top of a rental, such as an insurance option that reduces the customer’s deductible, a helmet, or another paid service. Operators configure additions and their pricing, and customers can select one or more additions for a rental.

Additions are selected before the rental starts. When a rental is created, include the additions that should be attached to that rental in the rental creation request. Once the rental has started, additions are not part of the normal rental update flow.

Operator tools can retrieve and price additions through /rentals/additions.

For new management workflows, prefer the newer /additions-management endpoints. Some /rentals/additions/{id} write operations are deprecated in favor of /additions-management/{id}.

Permissions And Settings

Rental tooling depends on the active user’s permissions and the branch/category configuration for the rental. A user can be allowed to inspect rentals in one branch but not create, start, end, or modify rentals in another branch.

Common permission areas:

Workflow	Permission consideration
List or inspect rentals	Rental read permissions on the relevant branch.
Create an administrative rental	Rental create permission on the vehicle’s branch.
Start, park, drive, end, renew, or open tailbox	Rental operation permissions and any vehicle/action permissions required by the configured workflow.
Release deposits or review billing	Finance/payment-related permissions may be required in addition to rental access.
Manage rental authority	Permission to grant or revoke rental authority for users on the branch.
Manage additions	Addition-management permissions for create, update, or delete workflows.

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 rental endpoint itself.

Settings and configuration that commonly affect rental workflows:

Area	Why it matters
Start rental requirements	Branch and vehicle-category requirements can block rental start, including payment pre-authorization.
End-rental requirements	Branch and vehicle-category requirements can block rental end until location, equipment, vehicle, or station conditions are fulfilled.
Vehicle category configuration	Determines allowed rental behavior, additions, actions, and vehicle-specific constraints.
Branch configuration	Controls operating area, business rules, rental authority, and local feature behavior.
Payment and deposit configuration	Determines whether deposits, pre-authorizations, or payment checks are required.

Use GET /settings when the tool already knows which DASHBOARD or SHARED setting keys it needs for a rental workflow. Use /settings-management to discover rental-related settings across areas and for administrative configuration workflows. Do not assume a rental feature is enabled for every branch or vehicle category.

Most Relevant APIs

Task	Endpoint
List rentals for a branch	`GET /rentals`
Create an administrative rental	`POST /rentals`
Get one rental	`GET /rentals/{rentalId}`
Cancel a reservation	`DELETE /rentals/{rentalId}`
Get route waypoints	`GET /rentals/{id}/routes`
Perform a rental operation	`POST /rentals/{rentalId}/operation`
Release a rental deposit	`POST /rentals/{rentalId}/release-deposit`
Get billing overview	`GET /rentals/{rentalId}/billing-overview`
Check rental start requirements	`GET /rental-requirements/start`
Manage rental authority	`GET/POST/DELETE/PUT /rental-authority`
Search and price rental additions	`GET /rentals/additions`
Manage additions	`GET/POST/PATCH/DELETE /additions-management`
Check current user’s permission	`GET /roles/assignments/exists`
Read relevant dashboard/shared settings by key	`GET /settings`

Error Handling

Rental APIs can fail for business reasons even when the request is technically valid. Common categories:

Category	Typical cause	What the client should do
Permission errors	Operator lacks permission on the branch or rental.	Show a permission message and avoid retrying.
Not found	Rental, vehicle, user, branch, or addition does not exist in the operator’s accessible scope.	Refresh local state and verify branch context.
Invalid state	The requested operation does not match the rental’s current state.	Re-fetch the rental before offering the operation again.
Concurrent processing	Another rental operation is already running.	Wait briefly, re-fetch rental state, then decide whether retrying is still valid.
Vehicle communication	IoT command failed or timed out.	Re-fetch rental and vehicle state before retrying.
Start rental requirements	User, branch, vehicle category, payment, pre-authorization, or rental authority requirement is not fulfilled.	Show the failed requirement and guide the operator to the account, payment, or permission action needed.
End-rental requirements	Vehicle cannot be ended at the current location or condition.	Show the failed requirement and guide the operator to the needed action.
Billing/payment	Deposit, invoice, or payment flow failed.	Route to support/finance workflow instead of blindly retrying rental operations.

For specific codes, see Error Codes. Rental-related codes usually start with R; vehicle communication codes often start with V; permission and user requirement errors can start with A, S, or U.

Implementation Notes For Custom Tools

Always scope operator rental lists by branchId.
Prefer includeChildBranches over deprecated includeChildren.
Re-fetch the rental after every write operation before showing the next available action.
Avoid double-submit UI behavior for rental operations. Operations are stateful and may be rejected while another operation is running.
Treat POST /rentals with startRentalState: "ACTIVE" and POST /rentals/{rentalId}/operation as high-impact actions.
Check start rental requirements before offering a manual start flow or creating an active rental on behalf of a user.
Persist the returned rental ID and current state in your tool, but do not assume cached state remains valid after vehicle operations.
Build operator audit views around events where possible; rental operations publish platform events.
Hide or disable rental actions when the current user lacks the relevant permission, but still treat endpoint permission checks as the source of truth.
Read branch and vehicle-category configuration before assuming start/end requirements, deposits, additions, or rental authority behavior.
For recurring bulk data ingestion, use Data Exports or the data warehouse instead of polling Operations API list endpoints or relying on /rentals/export.

Review Notes

The following product decisions are reflected in this guide:

Administrative rental operation fields are intentionally not documented individually here. External operator tools can use the documented rental operations; override details are advanced administrative behavior.
All rental operation types exposed by the Operations API are treated as supported for third-party operator tooling.
Start rental requirements are documented as branch and vehicle-category configuration, including payment pre-authorization configured at the vehicle-category level.
Rental domain permission and settings guidance is included here, while the general role/settings model remains in the Operations API Guide.
Recurring rental data ingestion should use Data Exports or the data warehouse, not /rentals/export.
Addition management should use /additions-management for create, update, and delete workflows.
Operations API endpoints are generally intended for interactive operator tooling. Data export workflows are the exception and should use the dedicated export/data products.
Platform webhook payloads are supported integration contracts for event-driven workflows.
Documented list filters are supported for building operator search and review screens.