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

Battery Health Check — Integration Overview

One page, no code. What our data is, what your users would see, and what it takes to put it in your product. If you are the developer, you probably want the full documentation instead.

Which of these are you?

A dealer group

You run one dealership or a group, and want your own cars’ battery results on your website or in your systems.

One credential from your Battery Health Check portal. It sees your tests, including your branches’.

Integrating as a dealer group

Software that many dealers use

You build a dealer management system, a website builder or a stock feed, and several of your dealers test with Battery Health Check.

One platform credential. Each dealer connects you with one click; you see only the dealers who have.

Building for many dealers

A car-listing site

You run a marketplace where the public browses cars, and want a battery result on any listing, whichever dealer tested the car.

A marketplace credential that looks a car up by VIN or registration. It has its own documentation.

Marketplace documentation

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 on a forecourt and on a listing page. Buyers know this, which is why they discount every used EV to cover the risk.

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.

The Partner API is how that result gets into your product. Once a dealer has tested a car, you can retrieve the result and the certificate against a VIN or a number plate, and we will push you an event the moment a new one lands.

What your users see

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

The full certificate (PDF)

State of Health, range, capacity, vehicle details and the VIN. This is the document for the dealer’s file and for handing to a buyer at the point of sale. It carries identifiers reserved for the dealer’s own record, so only the dealer’s own keys receive it; platforms and marketplaces receive the anonymised version, with the VIN hidden.

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 public 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 your own presentation rather than just embedding an image.

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 preview image, and we fetch and store them.
  3. We push you an event. A bhc.test.completed webhook fires with the full result attached, signed so you can verify it came from us.
  4. You display it. Match the result to your vehicle record — by VIN or by registration — and render the figures or the certificate image on the listing.

If webhooks do not suit your architecture, everything is also retrievable on demand: look up a VIN or a registration and get back the most recent test.

What it takes to build

The figures below are what a specialist web agency might quote for this work — an external team, building manually. They are not our estimate of the work involved, and they are included because they are the numbers most people are working from.

ScopeTypical agency quoteWhat 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 results appear without polling.
Group provisioning 2–3 weeks The above, plus creating branch records and ordering AVILOO units through the API, for a dealer group’s own sites. This needs a dealer-group credential with write:dealers, issued by us; a platform credential cannot create dealers or order units.
What has actually happened. Several dealers have had results and live updates running on the same day they received their credentials, working from this documentation. Others have built the listing integration themselves. The first two rows above are a small piece of work, and it is worth scoping them on that basis rather than on an agency quote.

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 Postman collection holds a ready-made request for every endpoint.

Software for many dealers — a DMS, website builder or advert publisher — builds the first two rows once, on one platform credential, and each dealer connects it with one click from a button in that software. Nothing is collected or configured per dealer. The Platform quickstart walks through the whole job, from the first token to the result on a vehicle detail page; Software for many dealers has the detail.

Using result status when publishing

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

Three cases account for this:

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.

Whether a figure may go on a public page is one call, not something to work out from these fields: the publish decision (GET /v1/tests/{id}/publish) reads both of them, 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, with the wording to use. Show a figure only when it says so; the two fields explain why it does not.

The sandbox has a fixture test for each of these cases. The sample response pack, built from real tests, has the provisional and not-yet-landed cases; it holds no real inconclusive result yet, so that one is described in the reference rather than invented.

Getting access

Which credential you need depends on who you build for. A dealer’s own administrators issue keys for that dealer from its Battery Health Check portal; software serving many dealers holds one platform credential that each dealer connects; a marketplace holds one lookup credential.

Access levelWho issues itWhat it can do
Read-onlyA dealer, self-serve from its portalRetrieval of that dealer’s (or group’s) test results and certificates. No provisioning or ordering permissions. Recommended for a website or listing integration built for one dealer or group.
Full integrationA dealer, self-serveAdds dealer records and webhook management, for that dealer or group.
ProvisioningUs, by agreement, to a dealer groupCreate branch records and order AVILOO units over the API, for the group’s own sites.
PlatformUs, by invitationOne credential for software serving many dealers. Each dealer connects it with one click from a button in your software, and can disconnect at any time; you see the tests, the anonymised certificates and the anonymised warranty documents of connected dealers only, and can be told by webhook when one connects or disconnects. No dealer records, provisioning or ordering. Issued under the Platform Terms. See Software for many dealers.
MarketplaceUs, by agreementOne credential looking up tests and anonymised certificates by VIN or registration across every dealer — for classifieds and aggregation sites. Lookup only: there is no call that lists any dealer's test history, which is what makes that reach reasonable. See Marketplace access.

There is no charge for API access on a platform credential (Platform Terms, clause 11). A dealer’s own keys come from its portal, and marketplace access is agreed with us. Everything else is self-serve — see how to integrate.

Questions we get asked

Is there a sandbox? Yes. A sandbox credential calls the production base URL and behaves as a platform credential connected to fixture dealers, answering from fixture tests: a usable result, a provisional reading, an inconclusive test, a failed one, a retest, and simulated webhook events. Ask us for one; see Sandbox. With it you can try every endpoint in your browser in the API explorer. The sample response pack shows real responses, anonymised. When an integration is ready, we recommend a pilot using real tests with a participating dealer.

Do we need a key from every dealer? Not if you build software for many dealers. You hold one platform credential, with no per-dealer keys to collect, store or rotate: each dealer connects you with one click, and you see only the dealers that have. A dealer group building for itself uses a key it issues from its own portal.

Is there a charge for API access? Not for software serving many dealers. On a platform credential there is no charge for API access: none per call, per credential or per connected dealer (Platform Terms, clause 11). The dealers pay for their battery tests under their own agreements. Any referral arrangement is agreed separately.

Can we cache results and re-host the images? Yes, and you should. Store each result and its certificate image with your own vehicle record, serve your own copy of the image, and refresh them when the test changes (a webhook tells you) rather than calling us on every page view. The links we return for images and documents expire after an hour, so never put one on a page.

Can we use the raw fields in our own design? Yes, for that dealer’s own pages: its stock records, its website and its adverts. Render the figures in your own house style rather than our image if you prefer, under the display rules: show a figure only when the publish decision says it is publishable, use its wording without changing the meaning, and never put the full certificate or full warranty on a public page, because both show the VIN.

What happens when a dealer disconnects? Its tests stop answering to you at once, and you are told by webhook. A platform deletes that dealer’s data within 30 days (Platform Terms, clause 6); what is already on the dealer’s live adverts is the dealer’s to manage.

What are the rate limits? Per credential and per endpoint, counted per minute: every figure, by kind of credential, is in Rate limits. Cache your token for its hour, and look up to 100 cars in one call with the batch lookup.

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 vehicle record? By VIN or by registration — both are searchable, and a lookup by either returns the most recent test. Where you hold both, we recommend matching on the VIN: registrations can be transferred between vehicles, and a test recorded without a registration can only be found by VIN.

Can we pass our own identifiers through? Yes. Dealers, units and tests each carry an internal_reference field which comes back to you unchanged.

How fresh is the data? A webhook 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.