Fleet Clearance

By using the Fleet Clearance API endpoints, it's possible for fleet operators to activate and deactivate data access to their vehicles. The raw Swagger specification is available at https://github.com/highmobility/open-api-specifications/blob/main/hm-fleet-clearance-v1.yml

Get all clearances

get

https://api.high-mobility.comhttps://sandbox.api.high-mobility.com

/v1/fleets/vehicles

Get the status of VINs that have previously been registered for data access clearance.

Required scopes

This endpoint requires the following scopes:

• : fleet clearance

Authorizations

FleetClearanceAuth

OAuth2clientCredentialsRequired

Token URL:

Query parameters

filterobjectOptional

URL Encoded JSON

Example: {"summary":"Filter by VIN - Equality","value":{"vin":{"operator":"eq","value":"EXVETESTVIN000001"}}}

Responses

200

Success

application/json

vinstringRequired

Vehicle Identification Number (VIN)

statusstring · enumRequiredPossible values:

brandstring · enumOptionalPossible values:

401

When an invalid ServiceAccountToken is used.

application/json

403

When the application doesn't have fleet access.

application/json

429

The client has sent too many requests in a given amount of time. Please wait before retrying. There is no rate limit enforced at this moment for this endpoint, but we reserve the right to enable it if necessary. Please use this API moderately and avoid bursts of calls within a few seconds.

application/json

500

Server Errors

get

/v1/fleets/vehicles

HTTPcURLJavaScriptPython

GET /v1/fleets/vehicles HTTP/1.1
Host: api.high-mobility.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "vin": "VIN0TESTVIN000000",
    "status": "approved",
    "brand": "mercedes-benz",
    "tags": {
      "foo": "bar",
      "bar": "baz"
    },
    "changelog": [
      {
        "timestamp": "2022-03-22T09:36:51",
        "status": "pending"
      },
      {
        "timestamp": "2022-03-22T10:36:51",
        "status": "approved"
      }
    ]
  }
]

Create a clearance

post

https://api.high-mobility.comhttps://sandbox.api.high-mobility.com

/v1/fleets/vehicles

Required scopes

This endpoint requires the following scopes:

• : fleet clearance

Authorizations

FleetClearanceAuth

OAuth2clientCredentialsRequired

Token URL:

Body

application/json

Responses

200

Success

application/json

401

When an invalid ServiceAccountToken is used.

application/json

403

When the application doesn't have fleet access.

application/json

422

Invalid Input. It occurs when the payload is missing a params or the the application is not configured.

application/json

429

The client has sent too many requests in a given amount of time. Please wait before retrying. There is no rate limit enforced at this moment for this endpoint, but we reserve the right to enable it if necessary. Please use this API moderately and avoid bursts of calls within a few seconds.

application/json

500

Server Errors

post

/v1/fleets/vehicles

HTTPcURLJavaScriptPython

POST /v1/fleets/vehicles HTTP/1.1
Host: api.high-mobility.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 259

{
  "vehicles": [
    {
      "vin": "WBADT43452G296403",
      "brand": "mercedes-benz",
      "tags": {}
    },
    {
      "vin": "WBADT43452G296404",
      "brand": "bmw",
      "tags": {}
    },
    {
      "vin": "VIN012345678901234",
      "brand": "ds",
      "tags": {}
    },
    {
      "vin": "VIN01234567890123",
      "brand": "unknown",
      "tags": {
        "foo": "bar",
        "bar": "baz"
      }
    }
  ]
}

{
  "vehicles": [
    {
      "vin": "WBADT43452G296403",
      "status": "pending",
      "tags": {}
    },
    {
      "vin": "WBADT43452G296404",
      "status": "pending",
      "tags": {
        "foo": "bar",
        "bar": "baz"
      }
    },
    {
      "vin": "VIN012345678901234",
      "status": "error",
      "description": "vin should be 17 character(s)"
    },
    {
      "vin": "VIN0123456789012",
      "status": "error",
      "description": "The brand is invalid"
    }
  ]
}

Get clearance for a vin

get

https://api.high-mobility.comhttps://sandbox.api.high-mobility.com

/v1/fleets/vehicles/{vin}

Get the status of a VIN that has previously been registered for data access clearance.

Required scopes

This endpoint requires the following scopes:

• : fleet clearance

Authorizations

FleetClearanceAuth

OAuth2clientCredentialsRequired

Token URL:

Path parameters

vinstringRequired

VIN of the vehicle in question.

Responses

200

Success

application/json

vinstringRequired

Vehicle Identification Number (VIN)

statusstring · enumRequiredPossible values:

brandstring · enumOptionalPossible values:

401

When an invalid ServiceAccountToken is used.

application/json

403

When the application doesn't have fleet access.

application/json

404

Given resource not found

application/json

429

The client has sent too many requests in a given amount of time. Please wait before retrying. This endpoint allows up to 60 calls per minute per application.

application/json

500

Server Errors

get

/v1/fleets/vehicles/{vin}

HTTPcURLJavaScriptPython

GET /v1/fleets/vehicles/{vin} HTTP/1.1
Host: api.high-mobility.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "vin": "text",
  "status": "approved",
  "brand": "bmw",
  "changelog": [
    {
      "timestamp": "text",
      "status": "approved",
      "reason": "text"
    }
  ],
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Delete clearance

delete

https://api.high-mobility.comhttps://sandbox.api.high-mobility.com

/v1/fleets/vehicles/{vin}

Delete the clearance for the given VIN. If the vehicle is in approved state, a revoke is performed. If the clearance is in pending state, the activation process is canceled. The cancelation is currently supported for Mercedes-Benz, Volkswagen, Audi, Skoda, SEAT, CUPRA and the Stellantis brands.

Required scopes

This endpoint requires the following scopes:

• : fleet clearance

Authorizations

FleetClearanceAuth

OAuth2clientCredentialsRequired

Token URL:

Path parameters

vinstringRequired

VIN of the vehicle in question.

Responses

200

Success

application/json

vinstringRequired

Vehicle Identification Number (VIN)

statusstring · enumRequiredPossible values:

401

When an invalid ServiceAccountToken is used.

application/json

403

When the application doesn't have fleet access.

application/json

404

Given resource not found

application/json

409

When deleting a clearance with given VIN is not possible.

application/json

422

When cancellation is not possible at this moment.

application/json

429

The client has sent too many requests in a given amount of time. Please wait before retrying. There is no rate limit enforced at this moment for this endpoint, but we reserve the right to enable it if necessary. Please use this API moderately and avoid bursts of calls within a few seconds.

application/json

500

Server Errors

delete

/v1/fleets/vehicles/{vin}

HTTPcURLJavaScriptPython

DELETE /v1/fleets/vehicles/{vin} HTTP/1.1
Host: api.high-mobility.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "vin": "VIN0TESTVIN000000",
  "status": "revoking",
  "tags": {
    "foo": "bar",
    "bar": "baz"
  }
}

Deprecated

Cancel clearance

post

https://api.high-mobility.comhttps://sandbox.api.high-mobility.com

/v1/fleets/{vin}/cancel_activation

Deprecated: use DELETE /v1/fleet/vehicles/{vin} end point instead

Required scopes

This endpoint requires the following scopes:

• : fleet clearance

Authorizations

FleetClearanceAuth

OAuth2clientCredentialsRequired

Token URL:

Path parameters

vinstringRequired

VIN of the vehicle in question.

Header parameters

AuthorizationstringRequired

Bearer token

Responses

200Success

application/json

vinstringRequired

Vehicle Identification Number (VIN)

statusstring · enumRequired

An access token can be retrieved for the FleetVin if the status is "approved"

Possible values:

descriptionstringOptional

Optional description of the VIN

500

Server Errors

post

/v1/fleets/{vin}/cancel_activation

HTTPcURLJavaScriptPython

POST /v1/fleets/{vin}/cancel_activation HTTP/1.1
Host: api.high-mobility.com
Authorization: text
Accept: */*

{
  "vin": "WBADT43452G296403",
  "status": "pending",
  "tags": {
    "foo": "bar",
    "bar": "baz"
  }
}

Deprecated

Get access token

post

https://api.high-mobility.comhttps://sandbox.api.high-mobility.com

/v1/fleets/access_tokens

Creates an access token for a VIN that has the "approved" state. This access token can be used to retrieve car data through any of the SDKs or the REST API.

Required scopes

This endpoint requires the following scopes:

• : fleet clearance

Authorizations

FleetClearanceAuth

OAuth2clientCredentialsRequired

Token URL:

Responses

200

Success

application/json

Access Tokens

validity_start_datestringOptional

Date and Time in ISO8601 format example: '2018-11-06T10:20:37.094533Z'

validity_end_datestringOptional

Date and Time in ISO8601 format example: '2018-11-06T10:20:37.094533Z'

token_typestringRequired

Token type

scopestringOptional

List of scopes

refresh_tokenstringOptional

Refresh token

expires_inintegerRequired

Expiration time in seconds

access_tokenstringRequired

Access token

400

Error

application/json

401

When an invalid ServiceAccountToken is used.

application/json

403

When the application doesn't have fleet access.

application/json

500

Server Errors

post

/v1/fleets/access_tokens

HTTPcURLJavaScriptPython

POST /v1/fleets/access_tokens HTTP/1.1
Host: api.high-mobility.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "token_type": "bearer",
  "scope": "diagnostics.get.mileage door_locks.get.locks windows.get.windows_positions",
  "refresh_token": "7f7a9be0-04c9-4202-a59f-35d55079b6ba",
  "expires_in": 600,
  "access_token": "a50e89e5-093c-4727-8101-4c6e81addabe"
}