Battery Health CheckDevelopers
OpenAPI Samples Postman

Dealer group and platform API. For dealer groups using their own tests, and for software that many dealers use. Running a car-listing site? Marketplace API

Platform quickstart: battery health on a vehicle detail page

You build software that many dealers use: a dealer website platform, a DMS or a stock feed. This page takes you from nothing to a battery result on each car’s detail page, for every dealer that connects you, on one credential. Every call is shown; the full detail of each is in the API reference.

The shape of it. One platform credential for your whole product. Each dealer connects you with one click from a button in your software. For each car in a connected dealer’s stock you ask which test speaks for it (current_test), whether its result may be published and in which words (the publish decision), and you re-host the certificate image. Webhooks tell you when anything changes. There is no charge for API access, and nothing to collect from any dealer.

Before you start

1. Get a token

Exchange your client_id and client_secret for a token that lasts an hour. The token is inside the data envelope, like every response. Cache it and reuse it until a few minutes before it expires; the token endpoint allows ten requests a minute.

curl -s -X POST https://api.batteryhealthcheck.co.uk/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$BHC_CLIENT_ID" -d client_secret="$BHC_CLIENT_SECRET" \
  | jq -r '.data.access_token'
import os, time, requests
from urllib.parse import urljoin

API_HOST = "https://api.batteryhealthcheck.co.uk" # a document's or image's path is relative to this (step 7)
API = API_HOST + "/v1"                      # the base URL every call below starts from
_token = {"value": None, "expires": 0}

def token():
    if _token["value"] and time.time() < _token["expires"] - 300:
        return _token["value"]
    r = requests.post(f"{API}/oauth/token", data={
        "grant_type": "client_credentials",
        "client_id": os.environ["BHC_CLIENT_ID"],
        "client_secret": os.environ["BHC_CLIENT_SECRET"],
    }, timeout=15)
    r.raise_for_status()
    data = r.json()["data"]                 # the token is inside "data"
    _token.update(value=data["access_token"],
                  expires=time.time() + data["expires_in"])
    return _token["value"]

def auth():
    return {"Authorization": f"Bearer {token()}"}

def api_get(path, **params):
    r = requests.get(f"{API}{path}", params=params, headers=auth(), timeout=15)
    r.raise_for_status()
    return r.json()

def api_post(path, body):
    r = requests.post(f"{API}{path}", json=body, headers=auth(), timeout=30)
    r.raise_for_status()
    return r.json()

2. Register one webhook

One endpoint, once, for every dealer that will ever connect you. Subscribe to the test events and the connection events:

curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.your-platform.example/bhc",
    "events": ["bhc.test.completed", "bhc.test.failed",
               "bhc.test.warranty_changed",
               "bhc.connection.created", "bhc.connection.updated",
               "bhc.connection.revoked"]
  }'

Store the secret in the response straight away: it is shown once. Then send yourself a ping with POST /v1/webhooks/{id}/test and check that your endpoint verifies its signature (verification, in three languages). A ping is bhc.webhook.test and carries no vehicle data, so it can never be mistaken for a result. It answers 200 with "queued": true as soon as the delivery is queued, not when your endpoint has accepted it, so check your receiver (why the sandbox’s simulate answers 202 instead, and where a failure shows).

3. Put the Connect button in your product

Register the address dealers come back to, then read your Connect link:

curl -X PUT https://api.batteryhealthcheck.co.uk/v1/connect-settings \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "return_urls": ["https://app.your-platform.example/bhc/return"] }'

curl https://api.batteryhealthcheck.co.uk/v1/connect-settings \
  -H "Authorization: Bearer $TOKEN"        # data.connect_url is your Connect link

Inside a dealer’s signed-in account in your product, show a “Connect Battery Health Check” button whose link is connect_url plus two parameters: ref, a random single-use reference you create for this dealer account and store, and return_to, your return URL, percent-encoded.

import secrets
from urllib.parse import quote

def connect_link(account):
    settings = api_get("/connect-settings")["data"]
    if settings["connect_url"] is None:
        return None                           # a sandbox credential: no dealer can connect it (step 11)
    ref = secrets.token_urlsafe(16)           # letters, digits, - and _
    issued_references.save(ref, account, expires_in_hours=24)
    return (settings["connect_url"] + "&ref=" + ref + "&return_to="
            + quote("https://app.your-platform.example/bhc/return", safe=""))

The dealer’s owner or admin clicks it, reads a confirmation page in its own Battery Health Check portal naming your platform and every site the connection covers, and presses Connect. It comes back to your return URL with bhc_status=connected. Treat that as a hint only; the connection itself reaches you in step 4. The button’s HTML, who may connect and the refusal cases are in How a dealer connects you.

4. Map each connection to your dealer

A bhc.connection.created event arrives, and the connection appears in GET /v1/connections:

{
  "dealer_id": 198,
  "name": "Example Motors Group",
  "sites": [
    { "dealer_id": 198, "name": "Example Motors Group", "city": "Leeds", "postcode": "LS1 1AA" },
    { "dealer_id": 247, "name": "Example Motors Leeds", "city": "Leeds", "postcode": "LS11 1AA" }
  ],
  "connected_at": "2026-10-14T09:41:07Z",
  "platform_reference": "c0n-7Hq2xK9vLm4pR8sT"
}
  1. Check the reference. Attach the connection only if platform_reference is a reference you issued in step 3, unused and in date. Anyone can send a dealer a link carrying any ref, so a connection with a reference you did not issue attaches to nothing (why).
  2. Keep the connection’s dealer_id (for a group, its head office). You pass it to the lookup in step 5.
  3. Map each sites[].dealer_id to your own store id. Every test carries the dealer_id of the site that ran it, and a dealer object of {"id", "name"}, so you can route each result to the right store.

5. Look up your stock

For a newly connected dealer, send its stock to POST /v1/tests/lookup, up to 100 cars a call, with the connection’s dealer_id so the answer is that dealer’s alone. Give each car your own reference and, when the advert has one, its mileage in miles: the publish decision then also checks the advert against the reading at the test.

curl -X POST https://api.batteryhealthcheck.co.uk/v1/tests/lookup \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "dealer_id": 198,
    "vehicles": [
      { "ref": "stock-118", "vin": "VF1AG000000000118", "mileage_miles": 18450 },
      { "ref": "stock-119", "vin": "VF1AG000000000119", "mileage_miles": 27300 }
    ]
  }'

Each result, in the order you sent the cars, carries:

FieldWhat it is
current_testThe test that speaks for this car, as GET /v1/tests/{id} returns it: its most recent completed test with a battery-health figure or, when no completed test has one, its most recent test. null when the car has not been tested at that dealer. This is the one to show. A failed or inconclusive retest never replaces a good result here.
latest_testThe car’s newest test, whatever its outcome. Not necessarily the one to show.
current_publishThe publish decision for current_test, made with the mileage you sent: whether its figure and its image may be shown, and the words to use. This is the one to decide from. null exactly when current_test is.
publishThe publish decision for latest_test. The same decision as current_publish when the two tests are the same.
errorWhy this one car was not looked up (a malformed VIN, say). One bad car never fails the call.

6. Decide what to show

Show current_test, under current_publish, the publish decision for that test. It comes with the lookup, so you never need a second call: when current_test is also the latest test (the usual case) it is the same decision as publish, and when a failed or inconclusive retest follows a good result it is the good result’s own decision, not the retest’s.

def battery_for_stock(connection_dealer_id, cars):
    """cars: [{"ref": your stock id, "vin": ..., "mileage_miles": ... or None}],
    at most 100. Returns {ref: (current_test, decision) or None}."""
    vehicles = [{k: v for k, v in car.items() if v is not None} for car in cars]
    body = api_post("/tests/lookup", {"dealer_id": connection_dealer_id,
                                      "vehicles": vehicles})
    out = {}
    for result in body["data"]:
        if result["error"]:
            report_bad_vehicle(result["ref"], result["error"])
            continue
        if result["ambiguous"]:
            out[result["ref"]] = None             # the plate matched more than one car: send the VIN (step 10)
            continue
        current = result["current_test"]
        if current is None:
            out[result["ref"]] = None             # not tested: show your "not yet tested" prompt
            continue
        decision = result["current_publish"]     # current_test's own decision, made with your mileage
        out[result["ref"]] = (current, decision)
    return out
The decision saysShow
publishable: trueThe figure exactly as soh_display gives it, with AVILOO’s grade (band.label, named as AVILOO’s) and tested_on, the advert copy in copy, and the image (step 7).
publishable: false, image.publishable: trueThe image only. No figure, gauge or band of your own: reason says why (a model still in validation, a reading above 100%, a test more than 90 days old and so on).
Both falseNo battery result for this car. statements holds one plain sentence saying why, if you want to tell the dealer.

Read publishable rather than re-deriving it from the test’s fields. The rules behind it are ours to keep right and can tighten without your code changing. Treat a reason you do not recognise as a reason not to publish.

The decision judges the test, not the match. It says whether that test’s result may be shown; whether the test is of the car on your advert is the lookup’s answer. When you look a car up by registration and the result says ambiguous: true, the plate matched tests of more than one car, so current_test may be another car’s. The lookup carries that into both of its decisions: publishable is false and reason is AMBIGUOUS_REGISTRATION, whatever the test itself found. GET /v1/tests/{id}/publish, which names one test by id, never says so, so check ambiguous before you use a decision you fetched yourself. Show nothing for the car until you send the VIN, as the code above does. A lookup by VIN is never ambiguous.

7. The image and the documents

The certificate image is built for a public page: the VIN removed, AVILOO’s certificate number masked, and a QR code to AVILOO’s own validation page. GET /v1/tests/{id}/preview returns a signed link to it that expires in an hour. Download the JPEG once, store it on your own storage or CDN, and serve your copy. Never put the signed link itself on a page.

Fetch it only when the publish decision for the test you show (step 6) says image.publishable: true. The preview call itself does not ask: it serves the image of a test whose decision rules the image out (an inconclusive test, a safety finding, a disputed result), so the decision is the only thing between that image and your page. The decision’s image.path is null in exactly those cases.

def rehost_preview(decision):
    """decision: the publish decision for the test you show (step 6)."""
    image = decision["image"]
    if not image["publishable"]:
        return None                           # this test's image may not go on a page
    if not image["available"]:
        return None                           # not prepared yet: the next sweep picks it up (step 10)
    url = urljoin(API_HOST, image["path"])    # "/v1/tests/{id}/preview": relative to the host
    for _ in range(3):
        r = requests.get(url, headers=auth(), timeout=15)
        if r.status_code == 409:              # our copy is being fetched again; this request started it
            time.sleep(r.json()["error"].get("retry_after_seconds", 30))
            continue
        r.raise_for_status()
        jpeg = requests.get(r.json()["data"]["url"], timeout=30)
        jpeg.raise_for_status()
        return cdn_put(f"bhc/{decision['test_id']}.jpg", jpeg.content, "image/jpeg")
    return None                               # try again on the next sweep

Put on a public page only what clause 5 of the Platform Terms names, re-hosted the same way: the certificate image, the anonymised certificate PDF, and the anonymised warranty PDF and image, all of which hide the VIN. The warranty block’s documents and images lists, and every certificate or warranty response to your platform credential, carry a public_display flag, which is true exactly for these. The flag describes the copy, not the test: it says the VIN is hidden, never that this test’s result may be shown. The certificate image and the anonymised certificate carry the result, so each goes on a page only when the publish decision for the test you show says image.publishable: true.

DocumentPublic pageCall
Certificate image (JPEG)Yes, when the decision’s image.publishable is trueGET /v1/tests/{id}/preview
Anonymised battery warranty (PDF, VIN hidden)YesGET /v1/tests/{id}/warranty?variant=anonymised
Anonymised certificate (PDF, VIN hidden)Yes, when the decision’s image.publishable is trueGET /v1/tests/{id}/certificate?variant=anonymised
Anonymised battery warranty (JPEG, VIN hidden)YesGET /v1/tests/{id}/warranty?format=image&variant=anonymised
Full certificate (PDF) and full warranty (PDF)Never: they show the VINNot served to a platform credential: they carry identifiers reserved for the dealer’s own record, and the dealer’s staff download them from their Battery Health Check portal. ?variant=full answers 403 variant_not_permitted.

Your credential receives no full copy, so the calls above work with or without variant=anonymised: without it each returns the anonymised version and says so ("variant": "anonymised"). Naming the variant, as the code below does, makes the intent plain. In the test object, the full item of each document list reaches you with available: false and withheld_reason: "DEALER_CREDENTIALS_ONLY".

The anonymised certificate carries the same result as the image, so the same gate applies. Fetch it only when the decision for the test you show says image.publishable: true and the test’s certificate_available is true. Like the preview call, GET /v1/tests/{id}/certificate?variant=anonymised does not ask: for a test whose decision rules the image out (an inconclusive test, a safety finding, a disputed result) it still answers 200 with public_display: true, because that flag says only that the VIN is hidden. A 409 means our copy is being prepared; a 404 means none is supplied for this test yet, and we ask again after a day.

def rehost_anonymised_certificate(test, decision):
    """The certificate PDF with the VIN hidden. It carries the same result as
    the preview image, so the same gate, whatever public_display says."""
    if not decision["image"]["publishable"]:
        return None                           # this test's certificate may not go on a page
    if not test["certificate_available"]:
        return None                           # no certificate yet: the next sweep picks it up
    r = requests.get(f"{API}/tests/{test['id']}/certificate?variant=anonymised",
                     headers=auth(), timeout=15)
    if r.status_code in (404, 409):
        return None                           # being prepared, or none supplied yet: the next sweep tries again
    r.raise_for_status()
    pdf = requests.get(r.json()["data"]["url"], timeout=30)
    pdf.raise_for_status()
    return cdn_put(f"bhc/{test['id']}-certificate.pdf", pdf.content, "application/pdf")

Offer the warranty document only when the test has one: current_test.warranty.state is "ACTIVE" and the anonymised item of its documents (the PDF) list has available: true; call that item’s path. The warranty images sit the same way in its images (the JPEG) list. A document’s available says the warranty has one, not that our copy is ready, so a brand-new test’s documents can answer 409 for a few seconds while they are prepared: wait retry_after_seconds and ask again, or leave it to the next sweep, as the code below does.

Every path is relative to the host, https://api.batteryhealthcheck.co.uk, not to the /v1 base URL: it already starts /v1/, for example /v1/tests/48213/warranty?variant=anonymised. Join it with urljoin(API_HOST, path). Appending it to the base URL doubles the /v1 and answers 404. The same goes for the publish decision’s image.path.

def rehost_warranty_copies(test):
    """The anonymised warranty PDF and image of the test you show, re-hosted."""
    warranty = test["warranty"]
    if warranty["state"] != "ACTIVE":
        return {}
    copies = {}
    for item in warranty["documents"] + warranty["images"]:
        if not (item["public_display"] and item["available"]):
            continue                          # the full copies show the VIN: never on a page
        r = requests.get(urljoin(API_HOST, item["path"]), headers=auth(), timeout=15)
        if r.status_code == 409:
            continue                          # being prepared: the next sweep picks it up
        r.raise_for_status()
        signed = r.json()["data"]             # a signed link that expires in an hour, like the preview's
        body = requests.get(signed["url"], timeout=30)
        body.raise_for_status()
        ext = "pdf" if signed["content_type"] == "application/pdf" else "jpg"
        copies[ext] = cdn_put(f"bhc/{test['id']}-warranty.{ext}", body.content,
                              signed["content_type"])
    return copies

8. Render it

<section class="battery-health">
  <h3>Battery Health Check</h3>
  <!-- decision.publishable: the figure exactly as soh_display gives it, with its date -->
  <p class="figure">Battery health 96.4% (AVILOO: Excellent health), tested 21 September 2026</p>
  <!-- optional, also only when decision.publishable: readings from the same test, dated -->
  <p>At the test on 21 September 2026: 13,049 miles on the odometer;
     estimated typical range at that battery health, 182 miles.</p>
  <!-- image.publishable: your own copy of the preview, never the signed link -->
  <img src="https://cdn.your-platform.example/bhc/48213.jpg"
       alt="Battery certificate preview" loading="lazy">
  <!-- also only when image.publishable: your copy of the anonymised certificate -->
  <a href="https://cdn.your-platform.example/bhc/48213-certificate.pdf">Battery certificate (PDF)</a>
</section>

9. Keep it current

  1. On a test event, look the car up again

    bhc.test.completed, bhc.test.failed or bhc.test.warranty_changed names a test in data.test. Verify the signature, return 2xx, then run that car through steps 5 to 7 again rather than showing the event’s test as it stands: a failed retest arrives as an event too, and never replaces a good result. Dedupe deliveries on the webhook-id header.

  2. Every hour, sweep

    Read GET /v1/connections: a new site needs step 5, a dealer no longer listed has disconnected. Then fetch the cars whose current test changed since your last sweep, newest first, following page until meta.has_more is false:

    curl -G https://api.batteryhealthcheck.co.uk/v1/tests \
      --data-urlencode "updated_since=2026-10-14T08:55:00Z" \
      --data-urlencode "current=true" --data-urlencode "per_page=100" \
      -H "Authorization: Bearer $TOKEN"

    current=true keeps only each car’s current test, chosen by the same rule as current_test. With no dealer_id it covers every dealer that has connected you. If you narrow it, note that dealer_id on GET /v1/tests is one site and not its branches, unlike the lookup’s: to list one connection’s tests, call it once for each of the connection’s sites[].dealer_id. Run each car it returns through steps 6 and 7 (its decision is GET /v1/tests/{id}/publish), keyed on the VIN and the dealer. Start each window a few minutes before the previous sweep started, so a test that changed while the last one ran is not missed. The sweep is your safety net for a missed webhook; The hourly sweep has the detail.

  3. Refresh at valid_until

    A publishable decision lapses at valid_until, 90 days after the test. Look the car up again then; if nothing newer exists, the image may stay but the figure goes.

  4. On a disconnect, stop

    bhc.connection.revoked means that dealer’s tests already answer 404 to you. Stop showing its results as live, and delete its data within 30 days (Platform Terms, clause 6). What is already on the dealer’s live adverts is the dealer’s to manage.

10. The awkward cases

You getShow
current_test: nullThe car has not been tested at that dealer: a “not yet tested” prompt, never a figure.
A failed test (status: "failed")Nothing new. A failed test never replaces a result; when it is current_test, the car has no result at all yet.
reason: "NO_RESULT_YET"The test is still running: nothing yet. An event follows when it finishes, whichever way it ends.
reason: "INCONCLUSIVE"At most “battery health could not be determined”. No figure, no image; none will follow for that test.
reason: "PROVISIONAL_OVER_100" or "MODEL_IN_VALIDATION"The image only. The model’s reference data is not final.
reason: "SAFETY_FINDING"Nothing on the advert. Tell the dealer; the finding is in the test’s warnings.
A lookup by registration with ambiguous: trueNothing, until you send the VIN. The plate belonged to more than one car, and both decisions say AMBIGUOUS_REGISTRATION.
No image for a failed or unfinished testA failed test, or one still running, never has an image: its preview_available and certificate_available are false, and asking answers 409 every time. Ask for the image only when the test’s preview_available (the decision’s image.available) is true and the decision’s image.publishable is true, as rehost_preview does. A completed test’s image is prepared automatically once its result arrives, and its updated_at moves when it is, so the sweep picks it up.
409 on an image or document you were told is availableOur stored copy is being fetched again, and your request started it: wait retry_after_seconds and ask once or twice more, or leave it to the next sweep.

Every reason code is listed under the publish decision; what each field means, and when it is null, in the data dictionary.

11. Rehearse it all in the sandbox

A sandbox credential (its client_id starts part_test_) answers every call on this page from fixture cars, on the production base URL, with the header BHC-Environment: sandbox. The one difference: its connect_url is null, because no dealer can connect a sandbox; its fixture connections stand in for step 3.

Sandbox data is invented. Never publish it.

Questions

Do we need a key from each dealer? No. One platform credential for your whole product; each dealer connects you from your button.

Is there a charge? There is no charge for API access: none per call, per credential or per connected dealer.

May we cache and re-host? Yes, and you should: store results and images with your stock records, refresh them as step 9 says, and serve your own copies.

May we use the raw fields in our own design? Yes, for that dealer’s own pages, under the publish decision and the display rules above.

More answers, including rate limits and what happens when a dealer disconnects, are under Questions platforms ask.