# Fleet Clearance 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. {% hint style="info" %} In order to follow the guide you need to create an account in You can follow along using this doc using our Sandbox instance. {% endhint %} Visit [Console](https://console.high-mobility.com/) 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. ```bash 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](https://docs.high-mobility.com/docs/oauth-2.0) 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. ```bash 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"}] }' ``` {% hint style="info" %} Additional resources: * Check out the [Open API Specification](https://app.gitbook.com/s/GqovsBFw7seb5vTEwucj/fleet-management/fleet-clearance) 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. {% endhint %} 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](https://docs.high-mobility.com/docs/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: ```json { "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: ```bash 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**](https://docs.high-mobility.com/docs/getting-started/activation-process#pending-state) vehicles that still are pending, which changes the state to `canceled`. ```bash 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 ```bash 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. ```bash 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](https://slack.high-mobility.com/) or [get in touch with our support](https://high-mobility.com/support/).