Diagnostic Service

The Diagnostic Service provides vehicle State of Health (SOH) diagnostics for EV batteries. It integrates with the Aviloo provider to assess battery health and returns a battery health score (0–100 %).

info

To activate the diagnostic service for your software, please contact us at https://openhive.eu/contact.

How It Works

Submitting a diagnostic request is asynchronous:

• 1️⃣ Your application submits a POST /api/soh/diagnostics request with the vehicle VIN.
• 2️⃣ The API returns immediately with a diagnostic in state NEW.
• 3️⃣ OpenHive polls the Aviloo provider in the background (every 30 seconds, up to 5 minutes) until the result is available.
• 4️⃣ Once complete, a webhook is sent to the webhookUri configured on your software.

Deduplication

Requests with the same VIN submitted within 5 minutes while a diagnostic is already in progress are deduplicated — the existing diagnostic is returned instead of creating a new one.

Diagnostic States

State	Description
NEW	Request created, waiting for provider processing to start.
PENDING	Diagnostic is being processed by the Aviloo provider.
DONE	Diagnostic completed. Score, PDF and image URLs are available.
ERROR	Diagnostic failed. An errorReason field explains the cause.

Webhooks

When a diagnostic reaches a terminal state (DONE or ERROR), OpenHive sends an HTTP POST to your software's webhookUri.

Successful diagnostic (DONE)

{
  "state": "DONE",
  "vin": "WVWZZZ1JZXW000001",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionId": "a1b2c3d4-e5f6-...",
  "softwareExternalId": "your-internal-id",
  "score": 92.5,
  "pdfUri": "https://...",
  "imageUri": "https://...",
  "reportedAt": "2025-01-02T04:05:06+00:00"
}

Failed diagnostic (ERROR)

{
  "state": "ERROR",
  "vin": "WVWZZZ1JZXW000001",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionId": "a1b2c3d4-e5f6-...",
  "softwareExternalId": "your-internal-id",
  "error": "Vehicle not found in Aviloo database"
}

Integration Steps

• 1️⃣ Get your API credentials from OpenHive
• 2️⃣ Obtain a JWT token from the OpenHive IDP
• 3️⃣ Submit a diagnostic request with the vehicle VIN
• 4️⃣ Receive the result via webhook