Battery Health Check Marketplace API

You have a VIN or a number plate from a listing. This API tells you whether that car has had an independent AVILOO battery test, what the test measured, and hands you a certificate image you can publish on the ad — across every Battery Health Check dealer, with one credential and no per-dealer setup.

# 1. Get a token (cache for ~55 min)
curl -X POST https://api.batteryhealthcheck.co.uk/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID -d client_secret=YOUR_CLIENT_SECRET

# 2. The car in front of you — by VIN...
curl "https://api.batteryhealthcheck.co.uk/v1/tests?vin=WVWZZZ1KZAW000000&per_page=1" \
  -H "Authorization: Bearer ACCESS_TOKEN"

#    ...or by plate, if that is what your listing carries.
#    Prefer the VIN where you have one — plates transfer between cars.
curl -G "https://api.batteryhealthcheck.co.uk/v1/tests" \
  --data-urlencode "registration=201-D-12345" --data-urlencode "per_page=1" \
  -H "Authorization: Bearer ACCESS_TOKEN"

# 3. Publishable certificate image (VIN removed, expiring link)
curl https://api.batteryhealthcheck.co.uk/v1/tests/TEST_ID/preview \
  -H "Authorization: Bearer ACCESS_TOKEN"

Base URLs

Conventions

• Transport: HTTPS only (TLS 1.2+). All responses are application/json; charset=utf-8.
• Auth: Authorization: Bearer <jwt> on every request except /oauth/token.
• Content-Type: application/json for request bodies (except /oauth/token, which is form-encoded).
• Dates: ISO 8601 with UTC timezone (e.g. 2026-05-27T14:22:08Z).
• Pagination: page-based. Pass ?page=1&per_page=25. per_page is capped at 100. The response meta object carries page, per_page, total, and has_more.
• Idempotency: on POST, send Idempotency-Key: <your-key> to make retries safe. Allowed characters: ASCII alphanumeric, hyphen (-), underscore (_), and dot (.). Max 80 characters. Keys are retained for the lifetime of the resource they idempotently created — there is no purge.
• Nulls: we never drop a key. Anything we don't hold is serialised as null, so the response shape is stable and safe to deserialise into a fixed schema — but you must null-check before rendering. See Nulls & beta vehicles.
• Additive changes: we may add new fields to existing responses without notice. Ignore keys you don't recognise rather than failing on them. Breaking changes ship on a new version path, never in place.
• Correlation: every response includes request_id in meta + X-Request-Id header.
• Scoping: a dealer-group credential is locked to your group's parent company; a marketplace credential looks up one vehicle at a time, by VIN or registration, across every dealer. Either way, there is no call that lists anything you did not name.

Getting access

Marketplace credentials are issued by Battery Health Check by agreement. There is no self-serve route — they reach every dealer, so they are only ever created deliberately, for a named platform, under terms.

Optional, and worth doing: send us the egress IP addresses your servers call from and we will lock the credential to them, so a leaked key is unusable from anywhere else. See IP allow-listing.

Authentication

OAuth 2.0 client-credentials grant. Exchange a long-lived client_id + client_secret pair for a short-lived (1 hour) JWT, then send the JWT as a Bearer token on every other request.

OAuth flow

┌────────────────┐                                  ┌────────────────┐
│                │  1. POST /oauth/token            │                │
│                │  ─────────────────────────────►  │                │
│                │     client_id + client_secret    │                │
│                │     grant_type=client_credentials│                │
│  Partner       │                                  │  BHC API       │
│                │  2. 200 OK                       │                │
│                │  ◄─────────────────────────────  │                │
│                │     { access_token, expires_in } │                │
│                │                                  │                │
│                │  3. GET /dealers                 │                │
│                │  ─────────────────────────────►  │                │
│                │     Authorization: Bearer <jwt>  │                │
│                │                                  │                │
│                │  4. 200 OK + JSON                │                │
│                │  ◄─────────────────────────────  │                │
└────────────────┘                                  └────────────────┘

Machine-to-machine. No user consent screen, no refresh token. Request a fresh token when the current one is about to expire.

Token endpoint

Request

Content-Type: application/x-www-form-urlencoded

curl -X POST https://api.batteryhealthcheck.co.uk/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=part_a1b2c3d4e5f6" \
  -d "client_secret=<your-secret>" \
  -d "scope=read:tests read:certificates write:dealers"

import requests

resp = requests.post(
    "https://api.batteryhealthcheck.co.uk/v1/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "part_a1b2c3d4e5f6",
        "client_secret": SECRET,
        "scope": "read:tests read:certificates write:dealers",
    },
    timeout=10,
)
token = resp.json()["access_token"]

const params = new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "part_a1b2c3d4e5f6",
    client_secret: process.env.BHC_SECRET,
    scope: "read:tests read:certificates write:dealers",
});

const resp = await fetch(
    "https://api.batteryhealthcheck.co.uk/v1/oauth/token",
    { method: "POST", body: params }
);
const { access_token } = await resp.json();

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:tests read:certificates write:dealers"
}

JWT structure

The access_token is a JWT signed with HS256. You don't need to verify the signature yourself — just store and present the token. We verify on our end.

{
  "iss": "bhc-partner-api",
  "aud": "bhc-partner-api",
  "sub": "part_a1b2c3d4e5f6",
  "scope": "read:tests read:certificates write:dealers",
  "parent_company_id": 198,
  "exp": 1748357821,
  "iat": 1748354221,
  "jti": "tok_8a3f4e2b1c5d"
}

Scope catalog

A marketplace credential can hold these and nothing else. The set is enforced when the credential is created, so it cannot be widened by mistake later.

read:dealers and write:dealers are never available to a marketplace credential. The dealer object behind those endpoints carries contacts, addresses, VAT numbers and hardware serial numbers — far more than rendering a certificate on a listing needs. Each test you receive already names its dealer as dealer: {id, name}, which is what a listing actually needs.

Requesting a scope at the token endpoint can only narrow what you hold, never widen it: ask for something you were not granted and it is simply dropped from the token.

Your reach

Your credential has no dealer group of its own and is not tied to a list of them. It answers about any vehicle you can name: give us a VIN or a registration and, if that car has been tested by any Battery Health Check dealer, you get the test and its certificate back.

That is deliberate. You cannot know in advance which dealer holds which car, and you should not have to — you have a listing, we have a test, and the question is only whether they are the same vehicle.

• One credential, every dealer. No per-dealer setup, nothing to add when a dealer joins, nothing to chase when one of your advertisers changes group.
• Naming the car is the price of entry. There is no call that lists tests, and no call that lists dealers. Without a VIN or a registration you get 400 invalid_request; with one for a car we have never tested you get an empty result, not an error. See Every call starts with a VIN or a plate.
• An untested car looks the same as one we don't cover. Both are an empty data array. Treat "no test" as the ordinary case — it will be most of your stock.
• Token shape. Your access token carries "parent_company_id": null and "kind": "marketplace". Treat it as opaque; reach is resolved server-side on every request.

A marketplace credential can also be issued narrowed to named dealer groups instead, if that is what an agreement calls for. Yours is not, unless your account manager has told you otherwise.

Token caching

Tokens are valid for 1 hour. Cache and reuse them — request a fresh one only when the current token is within 5 minutes of expiry. The token endpoint is rate-limited at 10 req/min/credential.

import time, threading, requests
_cache = {"token": None, "expires_at": 0}
_lock = threading.Lock()

def get_access_token():
    now = time.time()
    if _cache["token"] and now < _cache["expires_at"] - 300:
        return _cache["token"]
    with _lock:
        if _cache["token"] and now < _cache["expires_at"] - 300:
            return _cache["token"]
        body = requests.post(TOKEN_URL, data={...}, timeout=10).json()
        _cache["token"] = body["access_token"]
        _cache["expires_at"] = now + body["expires_in"]
        return _cache["token"]

IP allow-listing

A credential can be locked to a set of source addresses. Once an allow-list is set, a request presenting a perfectly valid token from any other address is rejected with 403 ip_not_allowed — so a leaked client_secret is worthless to anyone who cannot also call from your infrastructure.

This is a second, independent factor on top of OAuth and we recommend it for any server-to-server integration. Ask your account manager to set it, and give us the egress addresses your integration calls from. Two things to keep in mind:

• Tell us before your egress addresses change. A NAT gateway replacement or a new region will lock you out at the moment of cutover. We can hold both old and new ranges over a migration.
• It is per credential. If your staging and production environments call from different addresses, use separate credentials rather than one broad allow-list.

If your security team requires certificate-based client authentication specifically, rather than network-level restriction, raise it with your account manager — it is a scoped piece of work rather than something we run today.

Credential rotation and revocation

Credentials do not expire automatically. We recommend rotating annually as routine practice, and immediately on suspected compromise.

Rotation. Issue a second credential alongside the existing one; both remain valid concurrently. Deploy the new credential, confirm it is in use, then revoke the previous one. This allows rotation without downtime.

Revocation. Revocation takes effect immediately for new token requests. An access token already issued remains valid until it expires, so allow up to one hour for existing tokens to lapse. Where a credential is known to be compromised, contact us so the outstanding tokens can be invalidated.

Who performs it. Marketplace credentials are issued by Battery Health Check, so rotation goes through us — ask your account manager and we will issue the replacement before revoking the old one, so you are never without a working key. A revoked credential returns 403 credential_disabled.

Endpoints

Every endpoint requires a Bearer JWT. All requests and responses follow the conventions in the Conventions section.

Every call starts with a VIN or a plate

GET /v1/tests requires vin or registration on a marketplace credential. A request with neither is refused:

# No vehicle identified — refused.
curl "https://api.batteryhealthcheck.co.uk/v1/tests" \
  -H "Authorization: Bearer ACCESS_TOKEN"

HTTP/1.1 400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "This credential looks up one vehicle at a time: supply vin or registration.",
    "request_id": "req_9f2c1a7b3e5d"
  }
}

The other filters narrow a lookup; none of them replaces one:

Everything after the lookup works on a test you have already found: read it, then fetch its publishable image.

Look up tests by VIN or registration

Find tests for a specific vehicle across every Battery Health Check dealer. The primary use case is dealer websites and listing platforms: your inventory page has a VIN or a number plate, you want the most recent battery test for that vehicle to embed on the listing.

Required scope: read:tests

This is the entry point for marketplace credentials, which must supply vin or registration on every call.

Query parameters

Example — by VIN

curl -G https://api.batteryhealthcheck.co.uk/v1/tests \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "vin=VR3UHZKXZNT123456" \
  --data-urlencode "per_page=1"

Example — by registration

curl -G https://api.batteryhealthcheck.co.uk/v1/tests \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "registration=WP72 FKH" \
  --data-urlencode "per_page=1"

Handling more than one result

Both filters return a paginated array, not a single object — ordered newest-first by tested_at. There are three reasons you may get more than one row, and they need different handling:

rows = get("/v1/tests", registration=plate)["data"]
vins = {r["vehicle"]["vin"] for r in rows if r["vehicle"]["vin"]}

if len(vins) > 1:
    # Plate has transferred. Ask for a VIN rather than guessing.
    raise Ambiguous(plate, vins)

An unknown plate or VIN is not an error — it returns 200 with "data": [] and "total": 0. Treat empty as “no test on record”, never as a failure.

Response 200 OK

{
  "data": [
    {
      "id": 9182,
      "internal_reference": "BHC-TEST-009182",
      "dealer_id": 247,
      "unit_id": 412,
      "status": "completed",
      "vehicle": {
        "registration": "AB23 CDE",
        "vin": "VR3UHZKXZNT123456",
        "make": "Peugeot",
        "model": "e-208",
        "year": 2022,
        "mileage_km": 29644
      },
      "battery": {
        "soh_percent": 91.4,
        "capacity_kwh": 45.7,
        "nominal_kwh": 50.0,
        "estimated_range_miles": 195,
        "cell_count": 96,
        "cell_variance": 0.012
      },
      "tested_at": "2026-05-26T14:22:08Z",
      "results_received_at": "2026-05-26T14:25:09Z",
      "result_status": "final",
      "certificate_number": "BHC-CERT-2026-000183",
      "certificate_available": true,
      "preview_available": true,
      "created_at": "2026-05-26T14:22:08Z",
      "updated_at": "2026-05-26T14:25:09Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 1,
    "has_more": false,
    "request_id": "req_91c2d4e6f8a0"
  }
}

Empty data array means no tests exist for that vehicle — either it hasn't been tested, or it was tested at a dealer outside your group.

Get a test

Full JSON for a single test, including all vehicle and battery details.

Required scope: read:tests

The diagnostics block

Every test object — from GET /v1/tests, GET /v1/tests/{id} and the webhook payload alike — carries a diagnostics object alongside vehicle and battery. It is the normalised form of the full AVILOO measurement record: the same data the certificate is generated from, including the per-subsystem check results and the vehicle support flag.

Fields

Example

{
  "data": {
    "id": 9182,
    "status": "completed",
    "vehicle": { "vin": "VR3UHZKXZNT123456", "make": "Peugeot", "model": "e-208" },
    "battery": { "soh_percent": 91.4, "capacity_kwh": 45.7 },
    "vehicle_supported": true,
    "warnings": [],
    "diagnostics": {
      "vehicle_supported": true,
      "overall_battery_status": "OK",
      "battery_checks": {
        "battery_management_system": "OK",
        "battery_sensors": "OK",
        "battery_pack_parameters": "OK",
        "battery_cell_voltages": "OK",
        "vehicle_communication": "OK"
      },
      "sensor_checks": {
        "voltage_sensor": "OK",
        "current_sensor": "OK",
        "temperature_sensors": "OK",
        "cell_voltage_sensors": "OK"
      },
      "energy_kwh": {
        "gross_nominal_new": 50.0,  "gross_current": 45.7,
        "net_nominal_new": 46.3,    "net_current": 42.1,
        "usable_nominal_new": 45.0, "usable_current": 41.0
      },
      "range": {
        "typical_new_miles": 214.0,   "typical_current_miles": 195.4,
        "personal_new_miles": null,   "personal_current_miles": null,
        "wltp_new_km":     { "from": 340.0, "to": 362.0 },
        "wltp_current_km": { "from": 310.8, "to": 330.9 }
      },
      "measurements": {
        "cell_temperature_c": { "min": 17.0, "max": 17.4, "delta": 0.4, "status": "OK" },
        "cell_voltage_v":     { "min": 4.146, "max": 4.159, "delta": 0.013, "status": "OK" },
        "pack_voltage_v": 398.7,
        "average_current_a": 1.2,
        "mileage_km": 29644
      },
      "bms": {
        "soc_percent": 96.0,
        "soh_percent": 92.1,
        "soc_calculation_accuracy": 1.94,
        "soh_calculation_accuracy": 0.95
      }
    }
  }
}

Warnings

Alongside diagnostics, each test object carries a top-level warnings array — the conditions AVILOO flagged while evaluating the test, as enum strings. Where vehicle_supported tells you the model is still in validation, warnings tells you what was unusual about this particular test.

{
  "data": {
    "id": 9182,
    "battery": { "soh_percent": 102.9 },
    "vehicle_supported": false,
    "warnings": ["SOH_GREATER_THAN_100"],
    "diagnostics": { ... }
  }
}

An empty array means AVILOO raised no warnings. null means we hold no evaluation record for the test and therefore can't say either way — treat it as unknown, not as “clean”.

Warning types

A practical use: warnings let you explain an anomalous reading rather than inferring it. An SoH of 102.9% is far more actionable when it arrives with ["SOH_GREATER_THAN_100"] attached.

Can you publish this number? result_status

Every test object carries a top-level result_status. It answers one question directly: how much weight can this test’s numbers carry? If you publish battery data on a public website, this is the first field to branch on — it is cheaper to read than reasoning across status, soh_percent, vehicle_supported and warnings yourself.

The one branch that covers all four

test = get_test(test_id)

match test.get("result_status"):
    case "final":
        # Safe to publish. Still check vehicle_supported — a beta
        # model's derived figures (range, cell count) may be missing.
        render_soh(test["battery"]["soh_percent"])
    case "provisional":
        # Number exists but isn't quotable. Certificate image only.
        render_certificate_image(test)
    case "inconclusive":
        # Finished, no verdict. Never coming. Don't show a spinner.
        render_note("Battery health could not be determined")
    case _:
        # null — still processing, or an old record. Poll or omit.
        render_nothing()

{
  "data": {
    "id": 9184,
    "status": "completed",
    "battery": { "soh_percent": null },
    "result_status": "inconclusive",
    "vehicle_supported": true,
    "warnings": []
  }
}

Nulls & beta vehicles

We never omit keys — a value we don’t have is serialised as null rather than dropped, so the schema is stable. That means every consumer must null-check before rendering. These are the fields that are null often enough to matter in production:

Handling a beta vehicle

A worked example. A Honda e tested in July 2026 returned a state of health of 102.9% with a null estimated range, and warnings: ["SOH_GREATER_THAN_100"] — all artefacts of the model still being in AVILOO validation. The test is genuine and the certificate is valid; what you should not do is publish “102.9% battery health, range unknown” on a listing page without a second thought. Branch on the flag:

test = get_test(test_id)
warnings = test.get("warnings") or []

if test.get("vehicle_supported") is False or "SOH_GREATER_THAN_100" in warnings:
    # Beta model, or an implausible reading. The certificate is valid;
    # the derived figures may not be. Show the image, not your own numbers.
    render_certificate_only(test)
elif test["battery"]["soh_percent"] is not None:
    render_full_summary(test)
else:
    render_nothing()

A simple belt-and-braces check that catches the same class of result without reading either field: treat any soh_percent above 100, or any missing estimated_range_miles, as a signal to fall back to the certificate image rather than your own numeric rendering.

Get the full certificate (PDF) — contains VIN, for records

Returns a 1-hour signed URL for the full multi-page Aviloo PDF certificate.

The PDF prints the full VIN on it. Use it for sales-quality printable copies, customer hand-off, attaching to a vehicle's permanent record, or anywhere only authorised users will see the file. Don't surface this URL on a public web page — use /preview below for that.

Required scope: read:certificates

Response 200 OK — cached

{
  "data": {
    "url": "https://files.batteryhealthcheck.co.uk/certificates/.../X-Amz-Signature=...",
    "expires_at": "2026-05-27T12:47:00Z",
    "content_type": "application/pdf",
    "certificate_number": "BHC-CERT-2026-000183"
  },
  "meta": { "request_id": "req_e2a4f6c8b1d3" }
}

Response 409 Conflict — not cached yet

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "certificate_not_ready",
    "message": "Certificate is not yet available — retry shortly",
    "request_id": "req_e2a4f6c8b1d3",
    "retry_after_seconds": 30
  }
}

Get the public-facing certificate image (JPEG)

Returns a 1-hour signed URL for a JPEG image — the Aviloo-branded “Battery Certificate Preview”.

Single-page summary showing State of Health %, range, vehicle make/model, mileage, test date, and the testing dealer. The VIN is not on the image, and the certificate number is masked (e.g. DD783123-96F3-4F0B-****-************). A QR code on the image links back to Aviloo's hosted validation page.

Designed for public display: embed it directly on car listing pages as an <img>. No personally-identifying vehicle data leaks to the public.

Required scope: read:certificates

Response 200 OK

{
  "data": {
    "url": "https://files.batteryhealthcheck.co.uk/previews/.../X-Amz-Signature=...",
    "expires_at": "2026-05-27T12:47:00Z",
    "content_type": "image/jpeg"
  },
  "meta": { "request_id": "req_f3g5h7i9k1m3" }
}

Manage webhook subscriptions

See Webhooks below for event payloads and signing. The endpoints to manage them:

Required scope: manage:webhooks

curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks/42/test \
  -H "Authorization: Bearer $TOKEN"

What the test event looks like

It is not a synthetic bhc.test.completed. It has its own event type and carries no vehicle or battery data at all, so it can never be mistaken for a real result and published:

{
  "event": "bhc.webhook.test",
  "data": {
    "message": "This is a test event from Battery Health Check. …",
    "test_event": true,
    "endpoint_id": 42,
    "sent_at": "2026-08-17T13:22:14Z",
    "triggered_by": "partner_api"
  }
}

curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.stellantis.example.com/bhc/v1",
    "events": ["bhc.test.completed", "bhc.dealer.activated"]
  }'

The response includes a secret — store it immediately. We can rotate it but never re-display it.

Worked Example

End to end, runnable, in three languages. The responses match what you would see in production.

C. Embedding battery test data on a car listing page

Scenario: Your dealer-website team wants to show battery health on every used-EV listing. A customer browsing a 2022 Peugeot e-208 should see the SoH%, estimated range, and a downloadable certificate without having to call the dealer.

You have the VIN on every listing (from your inventory feed). You don't know which dealer ran the test — could be Manchester, could be any of your branches. The lookup endpoint solves that.

Step 1. Look up the most recent test by VIN

On your listing page's server-side render (or via your inventory backend):

import requests

def get_battery_data_for_vin(vin):
    token = get_access_token()  # cached, see auth section
    resp = requests.get(
        "https://api.batteryhealthcheck.co.uk/v1/tests",
        headers={"Authorization": f"Bearer {token}"},
        params={"vin": vin, "page": 1, "per_page": 1},
        timeout=5,
    )
    data = resp.json()["data"]
    return data[0] if data else None  # None if no test exists

async function getBatteryDataForVin(vin) {
    const token = await getAccessToken();
    const url = new URL("https://api.batteryhealthcheck.co.uk/v1/tests");
    url.searchParams.set("vin", vin);
    url.searchParams.set("page", "1");
    url.searchParams.set("per_page", "1");
    const resp = await fetch(url, {
        headers: { Authorization: `Bearer ${token}` }
    });
    const { data } = await resp.json();
    return data[0] || null;
}

<?php
function get_battery_data_for_vin($vin) {
    $token = get_access_token();
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => "https://api.batteryhealthcheck.co.uk/v1/tests?"
            . http_build_query(["vin" => $vin, "page" => 1, "per_page" => 1]),
        CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $body["data"][0] ?? null;
}

Step 2. Choose how to display it

You now have a test record. Three useful ways to surface it on the listing:

Option A — Show key values as text

Best for clean, brand-consistent listings. Pull the values out of the JSON and write your own HTML — guarding each field, since any of them can legitimately be null (see Nulls & beta vehicles):

<div class="battery-summary">
  <h3>Battery Health Check</h3>
  <dl>
    {% if test.battery.soh_percent %}
    <dt>State of Health</dt>
      <dd>{{ test.battery.soh_percent }}%</dd>
    {% endif %}
    {% if test.battery.estimated_range_miles %}
    <dt>Estimated range</dt>
      <dd>{{ test.battery.estimated_range_miles }} miles</dd>
    {% endif %}
    <dt>Tested</dt>
      <dd>{{ test.tested_at | date }}</dd>
  </dl>
  {% if test.certificate_number %}
  <p class="ref">Certificate: {{ test.certificate_number }}</p>
  {% endif %}
</div>

Option B — Embed the abbreviated certificate (JPEG)

Best when you want the official BHC-branded image on the listing. One additional call:

def get_preview_url(test_id, token):
    resp = requests.get(
        f"https://api.batteryhealthcheck.co.uk/v1/tests/{test_id}/preview",
        headers={"Authorization": f"Bearer {token}"},
        timeout=5,
    )
    return resp.json()["data"]["url"]

Then in the listing template:

<img src="{{ preview_url }}"
     alt="Battery Health Check certificate {{ test.certificate_number }}"
     loading="lazy"
     style="max-width: 400px;">

Option C — Offer the full PDF as a download

Best for “Download full report” buttons. Generate the signed URL on demand when the user clicks:

<!-- Button calls your backend, which then calls BHC -->
<a href="/api/internal/battery-cert/{{ test.id }}">
  Download full battery certificate (PDF)
</a>

Your backend:

@app.route("/api/internal/battery-cert/<int:test_id>")
def proxy_certificate(test_id):
    token = get_access_token()
    resp = requests.get(
        f"https://api.batteryhealthcheck.co.uk/v1/tests/{test_id}/certificate",
        headers={"Authorization": f"Bearer {token}"},
        timeout=5,
    )
    pdf_url = resp.json()["data"]["url"]
    return redirect(pdf_url, code=302)  # short-lived signed URL

Step 3. Handle the “no test exists” case

Not every car on your forecourt has been tested yet. Decide upfront what your listing shows when get_battery_data_for_vin() returns None:

• Hide the battery section entirely
• Show “Battery test scheduled” with the dealer's next available appointment
• Show a generic “Pre-owned EV — Battery Health Check available on request” CTA

Putting it together

A typical render-time flow on a car listing page:

def render_listing(vehicle):
    test = get_battery_data_for_vin(vehicle.vin)

    context = {"vehicle": vehicle, "battery_section": None}

    if test:
        token = get_access_token()
        preview_url = get_preview_url(test["id"], token)
        # Only a "final" result is quotable. "provisional" has a number
        # that isn't safe to headline, "inconclusive" has none at all,
        # null means not answerable yet — all three fall back to the
        # certificate image. Beta models also get image-only treatment.
        quotable = (test.get("result_status") == "final"
                    and test.get("vehicle_supported") is not False
                    and "SOH_GREATER_THAN_100" not in (test.get("warnings") or []))
        context["battery_section"] = {
            "soh_percent": test["battery"]["soh_percent"] if quotable else None,
            "range_miles": test["battery"]["estimated_range_miles"] if quotable else None,
            "tested_at": test["tested_at"],
            "certificate_number": test["certificate_number"],  # may be null
            "preview_url": preview_url,
            "full_cert_link": f"/api/internal/battery-cert/{test['id']}",
        }

    return render("listing.html", **context)

Webhooks

Subscribe to events and we'll push them to your endpoint within seconds. Signed using the Standard Webhooks scheme (HMAC-SHA256, base64-encoded). Failed deliveries are retried with exponential backoff, then auto-disabled if a single endpoint accumulates 50 consecutive failures.

Event catalog (v1)

Event envelope

{
  "event": "bhc.test.completed",
  "data": {
    "test": {
      "id": 9182,
      "internal_reference": "BHC-TEST-009182",
      "dealer_id": 247,
      "unit_id": 412,
      "status": "completed",
      "vehicle": {
        "registration": "AB23 CDE",
        "vin": "VR3UHZKXZNT123456",
        "make": "Peugeot",
        "model": "e-208",
        "year": 2022,
        "mileage_km": 29644
      },
      "battery": {
        "soh_percent": 91.4,
        "capacity_kwh": 45.7,
        "nominal_kwh": 50.0,
        "estimated_range_miles": 195,
        "cell_count": 96,
        "cell_variance": 0.012
      },
      "tested_at": "2026-05-26T14:22:08Z",
      "results_received_at": "2026-05-26T14:25:09Z",
      "certificate_number": "BHC-CERT-2026-000183",
      "certificate_available": true,
      "preview_available": true,
      "dealer": { "id": 247, "name": "Stellantis Manchester (Salford Quays)" },
      "result_status": "final",
      "vehicle_supported": true,
      "warnings": [],
      "diagnostics": { ... full measurement record ... }
    },
    "dealer": { ... full dealer object ... }
  }
}

The test object in the payload is byte-for-byte the same shape returned by GET /v1/tests/{id}, diagnostics and warnings included — so a beta vehicle (vehicle_supported: false) or a flagged reading can be detected at delivery time, without a follow-up call.

The envelope has exactly two top-level keys: event (the event type string) and data (the payload). The unique event identifier for idempotency is delivered in the webhook-id HTTP header — not as a field inside the JSON body. Persist that header value when you record the event, and reject re-deliveries with the same webhook-id.

Signature scheme (Standard Webhooks)

We implement the Standard Webhooks spec. If your stack already has a Stripe/AVILOO/Svix-style verifier, you can reuse it — the on-the-wire format is identical, only the secret needs to change.

Headers we send

How we compute the signature

The secret you receive at registration is base64-encoded behind a whsec_ prefix (e.g. whsec_8f9a3b2c...). Decode the base64 portion to recover the raw 32-byte key, then:

1. Build the signed message: <webhook-id> + "." + <webhook-timestamp> + "." + <raw body bytes>.
2. Compute HMAC-SHA256(decoded_secret, signed_message).
3. Base64-encode the digest (standard alphabet, with padding).
4. Send the header value as v1,<base64>. During secret rotation we send two signatures separated by a space; accept the delivery if any one of them verifies.

Verifying signatures

import base64, hmac, hashlib, time
from flask import request, abort

SECRET = "whsec_8f9a3b2c..."   # exact value from /v1/webhooks creation
TOLERANCE = 300                # 5 min replay window

def _key_bytes(secret):
    if not secret.startswith("whsec_"):
        raise ValueError("secret must start with whsec_")
    return base64.b64decode(secret[len("whsec_"):])

@app.route("/webhooks/bhc", methods=["POST"])
def bhc_webhook():
    msg_id   = request.headers.get("webhook-id", "")
    ts_str   = request.headers.get("webhook-timestamp", "0")
    sig_hdr  = request.headers.get("webhook-signature", "")
    body     = request.get_data()  # RAW bytes — never re-serialise

    try:
        ts = int(ts_str)
    except ValueError:
        abort(400, "bad timestamp")
    if abs(time.time() - ts) > TOLERANCE:
        abort(400, "stale timestamp")

    signed = f"{msg_id}.{ts}.".encode() + body
    expected = "v1," + base64.b64encode(
        hmac.new(_key_bytes(SECRET), signed, hashlib.sha256).digest()
    ).decode()

    # Header may contain multiple space-separated signatures during rotation
    if not any(hmac.compare_digest(expected, part)
               for part in sig_hdr.split(" ")):
        abort(400, "invalid signature")

    event = request.get_json()
    handle_event(msg_id, event)  # idempotent on webhook-id
    return "", 200

const crypto = require("crypto");

const SECRET = "whsec_8f9a3b2c...";
const TOLERANCE = 300;

function keyBytes(secret) {
    if (!secret.startsWith("whsec_")) {
        throw new Error("secret must start with whsec_");
    }
    return Buffer.from(secret.slice("whsec_".length), "base64");
}

app.post("/webhooks/bhc",
    express.raw({ type: "application/json" }),
    (req, res) => {
        const msgId  = req.headers["webhook-id"]        || "";
        const tsStr  = req.headers["webhook-timestamp"] || "0";
        const sigHdr = req.headers["webhook-signature"] || "";
        const body   = req.body;  # Buffer of RAW bytes

        const ts = parseInt(tsStr, 10);
        if (!Number.isFinite(ts) ||
            Math.abs(Date.now()/1000 - ts) > TOLERANCE) {
            return res.status(400).send("stale timestamp");
        }

        const signed = Buffer.concat([
            Buffer.from(`${msgId}.${ts}.`),
            body,
        ]);
        const expected = "v1," + crypto
            .createHmac("sha256", keyBytes(SECRET))
            .update(signed).digest("base64");

        const ok = sigHdr.split(" ").some(part => {
            const a = Buffer.from(expected);
            const b = Buffer.from(part);
            return a.length === b.length && crypto.timingSafeEqual(a, b);
        });
        if (!ok) return res.status(400).send("invalid signature");

        handleEvent(msgId, JSON.parse(body));  # idempotent on webhook-id
        res.status(200).send();
    }
);

<?php
$secret = "whsec_8f9a3b2c...";
$tolerance = 300;

$msgId  = $_SERVER["HTTP_WEBHOOK_ID"]        ?? "";
$tsStr  = $_SERVER["HTTP_WEBHOOK_TIMESTAMP"] ?? "0";
$sigHdr = $_SERVER["HTTP_WEBHOOK_SIGNATURE"] ?? "";
$body   = file_get_contents("php://input");   # RAW bytes

$ts = (int)$tsStr;
if (abs(time() - $ts) > $tolerance) {
    http_response_code(400); exit("stale");
}

if (strpos($secret, "whsec_") !== 0) {
    http_response_code(500); exit("bad secret");
}
$key = base64_decode(substr($secret, strlen("whsec_")));

$signed   = $msgId . "." . $ts . "." . $body;
$expected = "v1," . base64_encode(hash_hmac("sha256", $signed, $key, true));

$ok = false;
foreach (explode(" ", $sigHdr) as $part) {
    if (hash_equals($expected, $part)) { $ok = true; break; }
}
if (!$ok) { http_response_code(400); exit("invalid"); }

handleEvent($msgId, json_decode($body, true));
http_response_code(200);

Retry policy

A single delivery is attempted up to 4 times in total (initial + 3 retries). Backoffs are 60s, 120s, 240s, 480s — only the first three are used by the max-attempts cap. After the final failed attempt the delivery stops retrying. An individual endpoint is auto-disabled after 50 consecutive failures across deliveries. Use POST /v1/webhooks/{id}/replay to retry manually, or contact your account manager.

What counts as success vs failure

Errors

Stable error codes, standard HTTP semantics, and a request ID on every response. Branch on error.code, not on the message.

Error envelope

{
  "error": {
    "code": "invalid_field",
    "message": "primary_contact_email is required",
    "request_id": "req_a9f2e1c4b7d8",
    "field": "primary_contact_email"
  }
}

HTTP status codes

Common error codes

Rate limits

Limits are applied per endpoint group, per credential.

On 429:

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "too_many_requests",
    "message": "Rate limit exceeded. Retry in 23 seconds.",
    "request_id": "req_e9d8c7b6a5f4"
  }
}

Request ID correlation

Every response includes request_id. On success responses it lives inside meta.request_id; on error responses it lives inside error.request_id. The same value is mirrored on the X-Request-Id response header. Log it alongside your own trace IDs and quote it in support tickets — we use it to find your specific request in our logs in seconds.

Retry guidance

Getting support

• Email: info@batteryhealthcheck.co.uk
• Response SLA: 1 business day (Standard)

When reporting an issue include: one or more request_ids from failed calls, your client_id (not your secret), timestamps in UTC, and what you expected vs what happened.