Skip to content

Vehicle Commands API⚓︎

Vehicle Commands API

API Reference

API Changelog

The Vehicle Commands API allows you to actively communicate with vehicles by sending commands. The supported commands range from requesting a new vehicle state to unlocking the central lock of a car. The Vehicle Commands API does not allow you to set up or configure vehicles.

Preconditions⚓︎

Before you can send commands to your vehicles using the Vehicle Commands API, you have to add the vehicles to your OneAPI fleet. For detailed information on how to add vehicles to your INVERS OneAPI fleet, see Vehicle Lifecycle API.

Currently you can only add INVERS CloudConnect vehicles which already have a telematics unit built-in ex-factory, e.g. by the vehicle’s OEM or vendor. Soon, you can also add CloudBoxx-equipped vehicles.

Sending commands⚓︎

The Vehicle Commands API is centered around vehicles, not the telematics units built into those vehicles. Consequently, when sending commands to a vehicle, the vehicle is being addressed and identified by its own unique identifier (vehicle_id).

Not every vehicle supports all commands. For example, a car will not be able to unlock its top case, as it usually does not have a top case. A vehicle’s command capabilities tell you which commands it supports. If a vehicle does not have the command capability to execute a specific command, an error (409 Conflict) will be returned each time you send such a command.

If the command has been successful, a JSON object containing the updated vehicle state is returned along with HTTP status code 200. The properties that can be contained in the updated vehicle state depend on the vehicle model and the installed telematics unit. The vehicle’s vehicle state capabilities tell you exactly which properties are available for that particular vehicle.

Example⚓︎

The following example shows how to send the unlock-central-lock command to a vehicle.

curl -X POST \
  'https://api.invers.com/vehicles/❰vehicle_id❱/commands/unlock-central-lock' \ # (1)
  -H 'Authorization: Bearer ❰access_token❱' \ # (2)
  -H 'Content-Type: application/json' -d ''
  1. Just replace ❰vehicle_id❱ with the ID of the vehicle.
  2. Don’t forget to add your valid access token.

If the request has been successful, a JSON object is returned along with HTTP status code 200. The response contains information about the current vehicle state.1

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
{
  "mileage_in_kilometers": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 10000
  },
  "fuel_level_in_percent": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 85
  },
  "remaining_range_in_kilometers": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 35
  },
  "position": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": {
      "lat": 50.834,
      "lon": 8.0219
    }
  },
  "cellular_signal_quality": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": 4
  },
  "driving_enabled": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": true
  },
  "central_lock": {
    "timestamp": "2020-01-30T13:22:05.000Z",
    "value": "UNLOCKED"
  }
}

Error handling and problem types⚓︎

Sending commands via the Vehicle Commands API might sometimes not work as expected. In this case the response contains information that helps you identify the cause of the problem. All error responses contain an error response body with problem type.

In addition to that, the following classification helps you to quickly understand whether the error is caused by:

  • your client’s request
  • an internal problem of the Vehicle Commands API
  • a connectivity issue
  • a third-party (telematics provider) problem

Client errors⚓︎

Sometimes your application gets something wrong. Mostly, these are programming mistakes.

These kind of errors will have a HTTP status code in the 4xx range.

Example

{
  "type": "/problems/vehicle/command-not-supported",
  "title": "The command is not supported by the vehicle.",
  "status": 409,
  "detail": "The command 'unlock central lock' is not supported by the vehicle 'P49FJK'.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}
{
  "type": "/problems/resource-not-found",
  "title": "The resource cannot be found.",
  "status": 404,
  "detail": "The vehicle with ID 'P49FJK' cannot be found.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

Third-party error⚓︎

Problem types

Learn more about problem types in API Basics.

If the vehicle or the API of the vehicle manufacturer returns an error, this results in problem type /problems/third-party/error and HTTP status code 502 .

If this occurs over a longer period of time, we recommend checking the status page or alert newsletter of the telematics manufacturer.

{
  "type": "/problems/third-party/error",
  "title": "An error occurred at a third party API or protocol.",
  "status": 502,
  "detail": "An error occurred at the NIU API.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

Connection error⚓︎

If the communication between the INVERS OneAPI and the vehicle or the vehicle manufacturer’s API could not be established or a timeout occurred, problem type /problems/vehicle/no-connection will be returned along with HTTP status code 504.

{
  "type": "/problems/vehicle/no-connection",
  "title": "No connection to vehicle",
  "status": 504,
  "detail": "The vehicle 'JQ7RP' did not establish a connection.",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

Internal error⚓︎

If an internal error happened within the INVERS OneAPI while processing the command, problem type /problems/internal-server-error will be returned along with HTTP status code 500.

In this case INVERS will automatically be notified about the problem and our development team will start investigating the issue. If such an error persists, you can of course contact support. Make sure to provide the flow_id of your request.

{
  "type": "/problems/internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Internal Server Error",
  "flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}

  1. Depending on the vehicle and the installed telematics unit, the range of information returned in the response may vary. 

Back to top