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 groupSoftware 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 dealersA 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 documentationAn 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
- A dealer tests a car. Their AVILOO unit runs the test; it takes about three minutes. Nothing is required from you.
- The result lands with us. AVILOO returns the measurement with its certificate and preview image, and we fetch and store them.
- We push you an event. A
bhc.test.completedwebhook fires with the full result attached, signed so you can verify it came from us. - 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.
| Scope | Typical agency quote | What 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. |
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:
- 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 the result is provisional: publish the preview image only, never the figure (“102.9% battery health”).
- 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.
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 level | Who issues it | What it can do |
|---|---|---|
| Read-only | A dealer, self-serve from its portal | Retrieval 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 integration | A dealer, self-serve | Adds dealer records and webhook management, for that dealer or group. |
| Provisioning | Us, by agreement, to a dealer group | Create branch records and order AVILOO units over the API, for the group’s own sites. |
| Platform | Us, by invitation | One 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. |
| Marketplace | Us, by agreement | One 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.