Skip to content

Vehicle Models⚓︎

Vehicle models are used to describe the behavior and capabilities of every vehicle in the INVERS API. When adding a vehicle to your fleet directly through our API, you need to provide the ID of the corresponding vehicle model. Choosing the correct vehicle model is important since the vehicle model describes how the telematics unit needs to be configured in order to provide the correct vehicle commands and vehicle state values.

Important

For most use cases, it is sufficient to use our FleetControl UI or our SmartControl app to add or remove vehicles to/from your fleet. You only need to read this page if you would like to integrate your software stack even deeper with the INVERS API, e.g. if you would like to query vehicle model information from within your own applications.

Get all available vehicle models⚓︎

The INVERS API supports a range of vehicle models from which you can choose. To find the right model, you can use the endpoint GET /telematics-brands/{brand}/available-vehicle-models of the Vehicle Lifecycle API.

Here is an example of what the response payload might look like when using CLOUDBOXX as telematics brand:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "items": [
    {
      "id": "01GG9QFP7432K1QT65T4Q4HWSD",
      "vehicle_brand": "INVERS",
      "vehicle_model": "Devkit 4G",
      "vehicle_type": "DEV_KIT",
      "regions": [
        "Europe",
        "USA",
        "Canada",
        "South America",
        "Australia"
      ],
      "version": 3,
      "documents": [],
      "start_of_production": "2019-01",
      "central_lock_connection_types": [
        "DIRECT"
      ],
      "capabilities": {
        "commands": [
          "DISABLE_DRIVING",
          "ENABLE_DRIVING",
          "LOCK_CENTRAL_LOCK",
          "UNLOCK_CENTRAL_LOCK"
        ],
        "vehicle_state": [
          "CENTRAL_LOCK",
          "DRIVING_ENABLED",
          "IGNITION",
          "MILEAGE_IN_KILOMETERS",
          "ONBOARD_VOLTAGE_IN_VOLTS",
          "SPEED_IN_KPH"
          "STATE_OF_CHARGE_OR_FUEL_LEVEL_IN_PERCENT",
        ]
      },
      "cardb_key": "HKNCY",
      "mileage_source": "VSS",
      "setup_required": true,
      "requires_total_mileage_sync": true
    }
  ]
}

Once you have found the right model, you can use its ID in the POST /vehicles request as described in the Vehicle Lifecycle API.

Model Extensions⚓︎

Info

Model extensions are supported by cars connected via OEM integrations or by two-wheeler vehicles connected via OEM integration or with a built-in CloudBoxx.

Basic capabilities for your vehicle are defined by the model’s capabilities. Those capabilities only describe the most basic configuration of the vehicle. Just like the vehicle may have optional accessories, e.g. a top case, the vehicle model supports optional extensions. These supported extensions describe what accessories the vehicle can have, as well as what capabilities are associated with each one of them. When a vehicle is created, its actual capabilities are those of the vehicle model combined with those from the selected model extensions.

When calling GET /telematics-brands/{brand}/available-vehicle-models, the vehicle models in the response payload contain a property called supported_extensions. This property lists all supported extensions for a vehicle model including their capabilities.

The following extensions are available (depending on the model):

  • SELF_LOCKING_TOP_CASE can be used for top cases that lock automatically when closed
  • REMOTE_LOCKING_TOP_CASE can be used for top cases that need to be locked via the API
  • SUNROOF can be used for vehicles with a sunroof (only supported by OEM integrations)

Adding a vehicle with model extensions⚓︎

When creating a vehicle, you can select the model extensions for the vehicle by adding the property model_extensions to the setup when using the endpoint POST /vehicles of the Vehicle Lifecycle API.

Example

The example below shows the API call to add a single vehicle with model extensions. In the example, a vehicle is added which has a top case that can be locked remotely using the Vehicle Commands API.

curl -X POST \
https://api.invers.com/vehicles \
-H 'Authorization: Bearer ❰access_token❱' \ # (1)!
-H 'Content-Type: application/json' \
-d '{
      "telematics_unit": {
        "id": "NBSG7D2A50742X0F",
        "brand": "NIU",
        "setup": {
          "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G",
          "model_extensions": [
            "REMOTE_LOCKING_TOP_CASE"
          ]
        },
        "authentication": {
          "credentials_id": "01F62857KMPG2NE2GK1W2N3QYS"
        }
      },
      "master_data": {
        "vin": "R1NBDNB16J1000135",
        "license_plate": "RKL-832",
        "brand": "NIU",
        "model": "N1",
        "custom_name": "MyNiuN1",
        "fuel_type": "ELECTRIC",
        "year_of_production": "2020",
        "transmission": "AUTOMATIC",
        "vehicle_type": "MOPED",
        "remark": "Our customers like that scooter very much."
      },
      "custom_fields": {
        "seats": "2",
        "color": "black"
      }
    }'
  1. Don’t forget to fill in your access token.

In the response body of this request, the created vehicle contains the additional capabilities from the selected extension (REMOTE_LOCKING_TOP_CASE):

  • LOCK_TOP_CASE and UNLOCK_TOP_CASE as command capabilities
  • TOP_CASE_LID and TOP_CASE_LOCK as vehicle state capabilities

Updating model extensions of an existing vehicle⚓︎

Model extensions can also be added to an existing vehicle. To update the model extensions of an existing vehicle simply use the PUT /vehicles/:id/telematics-unit/setup endpoint and provide the extensions you want to select using the property model_extensions in the setup object.

Warning

Keep in mind that this endpoint will override all selected extensions that where previously assigned to the vehicle. Always provide all required information when calling the telematics unit setup endpoint.