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 additonal/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).
Credentials⚓︎
For some of the telematics brands you can use with INVERS OneAPI, an authentication mechanism secures the telematics unit from being used by a malicious person. Usually, this authentication mechanism dictates that certain credentials should be passed along in a certain way in order to communicate with the telematics unit or decode data received from the telematics unit. The manufacturer of the telematics unit or vehicle will provide you with the required credentials or you are able to create and change those on your own (e.g., through the portal of the telematics manufacturer).
The INVERS OneAPI needs to store the credentials in order to communicate with the telematics units built into the vehicles that you plan to connect through OneAPI. 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 (in this case, client_id and client_secret).
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.
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 or the credentials user interface within FleetControl 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 OneAPI fleet.
When storing shared credentials for a third-party API, an ID is generated for them. This ID has to be provided when you add the vehicles associated with those credentials (e.g., via the POST /vehicles endpoint).
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.