Typical Rental Flow⚓︎

This page is intended to be used as a guide if you are planning to implement a robust vehicle rental flow in your backend services and customer apps. In the following sections, we outline a typical sequence of actions and interactions happening during a vehicle rental. We also point out typical challenges and show how to overcome them.

We first and foremost describe the “happy flow” of a vehicle rental, starting from the moment the end customer would like to start their rental. We talk about trip pauses in between, leading up to the end of the rental where you need to make sure the end customer leaves the vehicle at the correct position and in the correct state to successfully end their rental. If applicable, additional hints and tips will be given, helping you to make your implementation more robust and to stay on that “happy flow” path as best as possible.

Note that we do not cover the reservation of vehicles before an actual rental, neither do we cover invoicing and billing topics. Both are not within the scope of the INVERS API.

General recommendations⚓︎

Consume the VehicleStateRecorded topic of our Events API to always receive the most recent state of your vehicles and store it in your database. Use the stored vehicle state to answer requests from your end customer apps or to handle internal booking system processes much faster than by actively requesting a new vehicle state every time you need it. We strongly discourage you from actively requesting a new vehicle state using the corresponding vehicle command too often.
Do not store or even process any credentials to the INVERS API within your customer apps. Always use your backend services as a proxy to our APIs and keep your API credentials safely stored in your backend services. Properly authenticate the end customer against your backend services and make sure they are allowed to start a rental and use the corresponding vehicle before sending any commands to the vehicle. Send all vehicle commands from your backend services and never directly from the customer apps.
If you would like to communicate with the vehicle directly using your customer apps, consider using Bluetooth. This can make your rental flow more resilient to connectivity issues (see below for further details).

Start rental⚓︎

Unlocking the vehicle⚓︎

The rental flow starts as soon as the customer would like to locate and access the vehicle. Use the latest vehicle state to give the customer up-to-date information about the vehicle, such as its location. Once the end customer has arrived at the vehicle and would like to start the rental, you usually need to unlock the vehicle’s central lock and enable driving (= disable the immobilizer).

Example: Unlock vehicle and enable driving

Send a command to simultaneously unlock the vehicle’s central lock and disable the immobilizer / enable driving. Have a look at our Vehicle Commands API for more information.

curl -X POST \
'https://api.invers.com/vehicles/❰vehicle_id❱/commands/unlock-and-enable-driving' \ # (1)!
-H 'Authorization: Bearer ❰access_token❱' \ # (2)!
-H 'Content-Type: application/json' -d ''

Replace ❰vehicle_id❱ with the ID of the vehicle.
Replace ❰access_token❱ with your access token.

Depending on the vehicle type and the installed telematics unit, but also your desired customer journey, you might want to use the above mentioned combined command or execute those steps separate from each other. Our Vehicle Commands API enables you to adapt the process to your needs and requirements, by offering the following commands related to the start of the rental:

unlock-central-lock: Unlock the vehicle’s central lock. This will give the customer access to the vehicle.
enable-driving: Enable driving for the vehicle. For most vehicles (especially cars) this will unlock the immobilizer.
unlock-and-enable-driving: Enable driving and unlock the vehicle’s central lock in one go (combines the two commands above).

Use Bluetooth Commands

Instead of using the Vehicle Commands API you can also use Bluetooth. It allows you to send commands from your customer app to a CloudBoxx-equipped vehicle directly, which is especially helpful in offline scenarios.

Note that unlock-and-enable-driving is a combined command that is not supported by all telematics brands. The INVERS CloudBoxx supports this command. Using the combined command reduces the number of API calls necessary and provides an atomic operation for changing the immobilizer and the vehicle’s central lock in one go.

To determine the commands that can be sent to a vehicle, we use the concept of capabilities. Before sending a command to your vehicle, use the vehicle’s capabilities to ensure the built-in telematics unit supports the given command.

Data protection features⚓︎

Once the customer got access to the vehicle and starts the trip, you may want to inform INVERS about the start of the rental by setting the rental status for the vehicle. This way INVERS can conform to the data protection packages that are configured for your fleet. Use the Vehicle Management API to set the rental status for the vehicle.

Even if you are not using the data protection and privacy features of the INVERS OneAPI we recommend to set the correct rental status. Amongst other things, this helps us to ensure that CloudBoxx firmware updates are not performed while the vehicle is in use.

Example: Set rental status of a vehicle

The following example shows how to set a vehicle’s rental status to IN_RENTAL. The INVERS OneAPI uses this information to enforce the data protection rules configured for your fleet (e.g., filter out a vehicle’s position during a rental for privacy reasons).

curl -X PUT \
'https://api.invers.com/vehicles/❰vehicle_id❱/rental-status?request_new_vehicle_state=true' \ # (1)!
-H 'Authorization: Bearer ❰access_token❱' \ # (2)!
-H 'Content-Type: application/json' \
-d '{
        "value": "IN_RENTAL"
    }'

Replace ❰vehicle_id❱ with the ID of the vehicle.
Replace ❰access_token❱ with your access token.

By setting the query parameter request_new_vehicle_state to true, a new vehicle state will be requested from the vehicle and returned in the response.

During rental⚓︎

During the rental you can continue to consume events and vehicle states via our Events API. Note that these events will comply to your selected data protection packages (see above). Depending on your selected data protection packages, vehicle states and events may contain fewer data than outside of the rental.

Keep in mind that you should not execute any commands while the customer is driving (if the vehicle’s ignition is on). This may lead to unwanted behavior during the rental.

Data protection: Remote Service

If your fleet has the “Remote Service” data protection feature enabled, you can use the request-vehicle-state command while the vehicle is in a rental. This can be useful to assist the end customer with any problems they might have. If the “Remote Service” package is disabled, you cannot actively request a new vehicle state during rentals.

Stopovers⚓︎

During a rental the customer might need to take a break or do a stopover. Depending on the vehicle type and model, stopovers need to be handled differently.

If the vehicle key is present in the vehicle, the end customer can simply take the key with them during breaks and use it to lock and unlock the vehicle. In this case, you can identify stopovers by looking at the ignition value, and also by checking the vehicle’s central lock value. The latter, however, is highly dependant on the vehicle model’s capability and not supported by all vehicle types and models.
If the vehicle does not have a physical key (keyless go) your customers need to use your app to secure the vehicle during stopovers. Use the same commands as for start and end of the rental (with similar checks, if required) to lock and immobilize the vehicle at the beginning of a break and to unlock and enable driving again at the end.

If the customer initiates a stopover at a location with bad signal quality, vehicle commands might not work. Consider using Bluetooth as a fallback or even primary communication channel to allow for the best customer experience.

End rental⚓︎

Set the rental status

Use the Vehicle Management API to update the vehicle’s rental status. See the example above for more details (use NOT_IN_RENTAL as value in order to effectively disable data protection mode).

If you are using any of our data protection features you will, depending on the exact configuration of your fleet, receive fewer data while the vehicle is in rental. Therefore, once the customer indicates that they would like to end their rental, you first need to change the vehicle’s rental status back to NOT_IN_RENTAL again. You can optionally request a new vehicle state when making this request, which helps you getting the vehicle state information you need for your end rental checks (see below).

End rental conditions⚓︎

Before the customer can successfully end their rental, you should check if all your desired end rental conditions are met. The conditions you can check depend on the capabilities of the vehicle, and how strict and foolproof you would like to design your rental workflow. The following list shows some suggestions of end rental checks that we recommend, including the corresponding vehicle state capabilities. The list is roughly prioritized, meaning the first bullet points are more important and more commonly used, or generally have a higher number of vehicle models supporting them:

ignition has been turned off (IGNITION)
vehicle is parked within a designated business area, or close to its home location (POSITION)
the vehicle key and cardholder cards are present (VEHICLE_KEY and CLOUDBOXX_CARDHOLDER_CARDS) - not applicable for keyless go vehicles
doors and windows are closed (DOORS_STATUS, WINDOWS_STATUS)
parking brake is engaged (PARKING_BRAKE_ENGAGED)
headlights are turned off (HEADLIGHTS)

If some or all end rental conditions are not met, ask your customer to take action via corresponding instructions in your customer app. Let them bring the vehicle into the desired state before securing the vehicle and ending the rental. Some end rental conditions (did the customer take all of their belongings? does the vehicle need to be cleaned?) will of course need to be solved differently and can not be read from the vehicle state. If needed, we recommend that you remind the customer about those topics, or potentially even ask for a confirmation within your customer app.

Vehicle state with end rental conditions not met

The following example shows a truncated vehicle state. The vehicle’s ignition has already been turned off, and all windows are closed. However, one or more doors are still open (doors_status is OPEN). In a case like this you should ask your customer to close all doors. As soon as all doors have been closed you will receive a new vehicle state via our Events API in which doors_status is CLOSED.

{
  "ignition": {
    "timestamp": "2024-02-19T13:22:05Z",
    "value": "OFF"
  },
  "windows_status": {
    "timestamp": "2024-02-19T13:22:05Z",
    "value": "CLOSED"
  },
  "doors_status": {
    "timestamp": "2024-02-19T13:22:05Z",
    "value": "OPEN"
  },
  // ... (truncated)
}

You can monitor the vehicle’s state and check for end rental conditions in near real-time by consuming vehicle states via our Events API, mainly the VehicleState topic and the VehicleStateRecorded event. There is usually no need to actively request a new vehicle state, especially when using the INVERS CloudBoxx. The CloudBoxx is highly event-driven and will automatically produce a new vehicle state each time a vehicle state value changes.

As a fallback, you could use the request-vehicle-state command to actively request a new vehicle state from the telematics unit. However, as mentioned before, this shouldn’t be necessary in a “happy flow” and if your booking software properly consumes vehicle states via our Events API.

Securing the vehicle⚓︎

Once all end rental conditions have been met, your customer can end their rental (usually by using your booking app). Now it is time to secure the vehicle:

lock-central-lock: Lock the vehicle’s central lock.
disable-driving: Disable driving for the vehicle. For most vehicles this will lock the immobilizer.
lock-and-disable-driving: Execute both of the above in one atomic, combined command.

If your vehicle (the installed telematics unit) supports the combined command lock-and-disable-driving we highly recommend using this command. You can check the vehicle’s command capabilities in order to find out whether or not that is possible. If the combined command is not supported or if you require a workflow where locking the immobilizer should be separate from locking the vehicle’s central lock, simply use the individual commands lock-central-lock and disable-driving.

Connectivity issues when ending the rental⚓︎

If the vehicle is parked at a location without any connectivity (like an underground parking garage) you might not receive vehicle states and it might not be possible to execute vehicle commands through our Vehicle Commands API. For these cases you can implement a range of safeguards to lessen the impact of potential connectivity issues.

If no new vehicle states have arrived via our Events API for some time and you are waiting for an end rental condition to be met, go ahead and try to actively request a new vehicle state.
If the vehicle has no cellular connection (request vehicle state command fails with a connection error), use Bluetooth as a fallback. When using the INVERS CloudBoxx, you can develop your customer app in a way that your rental workflow can still work even if the customer’s smartphone and the CloudBoxx are both without a cellular connection. In such a case, your customer app can perform end rental checks locally (see below for detailed information).

Bluetooth⚓︎

If you are using a CloudBoxx you can use Bluetooth (BLE) to communicate with the vehicle directly instead of sending requests through your backend services and the INVERS OneAPI. Bluetooth can be used as a fallback if communication to your backend services or the vehicle is not possible or not reliable enough - usually when the vehicle is parked outside of cellular connectivity, for example in underground parking garages. You can also use Bluetooth as your primary communication with the vehicle due to its lower latency compared to HTTP requests.

You need a Bluetooth token in order to authenticate your end customer app against the CloudBoxx. Once authenticated, you can receive vehicle state information and send commands to the CloudBoxx via BLE from within your customer app. Use the CloudBoxx Bluetooth Token Management API to create and manage those tokens. Detailed documentation on the BLE API of the CloudBoxx, as well as instructions and recommendations on token handling, can be found in our BLE documentation. A login (see top right corner) is required to view this page.

Troubleshooting⚓︎

Command responses⚓︎

When sending a command to the vehicle, the request may time out (see connection error) but ultimately the command might still be executed. Such a case can be caused by connectivity issues kicking in during the execution of the command. The response of the telematics unit might not make it back to the INVERS OneAPI backend services, meaning you will not receive a command response containing an updated vehicle state.

We recommend to not only rely on command responses, but further validate the processing of a command by waiting for relevant events using the Events API. For example, when sending the command lock-central-lock, wait for the corresponding change event CentralLockChanged or consume every VehicleStateRecorded event to monitor changes to the central lock (and other vehicle state values) yourselves.

Central lock changes might be delayed

Keep in mind that changing the vehicle’s central lock is taking some time. Depending on the vehicle model, it might even take several seconds until a new central lock value can be read from the vehicle and reported back. In case you do not receive an updated vehicle state with changes you are expecting, consider manually requesting the current vehicle state using the Vehicle Commands API.