Fleet Clearance

Manage vehicle data access by adding, approving, or revoking VINs with the Fleet Clearance API

The Fleet Clearance API enables fleet owners and fleet solution providers to manage data access for their vehicles. It offers endpoints to:

• Add vehicle VINs to a production or sandbox application.

• Retrieve a vehicle’s status to check if it has been approved.

• Remove vehicles that are no longer part of the fleet.

In order to follow the guide you need to create an account in https://console.high-mobility.com/

You can follow along using this doc using our Sandbox instance.

Visit Console and create a project, Go to "Car Data" of your project and select properties that you are interested in for each brand. After that go to "API Credentails" and copy your "OAuth Client Credentails" in Sandbox instance to continue the guide.

Getting Access Token

With the app set up, it's time to use the Fleet Clearance API to add a vehicle and to retrieve data from it. To authenticate with any of the endpoints, you first have to create an OAuth2 Access Token.

curl --location 'https://sandbox.api.high-mobility.com/v1/access_tokens' \
--header 'Content-Type: application/json' \
--data '{"client_id": "a92cf969-e8ff-4ad4-a45f-42930edde12d", "client_secret": "xfVxR6xnlbeVHXkQatRx4FmxSJxFR0-M", "grant_type": "client_credentials"}'
{
    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTgwNzAwMDEsImlhdCI6MTY5ODA2OTcwMSwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LmFwaS5oaWdoLW1vYmlsaXR5LmNvbS92MS9hdXRoX3Rva2VucyIsInNjb3BlIjoiZmxlZXQ6Y2xlYXJhbmNlIHZlaGljbGU6ZWxpZ2liaWxpdHktY2hlY2sgdmVoaWNsZTpkYXRhIiwic3ViIjoiMjEwZmMyOTUtZDQ5OS00ZDgwLTk5MWUtZTQ3NTZlZDI3YTZmIiwidmVyIjoxfQ.2neMW6LioKvZYlbSTf-W4GwSHQmMr_8cyXfhyi4XJF-6F4HrvFNIsLlNUa93wp6BiJ_XEythR8DfWh0PrIaHrg",
    "expires_in": 300,
    "scope": "fleet:clearance vehicle:eligibility-check vehicle:data",
    "token_type": "bearer"
}

See the authentication tutorial for OAuth2 Client Credentials to get the full details and integration options.

Getting clearance for a vehicle

Before data can be retrieved for a vehicle, it has to be cleared for access. The clearance procedure is different for each carmaker and should be considered an asynchronous process. It's possible to clear one or many vehicles at the same time, and this is done by passing in the Vehicle Identification Numbers (VINs).

You can use 2HM00000000000001 sandbox virtual VIN in sandbox which emit data every 1 min.

curl --location --request POST 'https://sandbox.api.high-mobility.com/v1/fleets/vehicles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg' \
--data-raw '{"vehicles": [{"vin": "2HM00000000000001", "brand": "sandbox"}] }'

Additional resources:

• Check out the Open API Specification to see the reference of the POST /fleets/vehicles and GET /fleets/vehicles endpoints.

• See the Activation Process guide for a detailed description of what happens under the hood during the clearance.

If you want to cancel the clearance of a vehicle, go ahead and use the DELETE /fleets/vehicles/{vin} endpoint. Similarly to when adding a new vehicle for clearance, this endpoint is asynchronous. Once the request has been processed the vehicle will be set to canceled or revoked depending on if the activation was still pending or not.

Subscribe to the fleet_clearance_changed webhook to receive a notification once the clearance state changes to any of the possible value approved, revoked, rejected, canceled. Read more about the available notifications on the webhooks page.

Reject & Reason

If a vehicle can not be activated the status is set to rejected or kept pending for further retries. Usually this means that the vehicle is not equipped with telematics hardware, however there could be other reasons as well. When we have specific information on why the activation failed we add a reject or pending reason to the clearance object.

Here's an example:

{
  "vin": "VIN0TESTVIN000000",
  "status": "rejected",
  "brand": "volkswagen",
  "changelog": [
    {
      "timestamp": "2025-01-12T09:36:51",
      "status": "pending"
    },
    {
      "timestamp": "2025-01-22T10:42:14",
      "status": "rejected",
      "reason": "privacy mode is enabled"
    }
  ]
}

Using tags

It is possible to store additional metadata together with each individual VIN clearance by using tags. Tags are key/value objects that you can use to store specific information such as:

• Identifiers that reference your internal database records

• Categorisation for your use-cases

• Segmentation for sub-fleets

The following shows an example of how vehicle clearance objects are passed in with a tag set:

curl --location --request POST 'https://sandbox.api.high-mobility.com/v1/fleets/vehicles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg' \
--data-raw '
{
  "vehicles": [
    {
      "vin": "VIN012345678901234",
      "brand": "audi",
      "tags": {
        "vw-group-customer-name": "Car Operations Ltd."
      }
    }
  ]
}
'

Revoking clearance

It's possible to revoke a clearance at any point of time, which stops the data access immediately. This is especially important when a vehicle is being defleeted.

To do this, you just need to use the DELETE /fleets/vehicles/{vin} endpoint, which will update the status to revoking and then to revoked once the deactivation has completed. It's also possible to cancel the clearance procedure for some brands vehicles that still are pending, which changes the state to canceled.

curl --location --request DELETE 'https://api.high-mobility.com/v1/fleets/vehicles/2HM00000000000001' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg'

Sandbox virtual VINs

When you are working with our sandbox API, you can perform the fleet clearance using the VINs of any of your vehicle simulators. The clearance is always approved in a matter of seconds.

To provide additional testing opportunities, the sandbox API also accepts the following virtual VINs. What's special about these VINs is that they have a predetermined behaviour that allow you you to simulate different real-life scenarios. In addition, a virtual VIN may support REST API requests (pull) and streaming (push).

VIN	BRAND	DESCRIPTION
2HM00000000000001	sandbox	Pull enabled, Push every 1 min
2HM00000000000002	sandbox	The clearance never succeeds or fails, stays in a pending state
2HM00000000000003	sandbox	The clearance is rejected after 3 hours

Data delivery

You can start getting vehicle data via Rest-API using vehicle data apo

curl --location 'https://sandbox.api.high-mobility.com/v1/vehicle-data/autoapi-13/2HM00000000000001' \ 
  --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg' \
{
    "brand": "sandbox",
    "diagnostics": {
        "odometer": {
            "data": {
                "unit": "kilometers",
                "value": 2059
            },
            "failure": null,
            "timestamp": "2023-09-22T13:27:26.715Z"
        }
    },
    "vin": "2HM00000000000001"
}

If you have enabaled streaming via the MQTT interface, the data will be put onto the stream automatically upon activation.

mosquitto_sub --disable-clean-session \
  --cafile root.pem \
  --cert certificate.pem.crt \
  --key private.pem.key \ 
  -h mqtt.sandbox.high-mobility.com \
  -p 8883 \
  -q 1 \
  -t 'sandbox/level13/1FBBEDED80595912588FF4FF/#' \
  -i '75374841-d7a5-4db7-b9b5-8a5f60eed79d'

More Information

If you have any questions, please contact us on Slack or get in touch with our support.