Vehicle Lifecycle API⚓︎
The Vehicle Lifecycle API allows you to add or remove vehicles from your fleet.
Prerequisites⚓︎
The table below gives you an overview about the data of your vehicle or telematics unit which you need for this process. Some of the data points are mandatory, while others are optional. You can add or update the additional/optional data later using the Vehicle Management API.
| Information | Description | Example |
|---|---|---|
telematics_brand |
Brand of the telematics unit. | CLOUDBOXX |
telematics_unit_id |
ID for the telematics unit that was assigned by the manufacturer. | 38429DA427AB7C25 as a CloudBoxx QNR |
vehicle_model_id |
ID of the vehicle’s vehicle_model. See vehicle models for more details. |
01F4XW6QHWKT4HMSFDZ9CCQH1G references the model “Audi A3” |
credentials_id (only for telematics units using shared credentials) |
ID of the credentials for the third-party API. 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 |
How to add vehicles to your fleet⚓︎
Important
You only need to integrate this API if you would like to add vehicles to your fleet using your booking software or some other automated script or application. The “adding vehicle assistant” within FleetControl and SmartControl provides you with a user interface for this API, which is sufficient for most use cases, and also faster and easier to use.
If you want to add a single vehicle to your fleet, you can use the endpoint POST /vehicles of the Vehicle Lifecycle API (see documentation). Your request will be processed synchronously and the response contains the newly created vehicle.
The following example shows the API call to add a single vehicle:
curl -X POST \
https://api.invers.com/vehicles \
-H 'Authorization: Bearer ❰access_token❱' \ # (1)!
-H 'Content-Type: application/json' \
-d '{
"telematics_unit": {
"id": "38429DA427AB7C25",
"brand": "CLOUDBOXX",
"setup": {
"vehicle_model_id": "01F4XW6QHWKT4HMSFDZ9CCQH1G",
"cloudboxx_installation_configuration": {
"central_lock_connection_type": "PID_LOMO"
}
},
},
"master_data": {
"vin": "R1NBDNB16J1000135",
"license_plate": "RKL-832",
"brand": "Audi",
"model": "A3",
"custom_name": "MyAudiA3",
"fuel_type": "ELECTRIC",
"year_of_production": "2019",
"transmission": "AUTOMATIC",
"vehicle_type": "CAR",
"remark": "Equipped with a CloudBoxx"
},
"custom_fields": {
"seats": "5",
"color": "black"
}
}'
- Don’t forget to fill in your access token.
If the request has been successful, HTTP status code 201 will be returned. 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 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 | |
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 need to change it if you have selected the wrong model during vehicle creation. The Vehicle Lifecycle API provides the PUT /vehicles/:id/telematics-unit/setup endpoint to allow just that. All you need is the ID of the correct vehicle model you would like to use.
Example: Change vehicle model
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)!
- Don’t forget to fill in your access token.
- The body is exactly the same as the object you would use in
telematics_unit.setupwhen creating a vehicle with this model. Hence the name “setup”.
How to remove a vehicle⚓︎
If you want to remove a single vehicle from your fleet, you can use the endpoint DELETE /vehicles/{id} of the Vehicle Lifecycle API (see documentation). Your request will be processed synchronously and the response contains the archived vehicle.
The following example shows the API call to remove a single vehicle:
curl -X DELETE \
https://api.invers.com/vehicles/JQ7RP \
-H 'Authorization: Bearer ❰access_token❱' # (1)!
- Don’t forget to fill in your access token.
If the request has been successful, HTTP status code 200 will be returned. Here is an example of what the response payload might look like:
1 2 3 4 5 6 7 | |
After that, it is still possible to receive information about the archived vehicle via the Vehicle Management API (see documentation). If you do not need the archived vehicle, you can also fully delete it manually. To delete an archived vehicle prematurely, you can use the endpoint DELETE /archived-vehicles/{id}.
Details⚓︎
Telematics units⚓︎
Typically, the telematics manufacturer will give you the ID of the telematics unit that is installed in the vehicle. Depending on the telematics brand, you can conveniently query which telematics units of that brand are available to add to your OneAPI fleet (/telematics-brands/{brand}/available-telematics-units).
Vehicle models⚓︎
In order for the vehicle to behave like the real vehicle, for example like an Audi A3, 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 correct capabilities.
You can view the different vehicle models of a specific telematics brand via GET /telematics-brands/{brand}/available-vehicle-models. Once you have found the right model, you can use its ID in the POST /vehicles request as described above.
Learn more about vehicle models
OEM Credentials⚓︎
The INVERS OneAPI does not only support our own CloudBoxx telematics unit, but also several telematics unit models from other vendors. Those are mostly telematics units that have already been installed into the vehicle by the vehicle’s manufacturer (the OEM).
In order to access those vehicles through the INVERS platform, you will need to add OEM credentials to your OneAPI fleet. See our OEM credentials section for more details.
shared vs. individual credentials
- shared credentials
-
The credentials for vehicles connected through a cloud solution (OEM Integrations) are typically shared by a group of vehicles. We call this kind of credentials shared credentials.
Storing your (shared) credentials for such a third-party API is a necessary step before you can start adding vehicles equipped with those OEM telematics 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.