The Battery Health Check API for marketplaces

One page, no code. What our data is, what it would add to a listing, and what it takes to put it there. If you are the developer, you probably want the API reference instead.

An electric car’s battery is most of its value, and nobody can see it. A used EV with a healthy pack and one with a tired pack look identical in a photo and identical in a spec table. Buyers know this, which is why they discount every used EV to cover the risk — and why “how is the battery?” is the question your enquiry threads keep filling up with.

Battery Health Check is an independent battery test. A dealer plugs an AVILOO unit into the car, and about three minutes later gets a measured State of Health — a cell-level analysis of the pack’s usable energy, not a reading of what the car reports about itself. The method is certified by TÜV Nord and TÜV Süd, and the certificate is issued by AVILOO GmbH.

This API is how that result reaches a listing. You hold a VIN or a number plate. You ask us about that car. If one of the dealer groups that has authorised you has tested it, you get the measurement and a certificate image to publish — with one credential, whichever of those groups the car belongs to.

What a buyer sees

Two artefacts come out of every completed test, and the split is deliberate.

Alongside them you get the underlying numbers — State of Health, measured capacity, estimated range, cell count and variance, and a full diagnostics block — so you can render the result in your own house style instead of embedding somebody else’s image. The QR code matters either way: a buyer can verify the certificate against AVILOO directly, which is what makes it worth more on your page than a claim from the seller.

How it works

1. A dealer tests a car. Their AVILOO unit runs the test; it takes about three minutes. Nothing is required from you.
2. The result lands with us. AVILOO returns the measurement, we render the certificate and the public preview.
3. You ask about a car you are listing. VIN or registration, one call, searching every dealer group that has authorised you.
4. You publish it. Render the figures or the certificate image on the ad.

If you would rather not wait to be asked, a bhc.test.completed webhook can push each new result to you the moment it lands, signed so you can verify it came from us. That is optional and agreed separately — most integrations start with lookups alone.

What you can and cannot ask

This is the one place where the marketplace API differs from the dealer API, and it is worth being plain about it before your team designs around it.

A lookup with no vehicle in it is refused, and narrowing it to a single dealer does not change that. It is not a rate limit or a tier you can buy up from: a listing-by-listing lookup is the shape of the permission the dealer groups gave, so a browsable copy of their stock is not something we are able to sell.

In practice this costs a marketplace nothing, because you already know which cars you are showing. You ask about the car on the page in front of the buyer.

Whose data it is

The tests belong to the dealers who paid for them. Your credential’s reach is the union of the dealer groups that have authorised sharing with you — each group’s head office plus its branches, current and future, so a group opening a new site next month is covered without anyone reissuing your key.

Each authorisation is recorded against your credential with who gave it and when, and a group can withdraw it at any time. Withdrawal takes effect on the next request, not when your token expires. Outside that set, a test does not return “forbidden” — it returns nothing at all, the same as an id that was never issued.

This is deliberate, and it is usually what makes a dealer group say yes: we can tell them exactly who can see their tests, and switch it off in one click.

What it takes to build

Authentication is standard OAuth 2.0 client credentials. Responses are JSON with a stable shape. An OpenAPI 3.1 specification is published if your team generates clients, and a sample response pack covers the result states you need to handle before you have live credentials.

Publishing a number safely

State of Health should be interpreted together with the result-status fields. An integration should check these before displaying a measured value publicly, because a completed test does not always produce a value that can be published as-is.

• The model is still in validation. AVILOO’s reference data for that model is not final, so the figure can come out above 100%. The test is genuine and the certificate is valid — but “102.9% battery health” on a listing is not a good look.
• The test reached no verdict. AVILOO ran it and could not determine battery health. There will never be a number for that test.
• The result has not landed yet, or the record predates some of what we now capture.

We surface all of this explicitly rather than making you infer it: a result_status field telling you how much weight that test’s figure can carry, and a separate vehicle_supported flag describing the model. They are independent — a model in validation routinely returns a perfectly usable figure, and a fully supported model can still return an inconclusive test. Read both. The reference spells out what to render in each case.

Getting access

Marketplace credentials are issued by us, by agreement — there is no self-serve route, because the credential’s reach is made of other people’s consent. Three steps:

1. Agreement. Scope, the dealer groups in play, and commercial terms, with your account manager.
2. Authorisation. Each dealer group authorises sharing with you. We record it.
3. Issue. We create the credential and send the client_id and client_secret over a channel you nominate. We do not send secrets by email.

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.

Questions we get asked

Is there a sandbox? We do not currently provide a public sandbox. For development, the sample response pack provides a representative set of responses covering successful, provisional and other result states. When an integration is ready for validation, we recommend a pilot using real tests with a participating dealer — it validates the whole workflow, including the parts a sandbox would have faked.

What vehicles are covered? The great majority of EV brands. Coverage is at the model level though, not the brand level — individual models can still be in AVILOO’s validation programme, which is what the vehicle_supported flag tells you on each result.

How do we match a result to our listing? By VIN or by registration — both are searchable, and a lookup by either returns the most recent test. Where you hold both, match on the VIN: registrations transfer between vehicles, and a test recorded without a registration can only be found by VIN.

What if the car has no test? An empty result set, not an error. That is the normal answer for most of your stock, and it is cheap to ask.

Can we cache results? Yes, and you should — a test result does not change once it lands. Cache the test object; do not cache the certificate URLs, which are short-lived signed links and expire in an hour by design.

How fresh is the data? A lookup is live. If you take the optional webhook, it fires as soon as the result lands and the certificate is rendered.

What happens if you change the API? We add fields without notice, so ignore keys you do not recognise. We do not rename or remove them, change types or units, or repurpose status codes. Anything breaking ships on a new version path, never in place.

Who do we talk to? info@batteryhealthcheck.co.uk.