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 vehicles to your fleet⚓︎

You can add single or multiple vehicles in a bulk. To add vehicles, you need to provide some mandatory data. You can additionally specify optional data, which also can be added later using the Vehicle Management API.

The following table gives you an overview what you need:

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

Adding a single vehicle⚓︎

If you want to add a single vehicle to your fleet, you can use the endpoint POST /vehicles of the API. The request will processed synchronous and the response contains the newly created vehicle.

Example adding a single vehicle⚓︎

The following example shows the API call to add a single vehicle:

 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": "NBSG7D2A50742X0F",
                "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 payload 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": "NBSG7D2A50742X0F",
    "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"
  }
}

Adding multiple vehicles⚓︎

To add multiple vehicles to your fleet, you can use the endpoint POST /vehicles-bulk of the API. This allows to submit all data in a single request instead of adding individual vehicles in separate requests. To test the whole process and validate the data, you can use the path parameter dry_run=true. If you use a dry run, no vehicle will be added. The query is similar to adding a single vehicle, however, the individual vehicles are to be specified in a list of items:

 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
{
    "items": [
        {
            "telematics_unit": {
                "id": "NBSG4C7B40647G5M",
                "brand": "NIU",
                "setup": {
                    "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G"
                },
                "authentication": {
                    "credentials_id": "01F62857KMPG2NE2GK1W2N3QYS"
                }
            }
        },
        {
            "telematics_unit": {
                "id": "NBSG4C7W425DHEGMN",
                "brand": "NIU",
                "setup": {
                    "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G"
                },
                "authentication": {
                    "credentials_id": "01F62857KMPG2NE2GK1W2N3QYS"
                }
            }
        }
    ]
}

The vehicles to be added will be processed asynchronous. The response contains the unique identifier id of the bulk, the overall status, if the bulk was a dry_run, the total number of vehicles to be added total_count, the number of processed vehicles processed_count and all items:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "id": "G6KL5",
    "status": "RUNNING",
    "dry_run": false,
    "processed_count": 0,
    "total_count": 2,
    "items": [
        {
            "id": "01FGPBABK6QVT6T0KW5EXFVNA5",
            "status": "PENDING"
        },
        {
            "id": "01FG1EEAJHXB8NCKZV8C8411ZY",
            "status": "PENDING"
        }
    ]
}

The initial status of the bulk is RUNNING. The status can have the following values:

RUNNING
At least one item is not finished.
FINISHED
All items were processed.
The order of the elements in the response corresponds to that from the request, which means that the response for the 3rd vehicle to be created from the request is also in the 3rd position in the response.
All items contain a unique item id and its status. Note that items can succeed or fail separately. The status of an item can have the following values:
PENDING
The item has not started yet.
RUNNING
The item is currently being processed.
SUCCEEDED
The item has successfully finished and a vehicle is added to your fleet.
FAILED
There was an error on adding the vehicle to your fleet.

If a item succeeds, it contains the vehicle_id. In case of an failed item, it contains problem details.

To monitor the whole process, you can poll the endpoint GET /vehicles-bulk/{id} with your received unique bulk id.

Example adding multiple vehicles⚓︎

In order to add multiple vehicles, you need to submit a request including all vehicles you want to add. You can send a request including two vehicles as shown below:

 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-bulk \
    -H 'Authorization: Bearer ❰access_token❱' \ # (1)
    -H 'Content-Type: application/json' \
    -d '{
            "items": [
                {
                    "telematics_unit": {
                        "id": "NBSG4C7B40647G5M", 
                        "brand": "NIU",
                        "setup": {
                            "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G"
                        },
                        "authentication": {
                            "credentials_id": "01F62857KMPG2NE2GK1W2N3QYS"
                        }
                    }
                },
                {
                    "telematics_unit": {
                        "id": "NBSG4C7W425DHEGMN",
                        "brand": "NIU",
                        "setup": {
                            "vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G"
                        },
                        "authentication": {
                            "credentials_id": "01F62857KMPG2NE2GK1W2N3QYS"
                        }
                    }
                }
            ]
        }
  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 207.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "id": "G6KL5",
    "status": "RUNNING",
    "dry_run": false,
    "processed_count": 0,
    "total_count": 2,
    "items": [
        {
            "id": "01FGPBABK6QVT6T0KW5EXFVNA5",
            "status": "PENDING"
        },
        {
            "id": "01FG1EEAJHXB8NCKZV8C8411ZY",
            "status": "PENDING"
        }
    ]
}

Keep in mind to monitor the status of the bulk. After some time, the items are processed and the vehicles added to your fleet. A finished bulk response could look like this:

 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
{
    "id": "G6KL5",
    "status": "FINISHED",
    "dry_run": false,
    "processed_count": 2,
    "total_count": 2,
    "items": [
        {
            "id": "01FGPBABK6QVT6T0KW5EXFVNA5",
            "status": "FAILED",
            "problem": {
                "type" : "/problems/unique-identifier-already-exists",
                "title": "Unique identifier already exists",
                "status": 409,
                "detail": "Validation of the 'telematics_unit' data failed: Element already exists.",
                "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
            }
        },
        {
            "id": "01FG1EEAJHXB8NCKZV8C8411ZY",
            "status": "SUCCEEDED",
            "vehicle_id": "K7272"
        }
    ]
}

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