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.
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
- Ask us for a sandbox credential and a platform invite at
info@batteryhealthcheck.co.uk. Build against the sandbox first: it answers every call below from fixture cars, on the same base URL (step 11). The platform invite creates your production credential when you are ready; you accept the Platform Terms on the way. - Have three things ready: a public HTTPS URL for webhooks; the URL in your product a dealer should come back to after connecting you (your return URL); and, optionally, the egress IP addresses your servers call from, so the invite can lock your credential to them (IP allow-listing).
- Keep the secret on your servers. Every call below is server to server. Never put a credential in a browser or an app, and never ask a dealer for its Battery Health Check password or keys.
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"
}
- Check the reference. Attach the connection only if
platform_referenceis a reference you issued in step 3, unused and in date. Anyone can send a dealer a link carrying anyref, so a connection with a reference you did not issue attaches to nothing (why). - Keep the connection’s
dealer_id(for a group, its head office). You pass it to the lookup in step 5. - Map each
sites[].dealer_idto your own store id. Every test carries thedealer_idof the site that ran it, and adealerobject 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:
| Field | What it is |
|---|---|
current_test | The 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_test | The car’s newest test, whatever its outcome. Not necessarily the one to show. |
current_publish | The 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. |
publish | The publish decision for latest_test. The same decision as current_publish when the two tests are the same. |
error | Why 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 says | Show |
|---|---|
publishable: true | The 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: true | The 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 false | No 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.
| Document | Public page | Call |
|---|---|---|
| Certificate image (JPEG) | Yes, when the decision’s image.publishable is true | GET /v1/tests/{id}/preview |
| Anonymised battery warranty (PDF, VIN hidden) | Yes | GET /v1/tests/{id}/warranty?variant=anonymised |
| Anonymised certificate (PDF, VIN hidden) | Yes, when the decision’s image.publishable is true | GET /v1/tests/{id}/certificate?variant=anonymised |
| Anonymised battery warranty (JPEG, VIN hidden) | Yes | GET /v1/tests/{id}/warranty?format=image&variant=anonymised |
| Full certificate (PDF) and full warranty (PDF) | Never: they show the VIN | Not 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>
- Use the words as given.
copy.seller_highlight,copy.attention_grabberandcopy.descriptionfit common advert slots;statementsare plain sentences for a person or an assistant to repeat. Respectmust_not_say: never round the figure, always give the date, and write nothing of your own that it rules out. - Raw fields are yours to present, for that dealer’s own pages. You may render your own gauge from the test’s fields instead of the copy, under the same decision: only when
publishableis true, and never for a car you have not looked up. - Mileage and range, if you show them. For the odometer in miles use
vehicle.odometer.miles;vehicle.mileage_kmis an old name kept for existing integrations and is not the one to show.battery.estimated_range_milesis the test’s estimate of typical range at the battery health it measured, so show it as that, beside the test date, and never as what the car will do:must_not_sayrules out promising a driving range (NO_RANGE_PROMISE). It isnullwhen no trustworthy figure is held; show no range then, and never work one out from the other fields. - No warranty claim of your own on a public page. Every decision’s
must_not_sayrules out claiming or implying a battery warranty and using the AVILOO name or marks, whatever the test’s warranty state. The warranty document itself is a different matter: step 7 says which version, if any, a public page may carry, re-hosted and unaltered. The warranty’sstate, the date inas_ofand itsterms_urlare for the dealer’s own staff, inside your signed-in product. - Outside the UK (for example an Irish dealer),
copyisnullandstatementsis empty, withcopy_withheld_reason: "REGION_NOT_REVIEWED": our English advert wording is not reviewed for that market. The figure and the image are still publishable under the same decision.
9. Keep it current
-
On a test event, look the car up again
bhc.test.completed,bhc.test.failedorbhc.test.warranty_changednames a test indata.test. Verify the signature, return2xx, 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 thewebhook-idheader. -
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, followingpageuntilmeta.has_moreisfalse: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=truekeeps only each car’s current test, chosen by the same rule ascurrent_test. With nodealer_idit covers every dealer that has connected you. If you narrow it, note thatdealer_idonGET /v1/testsis one site and not its branches, unlike the lookup’s: to list one connection’s tests, call it once for each of the connection’ssites[].dealer_id. Run each car it returns through steps 6 and 7 (its decision isGET /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. -
Refresh at
valid_untilA 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. -
On a disconnect, stop
bhc.connection.revokedmeans that dealer’s tests already answer404to 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 get | Show |
|---|---|
current_test: null | The 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: true | Nothing, 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 test | A 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 available | Our 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.
GET /v1/connectionslists the sandbox’s fixture connections. Use theirdealer_idvalues in step 5;990001is a group with a branch.POST /v1/sandbox/simulatesends a real, signed test or connection event to your webhook, so you can rehearse steps 2, 4 and 9. For step 4, send a connection event with aplatform_referenceyou issued in step 3: the delivery carries it in place of the fixture’s own, so your reference check passes (and fails for one you did not issue).- The fixture table lists each fixture car and the case it shows: a usable result, a provisional reading, an inconclusive test, a failed one, a retest and the rest. For step 6, look up
BHCTESTVIN0000048withdealer_id990003(BHC Sandbox Motors South, whose tests they are; under any other fixture dealer the lookup rightly answers “not tested”): its newest test (990000049) is a failed retest, socurrent_test(990000048) differs fromlatest_test, andcurrent_publishis the decision for990000048whilepublishis the failed retest’s. - Try any call in your browser in the API explorer, or import the Postman collection.
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.