Skip to content

Vehicle Models⚓︎

Vehicle models are used to describe the behavior of a vehicle at a basic level. When adding a vehicle to your fleet, you need to provide a model for the vehicle. This ensures that the vehicle has the right capabilities after adding it to your fleet.

Get all available vehicle models⚓︎

The INVERS OneAPI 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 NIU 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
{
  "items": [
    {
      "id": "01F4XW6QHWKT4HMSFDZ9CCQH1G",
      "vehicle_brand": "NIU",
      "vehicle_model": "N1",
      "vehicle_type": "MOPED",
      "credential_type": "INDIVIDUAL",
      "capabilities": {
        "commands": [
          "DISABLE_DRIVING",
          "DRAW_ATTENTION",
          "ENABLE_DRIVING",
          "UNLOCK_BATTERY_COMPARTMENT"
        ],
        "vehicle_state": [
          "CELLULAR_SIGNAL_QUALITY",
          "DRIVING_ENABLED",
          "FUEL_LEVEL_IN_PERCENT",
          "MILEAGE_IN_KILOMETERS",
          "POSITION",
          "REMAINING_RANGE_IN_KILOMETERS"
        ]
      },
      "setup_required": false,
      "supported_extensions": [
        {
          "name": "REMOTE_LOCKING_TOP_CASE",
          "capabilities": {
            "commands": [
              "LOCK_TOP_CASE",
              "UNLOCK_TOP_CASE",
            ],
            "vehicle_state": [
              "TOP_CASE_LID",
              "TOP_CASE_LOCK",
            ]
          }
        }
      ]
    }
  ]
}

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⚓︎

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 respone 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

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.