Skip to content

Vehicle Lifecycle API⚓︎

Want to integrate CloudBoxx?

Currently, you can only access your CloudBoxx-equipped vehicles with the CloudBoxx API but not yet through the INVERS OneAPI. We are actively working on making all CloudBoxx features available in the INVERS OneAPI.

Learn More

Vehicle Lifecycle API

API Reference

API Changelog

The Vehicle Lifecycle API allows you to add vehicles to your fleet.

Note, that you only need to integrate this API if your booking software is automatically adding vehicles to your fleet or if you have a special workflow. You will be able to add your vehicles via FleetControl soon.

How to add a vehicle to your fleet⚓︎

You need the following information:

Information Description Example
telematics_brand Brand of the telematics unit. NIU
telematics_unit_id ID for the telematics unit that was assigned by the manufacturer. NBSG4C7B40647G5M as a NIU device serial number
vehicle_model_id ID of the vehicle_model the vehicle has. See vehicle models for more details. 01F4XW6QHWKT4HMSFDZ9CCQH1G references the model “NIU N1 with top case”
credentials_id (only for telematics units using shared credentials) ID of the credentials for the third-party API, that are stored in the INVERS OneAPI system. See credentials for more details. 01F62857KMPG2NE2GK1W2N3QYS references your NIU Client ID and Client Secret
password (only for telematics units using individual credentials) The password that is necessary to communicate with the telematics unit. 12345
master_data (optional) This can range from VIN or license plate to the fuel type of the vehicle. See master data for more details. "vin": "R1NBDNB16J1000135"
custom_fields (optional) This can be any additional information as key-value pairs. See custom fields for more details. "seats": 4
tags (optional) Tags can be used to group vehicles together. See tags for more details. ["in_maintenance", "demo_night"]
operation_status (optional) The initial value for the operation_status of the vehicle (default is OPERATING). See operation status for more details. GARAGE

You must provide this information when making a request to add your vehicle via POST /vehicles.

Example⚓︎

The following example shows this API call. First, follow instructions to get an access token in order to retrieve a valid access token for the INVERS OneAPI.

 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
curl -X POST \
  'https://api.invers.com/vehicles' \
  -H 'Authorization: Bearer ❰access_token❱' \ # (1)
  -H 'Content-Type: application/json' \
  -d '{
        "telematics_unit": {
          "id": "NBSG4C7B40647G5M",
          "brand": "NIU",
          "setup": {
            "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G"
          },
          "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.

If the request has been successful, a JSON object is returned along with HTTP status code 201.

Here is an example of what the response might look like:

 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
45
46
47
48
49
50
51
52
53
54
55
{
  "id": "JQ7RP",
  "fleet_id": "F48XD",
  "created_at": "2021-01-19T13:13:09.952Z",
  "master_data": {
    "modified_at": "2021-01-19T13:13:09.952Z",
    "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."
  },
  "capabilities": {
    "commands": [
      "UNLOCK_TOP_CASE",
      "LOCK_TOP_CASE",
      "DISABLE_DRIVING",
      "ENABLE_DRIVING",
      "DRAW_ATTENTION",
      "UNLOCK_BATTERY_COMPARTMENT"
    ],
    "vehicle_state": [
      "FUEL_LEVEL_IN_PERCENT",
      "TOP_CASE_LOCK",
      "TOP_CASE_LID",
      "POSITION",
      "DRIVING_ENABLED"
    ]
  },
  "telematics_unit": {
    "id": "NBSG4C7B40647G5M",
    "attached_at": "2021-01-19T13:13:09.952Z",
    "manufacturer": "NIU",
    "brand": "NIU",
    "type": "EMBEDDED"
  },
  "life_status": {
    "value": "OFFLINE",
    "modified_at": "2021-01-19T13:13:09.952Z"
  },
  "operation_status": {
    "value": "OPERATING",
    "modified_at": "2021-01-19T13:13:09.952Z"
  },
  "custom_fields_modified_at": "2021-01-19T13:13:09.952Z",
  "custom_fields": {
    "seats": "2",
    "color": "black"
  }
}

How to change the model of an existing vehicle⚓︎

Usually, once a vehicle has been created, the associated vehicle model will not change. However, you may want to change it when you add a top case to an existing vehicle (say a moped) or have selected an ill-fitting model when creating the vehicle. The Vehicle Lifecycle API provides the PUT /vehicles/:id/telematics-unit/setup endpoint to allow just that.

You just have to provide the ID of the vehicle model you want to use.

Example⚓︎

The following example shows this API call. First, follow the instructions to get an access token in order to retrieve a valid access token for the INVERS OneAPI.

1
2
3
4
5
6
7
curl -X PUT \
  'https://api.invers.com/vehicles/JQ7RP/telematics-unit/setup' \
  -H 'Authorization: Bearer ❰access_token❱' \ # (1)
  -H 'Content-Type: application/json' \
  -d '{
        "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G"
      }' # (2)
  1. Don’t forget to fill in your access token.
  2. The body is exactly the same as the object you would use in telematics_unit.setup when creating a vehicle with this model. Hence the name “setup”.

If the request is successful, a JSON object will be returned along with HTTP status code 200.

Here is an example of what the response might look like:

1
2
3
4
{
  "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G",
  "status" : "SUCCEEDED"
}

Details⚓︎

Credentials⚓︎

In most cases an authentication mechanism secures the telematics unit from being used by a malicious person. Oftentimes, the authentication mechanism dictates that certain credentials should be passed along in order to communicate with the telematics unit. The manufacturer of the telematics units or vehicle will provide you with these credentials.

The INVERS OneAPI needs these credentials in order to communicate with your telematics units. For example, whenever a command is sent to a NIU vehicle using the Vehicle Commands API, this command has to be translated and sent to the appropriate endpoint(s) of the NIU API. The INVERS OneAPI has to authenticate at this endpoint using your NIU credentials (client_id and client_secret).

shared vs. individual credentials

shared credentials

The credentials for vehicles, that are connected through a cloud solution and therefore a third-party API, are typically shared by a group of vehicles. We call this kind of credentials shared credentials.

Storing your (shared) credentials for this third-party API is a necessary step before you can add a CloudConnect vehicle to your fleet.

individual credentials

In some cases, mostly when a direct connection to the telematics unit via TCP is needed, the telematics unit has an individual password. This password needs to be transmitted when communicating with the telematics unit in order for it to do anything. We call this kind of credentials individual credentials.

In this case you don’t need to store any credentials prior to adding your vehicle, but provide the password while adding it.

As stated above, you need to provide the necessary credentials before you add a vehicle to your fleet that is accessed via shared credentials. Please use the Credentials API for this. You can provide multiple different credentials for the same third-party API. This enables the use of vehicles that require different credentials for the third-party API in your fleet. For example, NIU vehicles that are part of different NIU fleets can therefore all be part of your single fleet.

When storing the credentials via the Credentials API, an ID is generated for them. This ID should be used in the request POST /vehicles above when adding a vehicle.

You can also use the Vehicle Lifecycle API described here to request all credentials you previously provided via the Credentials API. Request the stored credentials via /telematics-brands/{brand}/available-credentials.

Telematics units⚓︎

Typically, the telematics manufacturer will give you the ID of the telematics unit that is installed in the vehicle. In some instances, you can conveniently query which telematics units of that brand are available to add to your fleet. This depends on the telematics brand.

A telematics unit is available for use in a new vehicle if it is not part of any fleet at the moment and is accessible using one of the credentials provided via the Credentials API. Use /telematics-brands/{brand}/available-telematics-unit to figure out which telematics units can be used in a vehicle to be added to your fleet. Once a telematics unit is part of your fleet, it is no longer visible via the API.

Vehicle models⚓︎

In order for the vehicle to behave like the real vehicle, for example like a NIU N1 scooter, you need to provide the make and model of the vehicle you want to add to your fleet. This ensures that the vehicle has the right capabilities after adding it to your fleet.

The INVERS OneAPI supports a multitude of vehicle models from which you can choose. To find the right model, you can use this API and query all supported models: View the different vehicle models of a specific telematics brand via GET /telematics-brands/{brand}/available-vehicle-models. When you have found the right model, you need to use the ID associated with the vehicle model for the POST /vehicles request described above.

In case you used the wrong vehicle model or reconfigured the vehicle (e.g. adding a top case to an existing moped), you can change the model of an existing vehicle.

Back to top