Software for many dealers
One credential for your whole platform. Each dealer connects you with one click, from a Connect link in your own software, and from then on its battery test results reach you by webhook and by API — with nothing to collect, store or rotate per dealer.
Who this is for
A platform is software that many dealers use: a dealer-management system, a website builder, a stock publisher feeding adverts. If several of your customers have their cars’ batteries tested with AVILOO, through Battery Health Check or directly with AVILOO, and you want their test results in your product, this page is for you. See who can connect you.
| You are | Use |
|---|---|
| A platform serving many dealers | A platform credential, connected by each dealer. This page. |
| One dealer or one dealer group, or a developer building for one | A key the dealer issues from its own portal. See How to integrate. |
| A marketplace looking up cars across every dealer, connected or not | The Marketplace API. |
The API itself is the same one documented in the API reference: the same token endpoint, the same test object, the same webhook signing. What differs is who decides what you can see. A platform credential starts out seeing nothing at all, and each dealer adds itself by connecting you. Disconnecting is the dealer’s decision too, and takes effect at once.
The build, in order
- Get your platform credential and a token (read
data.access_token). - Register one webhook endpoint for the test and connection events, and register your return URLs.
- Put the Connect button in your software, carrying a reference you can match and a
return_to. - On each new connection, map its sites and backfill their tests.
- Take test events as they come, and run the hourly sweep as the safety net.
- Publish only what may be published: the preview image and the anonymised copies from your own storage, never a full PDF (certificate or warranty). Your credential receives the anonymised certificate and warranty copies only; the full ones are for dealer credentials.
The worked example puts steps 4 to 6 together in Python. For the whole job in one walkthrough, from the first token to the battery result on a vehicle detail page, read the Platform quickstart.
Getting your platform credential
Platform credentials are issued by Battery Health Check. There is no self-serve route, because one credential can come to cover many dealers. Talk to us at info@batteryhealthcheck.co.uk first.
-
We send you an invite link
A single-use link for your named technical contact. It carries no secret, and it expires, so open it when you are ready to build. Nothing exists until you do.
-
Accept the Platform Terms
The page states what will be created, including that the credential sees no dealer until a dealer connects you, and shows the Battery Health Check Platform Terms. You must accept them to create the credential, and we keep a record of who accepted, which version and when. The version in force is the one published on Platform Terms. Its clause 5 is the one that shapes your adverts: you never publish the full certificate PDF or the full warranty PDF, both of which show the VIN; public pages use the preview image, the anonymised certificate PDF, the anonymised warranty PDF or the anonymised warranty image, all of which hide the VIN (see Publishing a result).
-
Copy your secret
Creating the credential shows the
client_secretonce, in your browser. It is never emailed, and we cannot show it again because we store only a one-way hash. Put it straight into your secrets store, on your servers, never in browser or app code.
The terms in force today are published on Platform Terms, word for word as the invite page shows them.
The same page shows your Connect link, the one your dealers click (see How a dealer connects you). It is not secret and does not change. You never need to ask us for it again: GET /v1/connect-settings returns it as connect_url whenever you call it.
A platform credential carries four scopes: read:tests, read:certificates, read:warranties and manage:webhooks. With read:certificates and read:warranties it receives the anonymised certificate and warranty copies only, never the full ones, which are for dealer credentials (see You receive the anonymised copies only). A credential keeps the scopes it was created with: one created before platforms gained read:warranties does not hold it, and receives 403 insufficient_scope from the warranty document. Talk to us if yours is one. Its access token carries "kind": "platform" and "parent_company_id": null; treat the token as opaque, because what it can reach is worked out on every request.
data: read data.access_token), call GET /v1/connections (an empty list), register your webhook endpoint and prove it with POST /v1/webhooks/{id}/test, and build your handling against the sample response pack or, if we have invited you, the sandbox, which can rehearse the connection events. When your first dealer connects, real results start to flow with no change on your side.
Staging. Use a sandbox credential for your test environments rather than a second platform credential: a dealer’s connection belongs to the one credential it connected, so a second platform credential would see nothing until each dealer connected that one too.
Optional and worth doing: send us the egress IP addresses your servers call from before we send your invite, and the link will carry them, so the credential it creates works only from those addresses (see IP allow-listing). A platform secret cannot be changed in place, and a replacement credential starts with no connections, so this is the best protection it has; see Key rotation.
How a dealer connects you
Put your Connect link behind a “Connect Battery Health Check” button in your software, inside the dealer’s signed-in account. Add a reference of your own, and the address to bring the dealer back to:
https://app.batteryhealthcheck.co.uk/dashboard/platforms/connect?p=<your Connect code>&ref=<your reference>&return_to=<your return URL, percent-encoded>
| Parameter | What it is |
|---|---|
p | Your Connect code, exactly as it appears in your Connect link (connect_url from GET /v1/connect-settings). The same for every dealer, and nothing to do with your access token: it only names your platform. It is not your client_id; never put your client_id or secret in a link. |
ref | Optional. Your reference for this connection: letters, digits, full stops, underscores and hyphens, up to 100 characters. We store it with the connection and give it back as platform_reference in GET /v1/connections and the connection events, and as ref on the return link. A link carrying any other characters is refused on the confirmation page. See Matching a connection to your account for what to put in it. |
return_to | Optional. Where to send the dealer afterwards: one of your registered return URLs, or a URL under one. Percent-encode it, as any URL inside a query string must be. |
Keep the whole link short. If the dealer is not signed in to its portal, we ask it to sign in and then take it on to the confirmation page; that works only while the link’s path and query, everything after the host name, stay within 512 characters. A longer link loses its place at sign-in and leaves the dealer on its portal home page.
A Connect button to copy
Plain HTML with inline styles, so it works in any page and loads nothing from us. Replace the three placeholders.
<a href="https://app.batteryhealthcheck.co.uk/dashboard/platforms/connect?p=YOUR_CONNECT_CODE&ref=YOUR_REFERENCE&return_to=https%3A%2F%2Fapp.your-platform.example%2Fbhc%2Freturn"
style="display:inline-block; padding:10px 18px; border-radius:6px;
background:#009DDF; color:#ffffff; text-decoration:none;
font:600 15px/1.2 Arial, Helvetica, sans-serif;">Connect Battery Health Check</a>
It looks like this: Connect Battery Health Check
What the dealer sees
-
It opens the link from your software
The link opens the dealer’s Battery Health Check portal. A dealer that is not signed in first sees a short page naming your platform and saying what connecting does, with a button to sign in that brings it back to the confirmation page.
-
It reads a confirmation page
The page names your platform and lists every site the connection will cover. You will receive the dealer’s test results and certificates; you will not receive its contacts, VAT number, billing or users. Opening the page changes nothing. Its Cancel button takes the dealer back to you when the link carries a registered
return_to. -
It presses Connect
From that moment you can read the dealer’s tests and receive its webhooks, and, if your webhook is subscribed to it, a
bhc.connection.createdevent is on its way to you. With a registeredreturn_tothe dealer goes straight back to it; without one it lands on the page in its own portal that lists its connected platforms.
Who can connect you
- Only a dealer’s owner or admin users. Other portal users cannot open the confirmation page, connect or disconnect anything, and are not sent back to you.
- A group connects once, from its head office. That one connection covers every site in the group, including branches added later.
- Connecting twice is harmless. The existing connection is kept; no second one is made. A dealer that is already connected is told so, with a button back to you when the link carries a registered
return_to. - Any dealer whose AVILOO tests are available to us, including dealers that buy their AVILOO testing directly from AVILOO rather than through Battery Health Check. Those dealers connect with a free connect-only login, which we set up for them: it shows them their connected platforms and their own test results, and nothing else. The page a signed-out dealer sees on following your link tells it how to ask for one.
Some dealers are refused on the confirmation page, which tells them why. With a registered return_to the page offers a button back to you carrying bhc_status=refused; the reason itself is shown only to the dealer. These are the cases, and what to tell the dealer:
| The dealer is | What it needs to do |
|---|---|
| A branch of a group | Ask its head office’s owner or admin to connect you. A head office’s connection covers its branches; a branch cannot connect on its own. |
| A head office whose group view is not switched on yet | Ask Battery Health Check to switch on the group view first. The group view is the head office’s view of all its branches in the portal; until it is on, a head office cannot connect anything that would cover its branches. |
| A closed account | Nothing can be connected. |
Following a link whose ref breaks the character rules | Nothing: the link is wrong. Fix the ref in your software. |
The return link
Register up to five return URLs with PUT /v1/connect-settings. A Connect link’s return_to is followed only when it lies within one of them: the same scheme, host and port, and the same path or a path below it after a / (registered https://app.your-platform.example/bhc/return covers …/bhc/return and …/bhc/return/7, never …/bhc/returned). Its query string may differ, so you can carry your own state in it. Any other return_to is ignored: the dealer is never sent to an address you have not registered, and the page behaves as if there were none.
We send the dealer back to that address with these query parameters added. A bhc_status or bhc_dealer_id already in your URL is replaced, as is a ref when we add one; the rest of your query is kept as it was.
| Parameter | Value |
|---|---|
bhc_status | connected after the dealer pressed Connect, or followed the button on a page saying it was already connected; cancelled after it pressed Cancel; refused after the button on a refusal, or when its Connect was refused. |
bhc_dealer_id | With connected only: the connection’s dealer_id, as in GET /v1/connections. For a group, its head office. |
ref | The ref your Connect link carried, when it carried one. |
https://app.your-platform.example/bhc/return?bhc_status=connected&bhc_dealer_id=198&ref=c0n-7Hq2xK9vLm4pR8sT
Nothing else is added, and never a secret. Treat the return link as a hint about where the dealer has got to, never as proof: anyone can type that URL. Confirm the connection from our side, by the bhc.connection.created event or GET /v1/connections, before you act on it.
Matching a connection to your account
We cannot know which of your accounts a dealer belongs to, and anyone can send a dealer a Connect link carrying any ref. So make the ref something only your own signed-in product could have produced:
- When a signed-in user presses your Connect button, create a random, single-use reference (for example 20 or more letters and digits), store it against that user’s account with a time limit, and put it on the link as
ref. - When a connection arrives with that reference as
platform_reference, in abhc.connection.createdorbhc.connection.updatedevent or inGET /v1/connections, look it up. If you issued it, it is still unused and in date, attach the connection to that account and mark the reference used. - A connection with a reference you did not issue, or with none, attaches to nothing. Show it to your own staff, or ask the dealer to connect again from inside your product.
A dealer that later follows a link with a different reference and confirms it changes platform_reference, and you receive bhc.connection.updated; apply the same check to the new value.
Disconnecting
A dealer disconnects you from the same place in its portal, whenever it chooses, and it takes effect immediately: on your next call its tests return 404 or drop out of lists, it disappears from GET /v1/connections, and webhook deliveries for it stop, including retries already queued. Your access token does not need to expire first. You receive one bhc.connection.revoked event.
ref and return_to. The confirmation page in the dealer’s own portal is the dealer’s instruction to share its results with you. The only other way in is the dealer’s own written instruction to us, naming your platform: our staff then record the connection for it, and it reaches you exactly as one the dealer made itself. Neither can be started from your side.
Connect settings
Platform credentials only (see Software for many dealers). Any other kind of credential receives 404 not_found, as for a path that does not exist. Required scope: manage:webhooks, for both methods.
GET: your settings
Returns your Connect link, so you never need to ask us for it again, and the return URLs a Connect link’s return_to may point at (see The return link).
{
"data": {
"connect_url": "https://app.batteryhealthcheck.co.uk/dashboard/platforms/connect?p=NDI.c2lnbmF0dXJlLWV4YW1wbGU",
"return_urls": [
"https://app.your-platform.example/bhc/return"
],
"updated_at": "2026-10-14T09:12:40Z"
},
"meta": { "request_id": "req_m3n5p7r9t1v3" }
}
| Field | Meaning |
|---|---|
connect_url | Your Connect link. Its p value is your Connect code. Add ref and return_to to it (see How a dealer connects you). null on a sandbox credential, which no dealer can connect. |
return_urls | Your registered return URLs, in the order you sent them. [] until you register one. |
updated_at | When return_urls last changed. null until the first change. |
PUT: replace your return URLs
The body’s return_urls replaces the whole list; [] clears it. Other keys are ignored, so you can send back what GET returned. The response is the same shape as GET. Sending the list you already have changes nothing, and updated_at stays as it was.
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"] }'
Each return URL must be:
- an absolute
https://URL of at most 500 characters, in printable ASCII with no spaces (percent-encode anything else) and no backslash; - without a fragment (
#), credentials (user@) or wildcard (*); - on a public host name, or a public IPv4 address written in full, and not one of Battery Health Check’s own domains;
- free of
.or..path segments and of encoded slashes, backslashes or dots in the path; - different from every other URL in the list.
Up to five. Register the URL your product will receive the dealer on; a return_to below it, or with a different query string, also matches.
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | The body is not a JSON object. |
| 400 | invalid_field | field: "return_urls": the key is missing, is not a list, or lists more than five. field: "return_urls[2]" with index: 2: that entry breaks a rule above, and message says which. |
| 403 | insufficient_scope | The token does not carry manage:webhooks. |
| 404 | not_found | The credential is not a platform credential. |
Rate limits are in Rate limits.
What you can see
Your reach is exactly the sites of the dealers that have connected you, re-checked on every request. Inside them, your credential reads tests the way a dealer’s own key does, except that it receives the anonymised certificate and warranty copies only:
| Call | On a platform credential |
|---|---|
GET /v1/tests | Lists every test at every connected site, newest first. Narrow it with dealer_id (one site), updated_since (new or changed tests), since / until, a VIN (full, or a prefix of 3 or more characters) or registration. |
GET /v1/tests/{id} | Any test at a connected site. |
GET /v1/tests/{id}/previewGET /v1/tests/{id}/certificate | Signed links to the certificate image and the anonymised certificate PDF, with the VIN hidden. The full PDF is for dealer credentials: ?variant=full is 403 variant_not_permitted. See Publishing a result before you use either. |
GET /v1/tests/{id}/warranty | A signed link to the anonymised AVILOO battery warranty document, with the VIN hidden, for a connected dealer’s test that carries one, as a PDF or with ?format=image as an image. The full document is for dealer credentials: ?variant=full is 403 variant_not_permitted. |
GET /v1/connections | The dealers that have connected you, and their sites. Below. |
GET / PUT /v1/connect-settings | Your Connect link and your return URLs. Above. |
/v1/webhooks | One endpoint for every connected dealer. See One webhook endpoint. |
- Never global. A dealer that has not connected you does not exist as far as your credential is concerned. A VIN or registration lookup only searches connected sites, so a car tested elsewhere returns an empty list; its test id returns
404 not_found, exactly like an id that does not exist; anddealer_idfor an unconnected site is404too. - With no connections you see nothing. Every list is empty and every test id is
404. That is the normal state of a new credential, not an error. - Every test names its site. Each test carries
dealer_idand adealerobject of{"id", "name"}, so you never need a second call to say who tested the car. - No dealer records.
/v1/dealersis not available to a platform credential (403 insufficient_scope), and nor is anything that creates dealers or orders test units. Site names, towns and postcodes come fromGET /v1/connections. - Join on the VIN. Search by VIN or by registration, but match a test to your stock record on
vehicle.vin. Plates move between vehicles; VINs do not, and a test recorded without a plate can only be found by VIN.
Field-by-field detail for the test object is in the API reference and the data dictionary.
List the dealers connected to you
Platform credentials only (see Software for many dealers). Every dealer that has connected your platform, oldest connection first, with every site each connection covers. This is your whole reach: the tests and webhooks you receive come from these sites and no others. A dealer that disconnects is gone from the next response.
Required scope: read:tests. Any other kind of credential receives 404 not_found.
Query parameters
| Param | Type | Description |
|---|---|---|
page | integer | 1-based page number. Default 1. |
per_page | integer | 1–100. Default 25. |
Response 200 OK
{
"data": [
{
"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": "dlr-10442"
},
{
"dealer_id": 312,
"name": "Example EV Centre",
"sites": [
{ "dealer_id": 312, "name": "Example EV Centre",
"city": "Cardiff", "postcode": "CF10 1AA" }
],
"connected_at": "2026-10-15T15:02:51Z",
"platform_reference": null
}
],
"meta": { "page": 1, "per_page": 25, "total": 2, "has_more": false,
"request_id": "req_k2m4n6p8r0t2" }
}
| Field | Meaning |
|---|---|
dealer_id, name | The dealer that connected you. For a group, its head office. |
sites | Every site the connection covers: the dealer itself first, then each of its branches. A branch the group adds later appears here and is covered without the dealer connecting again. Each sites[].dealer_id is the value you will see as dealer_id on that site’s tests and webhooks. |
sites[].city, sites[].postcode | Town and postcode of the site’s operational address, or of its registered address where we hold no operational one, to help you match our sites to yours. Either can be null. |
connected_at | When the dealer connected you. |
platform_reference | The ref your Connect link carried, unchanged; null when the link had none. Whoever sent the dealer the link chose it, so check it against the references you issued before you attach the connection to one of your accounts: see Matching a connection to your account. If the dealer later follows a link carrying a different ref and confirms it, this field changes to the new value. |
Nothing else about the dealer is returned: no contacts, VAT number, street address, billing or test units. Each item is exactly the data of the connection events, which tell you of a change as it happens. Read the list when your service starts and again at the start of each hourly sweep as well, because a webhook can be missed: new entries are dealers to backfill, and missing ones have disconnected. There is no need to poll it more often than that; its limit is in Rate limits.
One webhook endpoint for every dealer
Register one endpoint, once, for the test events and the connection events. Every connected dealer’s results arrive there, including dealers that connect after you registered it; you never register per dealer.
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 from the response immediately; it is shown once. Then prove the endpoint with POST /v1/webhooks/{id}/test. bhc.dealer.activated is not available to a platform credential and is refused with 422. Signing, verification, the URL rules and the retry schedule are exactly as in the API reference.
| Event | Sent when |
|---|---|
bhc.test.completed | A connected dealer’s test result lands. data.test is the test object. |
bhc.test.failed | A test could not complete. |
bhc.test.warranty_changed | The AVILOO battery warranty on a test you already have moved to a new state. Refetch the test, and its warranty document if you offer it. |
bhc.connection.created | A dealer connected you. |
bhc.connection.updated | A connected dealer followed a link carrying a different ref and confirmed it, so its platform_reference changed. |
bhc.connection.revoked | The connection ended: the dealer disconnected you, or Battery Health Check ended it on the dealer’s instruction. Sent once. |
The connection events
Platform credentials only (and the sandbox, which can simulate them), and only about your own connections: a dealer-group or marketplace credential is refused with 422 if it tries to subscribe, and no other credential connected to the same dealer ever receives yours. Each event’s data is exactly that connection as GET /v1/connections lists it; bhc.connection.revoked adds revoked_at. They are signed, retried and replayable like every other event.
{
"event": "bhc.connection.created",
"data": {
"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"
}
}
{
"event": "bhc.connection.revoked",
"data": {
"dealer_id": 198,
"name": "Example Motors Group",
"sites": [ … as above … ],
"connected_at": "2026-10-14T09:41:07Z",
"platform_reference": "c0n-7Hq2xK9vLm4pR8sT",
"revoked_at": "2026-11-02T16:20:44Z"
}
}
- Nothing is sent for nothing. A refused connect, or a dealer connecting again with no change, sends no event.
- Created and updated stop at the disconnect. A
bhc.connection.createdor.updateddelivery still waiting to be retried when the dealer disconnects is not sent;bhc.connection.revokedalways is. - On
bhc.connection.created, match the connection to your account (see Matching a connection to your account) and backfill its sites’ history withGET /v1/tests?dealer_id=<site>. - On
bhc.connection.revoked, stop showing that dealer’s results as live. Its tests already return404to you. - Still run the hourly sweep. The events are the fast path;
GET /v1/connectionsis the record.
Routing a test to the right dealer
Route on data.test.dealer_id: the site that ran the test. Look it up among the sites of your connections to find the connection, and from the account you matched it to, your own dealer record. The same site also appears as data.test.dealer and data.dealer, both {"id", "name"}.
Expect the same test more than once
- Dedupe each delivery on its
webhook-idheader. A retry of a delivery carries the samewebhook-id; record it and acknowledge repeats without processing them again. - Treat the test as an upsert keyed on
data.test.id. The same test can be delivered more than once, each time as a new delivery with its ownwebhook-id, and a later delivery can carry newer data. Keep the copy with the latestupdated_at, and never create a second record for the same test id. - Respond fast. Verify the signature, queue the work, return
2xx. Fetch images and update stock records afterwards, not inside the request.
Certificates that are not ready yet
GET /v1/tests/{id}/preview and /certificate can return 409 (preview_not_ready or certificate_not_ready) for a test whose image has not been rendered yet. Your request starts the rendering. Wait for the retry_after_seconds in the error body, about 30 seconds, and ask again; do not treat it as a failure, and do not retry in a tight loop.
This is common on the first delivery of a brand-new test, which can arrive before the image is ready: preview_available and certificate_available in that payload may still be false. Ask for the image anyway, rather than waiting for a later delivery to say it is there.
The hourly sweep
Webhooks are the fast path, not the only one. Your endpoint will be down at some point, a delivery can exhaust its retries, and a dealer that connects you today has a history no webhook will ever send. Run a sweep every hour so that nothing depends on a single delivery:
-
Read your connections
GET /v1/connections. For any site (sites[].dealer_id) you have not seen before — a newly connected dealer, or a branch added to one later — backfill it: page throughGET /v1/tests?dealer_id=<site>¤t=true&per_page=100, each car’s current test at that site. A dealer that is no longer listed has disconnected you. -
Fetch everything that changed since the last sweep
GET /v1/tests?updated_since=<start of your last sweep, minus a few minutes>¤t=true&per_page=100, followingpageuntilmeta.has_moreisfalse.updated_sincereturns tests that are new or changed since that instant: a result that landed late, a registration resolved after the test, a warranty that changed.current=truekeeps only each car’s current test, the one to show, so a failed retest never displaces a good result. -
Upsert every test on its id
The same handling as a webhook delivery: one record per
test.id, keeping the copy with the latestupdated_at. Most of what the sweep returns you will already hold, and that is the point.
updated_since, not since. since filters on tested_at, the time the car was tested, and the result lands with us some minutes later. A window on tested_at that started where the last one ended would miss a test performed just before your previous sweep whose result had not landed by then. updated_since keys on when we last changed the record instead. Start each window a few minutes before the time you started the previous sweep, not when it finished, and upsert on the test id so the overlap costs nothing.
from datetime import timedelta
def hourly_sweep():
started = now_utc()
window = last_sweep_started() - timedelta(minutes=5) # a small overlap
refresh_connections() # backfills new sites
page = 1
while True:
body = api_get("/tests",
updated_since=window.strftime("%Y-%m-%dT%H:%M:%SZ"),
current="true", page=page, per_page=100)
for test in body["data"]:
apply_test(test, current=True) # same upsert as the webhook path
if not body["meta"]["has_more"]:
break
page += 1
record_sweep_started(started)
api_get, refresh_connections and apply_test are in the worked example below.
Publishing a result
Your dealers will put these results on public adverts, so the rules that matter most are about what reaches a buyer.
Re-host the preview image
GET /v1/tests/{id}/preview returns a signed link to the public certificate image: a JPEG with the VIN removed and AVILOO’s certificate number masked, and a QR code to AVILOO’s own validation page. It is the one built for an advert. The link expires after an hour, so download the image straight away, store it on your own storage or CDN, and serve it from there. Never put the signed link itself on a page, and never store it for later.
You receive the anonymised copies only
Every certificate and every AVILOO battery warranty exists in two versions: the full one, which shows the VIN and carries identifiers reserved for the dealer’s own record, and the anonymised one, which hides the VIN. A platform credential receives only the anonymised version of each:
| Document | What your credential gets |
|---|---|
| Certificate PDF | GET /v1/tests/{id}/certificate, with or without ?variant=anonymised: the anonymised certificate. |
| Warranty PDF | GET /v1/tests/{id}/warranty, with or without ?variant=anonymised: the anonymised warranty. |
| Warranty image (JPEG) | GET /v1/tests/{id}/warranty?format=image, with or without &variant=anonymised: the anonymised image. |
Any of them with ?variant=full | 403 variant_not_permitted. No scope changes this. |
Every one of those responses carries "variant": "anonymised" and "public_display": true, so your code can check what it received. On the test object, certificate_documents, warranty.documents and warranty.images still list both versions, full first, so their shape is the same for every credential; to you the full item of the first two is available: false, with path null and withheld_reason: "DEALER_CREDENTIALS_ONLY". The full image is served to no credential, dealers included, so its warranty.images item is unavailable to everyone, with withheld_reason null. A battery reading’s documents lists only the anonymised kinds. The dealer’s own staff download the full versions from their Battery Health Check portal, so there is nothing for your product to offer them there.
Publishing the anonymised copies
The anonymised certificate may go on a public page, re-hosted like the preview image and under the same rule: only when the publish decision for that test says image.publishable: true (below). Its public_display: true says the VIN is hidden, not that this test’s result may be shown: the endpoint serves it for an inconclusive test, a safety finding or a disputed result too. The anonymised warranty PDF and image may go on an advert too; the image suits a listing. As with the preview image, download each one and serve your own copy; never put the signed link on a page.
The same goes for the test passport, GET /v1/tests/{id}/passport: it carries the VIN and is for your own systems. Only its publish block is written for public display.
Never publish the full PDF, certificate or warranty, even a copy a dealer sends you some other way. That is clause 5 of the Platform Terms: you never publish the full certificate PDF or the full warranty PDF, both of which show the VIN, and public pages use the preview image, the anonymised certificate PDF, the anonymised warranty PDF or the anonymised warranty image, all of which hide the VIN.
Decide what to show: the publish decision
GET /v1/tests/{id}/publish is Battery Health Check’s own publish decision for a test. It reads result_status and vehicle_supported, also checks for a newer test of the same car, a finding on the test and a test more than 90 days old, and returns the advert copy and plain sentences to use. Show what it allows, and nothing more:
| 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, and the preview image and anonymised certificate. |
publishable: false, image.publishable: true | The preview image and anonymised certificate only. No figure, gauge or band of your own: reason says why. |
| Both false | No battery result for this car: neither the preview image nor the anonymised certificate. |
Read its publishable rather than deciding from the test’s fields yourself: the rules behind it can tighten without your code changing. Treat a reason you do not recognise as a reason not to publish.
What the status fields tell you
They explain the publish decision; neither is permission to publish. result_status describes this test’s result: "final" is a usable figure, which the decision can still refuse; "provisional" is a figure not safe to quote, so at most the image; "inconclusive" has no figure and never will, so at most “battery health could not be determined”; null means nothing yet, and never means "final". vehicle_supported describes the model; read both, because neither stands in for the other. The full reasoning is in Can you publish this number? and Nulls & beta vehicles.
A car can be tested more than once, and the newest test is not always the one to show: a failed or inconclusive retest never replaces a good result. Ask us which test speaks for the car rather than choosing by date: current_test on each batch lookup result, GET /v1/tests?vin=…¤t=true, or the current_test_id of the publish decision above, which all follow the same rule.
Worked example: from a new test to a stock record
A dealer you serve tests a car on its forecourt. A few minutes later the result is on that car’s stock record in your system, with the certificate image ready for its advert. Python, using requests; the storage calls (seen_before, find_stock, cdn_put and so on) stand for your own.
1. Know which of your dealers each site belongs to
import time
import requests
API = "https://api.batteryhealthcheck.co.uk/v1"
def auth():
# token() is your cached access token: one POST /v1/oauth/token an hour
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()
def refresh_connections():
"""Map every BHC site to your own dealer, and backfill new sites."""
sites, page = {}, 1
while True:
body = api_get("/connections", page=page, per_page=100)
for conn in body["data"]:
your_dealer = match_connection(conn) # see "Matching a connection"
if your_dealer is None:
continue # not one of your references
new_sites = [s for s in conn["sites"]
if s["dealer_id"] not in known_sites()]
for site in conn["sites"]:
sites[site["dealer_id"]] = (your_dealer, conn["dealer_id"])
backfill(new_sites) # a branch added later needs its history too
if not body["meta"]["has_more"]:
break
page += 1
save_site_map(sites) # sites missing from it have disconnected
def backfill(sites):
for site in sites:
page = 1
while True:
body = api_get("/tests", dealer_id=site["dealer_id"],
current="true", page=page, per_page=100)
for test in body["data"]:
apply_test(test, current=True) # each car's current test
if not body["meta"]["has_more"]:
break
page += 1
2. Take the webhook, and get out of the way
This is the handle_event the signature verification example calls once the signature checks out.
TEST_EVENTS = ("bhc.test.completed", "bhc.test.failed",
"bhc.test.warranty_changed")
CONNECTION_EVENTS = ("bhc.connection.created", "bhc.connection.updated",
"bhc.connection.revoked")
def handle_event(msg_id, event):
if seen_before(msg_id): # a retry of a delivery you already took
return
remember(msg_id)
if event["event"] in TEST_EVENTS:
enqueue(apply_test, event["data"]["test"]) # return 2xx now; work later
elif event["event"] in CONNECTION_EVENTS:
enqueue(refresh_connections) # maps, backfills or drops the dealer
# anything else (bhc.webhook.test, a type you don't know): ignore it
def match_connection(conn):
# Your dealer for this connection, or None. The reference must be one
# your own signed-in product issued, unused and in date, or already
# bound to this connection (see "Matching a connection").
ref = conn["platform_reference"]
account = issued_references.claim(ref, conn["dealer_id"]) if ref else None
return account.dealer if account else None
3. Upsert the result onto the stock record
def apply_test(test, current=False):
mapped = load_site_map().get(test["dealer_id"])
if mapped is None:
return # not a site you map (yet)
your_dealer, connection_id = mapped
stock = find_stock(your_dealer, vin=test["vehicle"]["vin"]) # join on the VIN
if stock is None:
return
decision = None
if not current:
# A webhook names the test that changed, which is not always the one
# to show: a failed or inconclusive retest never replaces a good result.
test, decision = current_test(connection_id, test["vehicle"]["vin"])
if test is None or test["status"] != "completed":
return # no result to show yet
if decision is None:
decision = api_get(f"/tests/{test['id']}/publish")["data"]
# What may be shown is the publish decision's call, never your own reading
# of the test's fields: it also weighs findings on the test, its age and
# newer tests of the car, and it can tighten without your code changing.
image = None
if decision["image"]["publishable"]:
held = stock.bhc_test # what you stored last time, if anything
if held and held["id"] == test["id"] and held["updated_at"] >= test["updated_at"]:
image = stock.battery_image # the same test, no newer: keep your copy
else:
image = rehost_preview(test["id"])
if image is None:
retry_image_later(test["id"]) # not rendered yet; updated_since will not resend it
return
publishable = decision["publishable"]
stock.bhc_test = test
stock.battery_figure = decision["soh_display"] if publishable else None # exactly as given
stock.battery_band = decision["band"]["label"] if publishable else None
stock.battery_tested_on = decision["tested_on"]
stock.battery_note = ("Battery health could not be determined"
if "INCONCLUSIVE" in decision["reasons"] else None)
stock.battery_image = image
stock.recheck_at = decision["valid_until"] # the figure lapses then: apply_test again
stock.save()
def current_test(connection_id, vin):
# The lookup answers for that dealer and its branches only. Its
# current_publish is the current test's own decision (its publish is
# latest_test's), so apply_test needs no second call.
body = api_post("/tests/lookup", {"dealer_id": connection_id,
"vehicles": [{"vin": vin}]})
result = body["data"][0]
return result["current_test"], result["current_publish"]
4. Re-host the preview image
def rehost_preview(test_id):
for _ in range(5):
r = requests.get(f"{API}/tests/{test_id}/preview", headers=auth(),
timeout=15)
if r.status_code == 409: # not rendered yet; this request started it
time.sleep(r.json()["error"].get("retry_after_seconds", 30))
continue
r.raise_for_status()
image = requests.get(r.json()["data"]["url"], timeout=30) # expires in an hour
image.raise_for_status()
return cdn_put(f"bhc/{test_id}.jpg", image.content, "image/jpeg")
return None # the next hourly sweep tries again
Run the hourly sweep alongside this, calling the same apply_test, and a missed webhook costs at most an hour.
Questions platforms ask
Do we need credentials for each dealer? No. You hold one platform credential for your whole product, with no per-dealer keys to collect, store or rotate. Each dealer connects you with one click from a button in your software (How a dealer connects you), and from then on its results reach you on that same credential. A dealer group adding a branch needs nothing from you either: the group’s connection covers it.
Is there a charge for API access? No. 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.
May we cache the data and re-host the images? Yes, and you should. Keep each result with your stock record and refresh it when a webhook or the hourly sweep says it changed, rather than calling us on every page view. Download the certificate image and any anonymised document once, store it on your own storage or CDN, and serve your copy: the signed links we return expire after an hour, so never put one on a page.
May we use the raw fields in our own front end? Yes, for that dealer’s own pages: its stock records, its website and its adverts (Platform Terms, clauses 2 and 3). Present the figures in your own design if you prefer, under the display rules in Publishing a result: show a figure only when the publish decision says it is publishable, use its wording without changing the meaning, and put no full certificate or full warranty on a public page.
Can a dealer connect us without the button? Yes, on its own written instruction to us at info@batteryhealthcheck.co.uk, naming your platform: for example when nobody at the dealer holds an owner or admin login. Our staff record the connection on its behalf, noting who gave the instruction, how and when. It reaches you as any other connection does: a bhc.connection.created event and an entry in GET /v1/connections, and the dealer can disconnect you in the usual way. No link carried a reference, so its platform_reference is null: attach it to the right account by hand (Matching a connection), or ask the dealer to press your button once, which sets the reference and sends you bhc.connection.updated. We act only on the dealer’s instruction, never on a platform’s request.
Do we receive the full certificate and warranty documents? No. A platform credential receives the anonymised certificate PDF and the anonymised warranty PDF and image, all with the VIN hidden. The full versions carry identifiers reserved for the dealer’s own record, so they go to dealer credentials only, and the dealer’s staff download them from their Battery Health Check portal. Asking for one with ?variant=full answers 403 variant_not_permitted (You receive the anonymised copies only).
What happens when a dealer disconnects? It takes effect at once: its tests answer 404, its webhooks stop and you receive bhc.connection.revoked. You delete that dealer’s data within 30 days (Platform Terms, clause 6). What is already on its live adverts is the dealer’s to manage.
What are the rate limits? Per credential and per endpoint, and one allowance covers all your connected dealers. 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.
Where do we start? The Platform quickstart takes you from the first token to the result on a vehicle detail page. A sandbox credential answers from fixture cars while you build, and the API explorer lets you try each one in your browser.
Provider modes
Besides AVILOO test results, the API presents AVILOO’s battery readings at GET /v1/vehicles/battery-readings, and answers about a car from provenance providers, one provider at a time and each in its own words, at GET /v1/vehicles/provenance, for a car with a test at a dealer that has connected you. GET /v1/providers lists every provider with its stage. AVILOO is the battery provider, and the Live provenance providers are DVSA, for the full MOT history of every car Battery Health Check has tested, and the vehicle record provider, for the vehicle record Battery Health Check already holds. Every other provenance provider is Planned: production answers nothing from it, and the sandbox shows the shape of what it returns. Who they are, and what each domain covers: Data and providers.
Battery Health Check’s own valuation, with a valuation adjuster you apply to your own standard valuation, is Beta: figures in the sandbox now; production figures follow. See Valuation.
Never combine providers: two provenance checks are two separate answers, so show each with its own provider and its attribution_text. Show each battery reading with its provider, method and test date, as its display_conditions say.