Battery Health CheckMarketplaces
OpenAPI Samples

Marketplace API. For public car-listing sites that show a battery result on any listing, whichever dealer tested the car. A dealer group, or software many dealers use? Dealer group and platform API

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 brings the AVILOO FLASH Test to dealers. A dealer connects an AVILOO unit to the car, and about three minutes later has the battery’s State of Health, calculated by AVILOO’s own algorithm from data read through the car’s diagnostic port rather than repeated from the figure the car reports about itself. 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 any Battery Health Check dealer has tested it, you get the measurement and a certificate image to publish — one credential, no per-dealer setup, whoever the car belongs to.

What a buyer sees

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

The anonymised certificate (PDF)

State of Health, range, capacity and vehicle details, with the VIN hidden. The full certificate, which shows the VIN and carries identifiers reserved for the dealer’s own record, stays with the dealer: a marketplace credential receives this anonymised version only.

Public-facing certificate image (JPEG)

The same headline result with the VIN removed and AVILOO’s certificate number masked, carrying a QR code that links to AVILOO’s own validation page. This is the one designed to sit on a listing.

Alongside them you get the underlying numbers — State of Health, measured capacity, estimated range, cell voltage spread 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 with its certificate and public preview image, and we fetch and store them.
  3. You ask about a car you are listing. VIN or registration, one call, searching every dealer.
  4. You publish it. Render the figures or the certificate image on the ad.

If you would rather not poll, webhooks can tell you the moment a car you have looked up gets a new test, signed so you can verify it came from us. They are optional and granted 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.

✓ What you can ask

“Here is a VIN — what do you know about this car?”
“Here is a plate — same question.”
“Give me the certificate for the test you just returned.”

✗ What you cannot ask

“List every test this dealer has done.”
“List everything you hold.”
“Give me the dealer’s record.”

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 — it is the reason the credential can reach every dealer in the first place. A browsable copy of the national test record is a different product, and not one we 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.

The tests belong to the dealers who paid for them, and a dealer pays for a test largely so the result can be shown to a buyer. The public preview exists for exactly that: VIN removed, AVILOO’s certificate number masked, a QR code to AVILOO’s own validation page. Putting it on the listing is the intended destination, not a side effect.

What makes reaching every dealer reasonable is that you can only ask about a car you can already name — in practice, one you are already advertising. You are matching a listing to its certificate, not reading a dealer’s book.

We can still narrow a credential to named dealer groups where an agreement calls for it, and we can revoke one outright, with either taking effect on the next request rather than when your token expires.

What it takes to build

ScopeTypical effortWhat it covers
Show results on listings 1–3 days Authenticate, look up a vehicle by VIN or registration, render the figures and the certificate image.
Add live updates +1–2 days Receive and verify webhooks, so new results appear without polling. Optional, agreed separately.

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.

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, to understand the result. Whether a figure may go on the ad is the publish decision’s call (GET /v1/tests/{id}/publish): it reads both fields, also checks for a finding on the test, a newer test of the same car and a test more than 90 days old, and says whether the figure is publishable. Show a figure only when it says so. The reference spells out what each case means.

Getting access

Marketplace credentials are issued by us, by agreement — there is no self-serve route, because the credential reaches every dealer’s tests. Three steps:

  1. Agreement. Scope and terms, with your account manager.
  2. Invite link. We send you a single-use link that expires after 14 days. Nothing exists until you open it.
  3. Mint it yourself. Opening the link creates the credential and shows the client_secret once, in your browser only. It is never sent to you, because we never have it.

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? Sandbox credentials are by invitation: ask us at info@batteryhealthcheck.co.uk. A sandbox credential calls this same base URL and answers from invented fixture data, as a platform connected to fixture dealers rather than with a marketplace credential’s reach, so it shows every response shape and result state but not the marketplace lookup rules. Without one, 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, but not for ever: a test can change after it lands (a registration added later, a warranty changing state) and a newer test of the same car can arrive. Keep the test object keyed on its id and updated_at, look the car up again from time to time while it is listed (or take the webhooks, which tell you when a car you have looked up gets a new test), and replace your copy when either moves. Store the certificate image itself on your own storage; never store or publish the certificate links, which are short-lived signed links that 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.