FleetShare

Vehicle Management API

API Reference

API Changelog

FleetShare makes it possible to share vehicles between different INVERS One API fleets while regulating the vehicle access and safe handover of control. It can help to better utilize vehicles when they would otherwise be idle in their own fleet. Furthermore, it can help platforms increase their vehicle supply. Operational processes like cleaning or maintenance through external service providers can also be handled more easily and securely with FleetShare.

FleetShare is part of the Vehicle Management API and can only be used with registered partners.

Vehicle Sharing

The table below gives you an overview of the sharing object attached to the vehicle.

Information	Description
owner	Contains the fleet_id and name of the owner of the vehicle.
partner	Contains the fleet_id and name of the partner using the vehicle.
starts_at	UTC timestamp at which the sharing starts.
ends_at	UTC timestamp at which the sharing ends.

Owner and partner are the two involved parties in FleetShare. When you create a new sharing, you are always the owner as you share your vehicles with another fleet. If another fleet shares a vehicle with your fleet, you are the partner. In this case, the shared vehicle will be returned alongside your own vehicles when requesting all vehicles.

While a vehicle is shared, some restrictions apply depending on whether you are the owner or the partner. As the owner, you cannot send commands to shared vehicles. As the partner, you have read-only access to shared vehicles. You can send commands, but all other modifying operations are forbidden. During sharing, both the owner and the partner receive events from shared vehicles.

Start Sharing

To start sharing, use the POST /vehicles/{id}/sharing endpoint. You need the fleet_id of the fleet you would like to share the vehicle with. Possible fleets for sharing can be retrieved via the partners endpoint GET /sharing-partners. Optionally, it is possible to specify an ends_at timestamp when the sharing should be ended. If left empty, the sharing will be created with an open end. The ends_at timestamp can also be changed with a patch.

The following example shows the API call to share a vehicle:

Example: Start sharing

curl -X POST \
  https://api.invers.com/vehicles/FK852/sharing \
  -H 'Authorization: Bearer ❰access_token❱' \ # (1)!
  -H 'Content-Type: application/json' \
  -d '{
        "ends_at": "2022-01-01T12:12:12.000Z",
        "fleet_id": DE3P4
      }'

1. Don’t forget to fill in your access token.

If the request has been successful, the vehicle will be returned with HTTP status code 200 (some contents of the following example response are shortened):

response (json)

{
  "id": "FK852",
  "fleet_id": "78LMK",
  ...
  "sharing": {
    "ends_at": "2022-01-01T12:12:12.000Z",
    "owner": {
        "fleet_id": "78LMK",
        "name": "ShareOne"
    },
    "partner": {
        "fleet_id": "DE3P4",
        "name": "ShareTwo" 
    },
    "starts_at": "2021-12-20T11:15:000Z",
    "status": "SHARED_OWN_VEHICLE"
  }
  ...  
}

End Sharing

Sharing can be ended by the owner or partner at any time. Once the sharing is ended, the vehicle is returned to the owner’s fleet. The owner is then able to send commands again while the partner loses all access to the vehicle. The API offers two endpoints for ending sharing. Which one you have to use depends on whether you are the owner or the partner. Owners must use DELETE /vehicles/{id}/sharing while partners have to use DELETE /vehicles/{id}/sharing/partner.

Example: End sharing as owner

curl -X DELETE \
  https://api.invers.com/vehicles/FK852/sharing \
  -H 'Authorization: Bearer ❰access_token❱' \ # (1)!

1. Don’t forget to fill in your access token.

Example: End sharing as partner

curl -X DELETE \
  https://api.invers.com/vehicles/FK852/sharing/partner \
  -H 'Authorization: Bearer ❰access_token❱' \ # (1)!

1. Don’t forget to fill in your access token.