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

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 areUse
A platform serving many dealersA platform credential, connected by each dealer. This page.
One dealer or one dealer group, or a developer building for oneA key the dealer issues from its own portal. See How to integrate.
A marketplace looking up cars across every dealer, connected or notThe 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

  1. Get your platform credential and a token (read data.access_token).
  2. Register one webhook endpoint for the test and connection events, and register your return URLs.
  3. Put the Connect button in your software, carrying a reference you can match and a return_to.
  4. On each new connection, map its sites and backfill their tests.
  5. Take test events as they come, and run the hourly sweep as the safety net.
  6. 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.

  1. 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.

  2. 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).

  3. Copy your secret

    Creating the credential shows the client_secret once, 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.

Start building straight away. You do not need a connected dealer to begin. Get a token (it is inside 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>
ParameterWhat it is
pYour 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.
refOptional. 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_toOptional. 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&amp;ref=YOUR_REFERENCE&amp;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

  1. 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.

  2. 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.

  3. 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.created event is on its way to you. With a registered return_to the 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

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 isWhat it needs to do
A branch of a groupAsk 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 yetAsk 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 accountNothing can be connected.
Following a link whose ref breaks the character rulesNothing: 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.

ParameterValue
bhc_statusconnected 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_idWith connected only: the connection’s dealer_id, as in GET /v1/connections. For a group, its head office.
refThe 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:

  1. 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.
  2. When a connection arrives with that reference as platform_reference, in a bhc.connection.created or bhc.connection.updated event or in GET /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.
  3. 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.

Never ask a dealer for its Battery Health Check password or API keys, and never alter the Connect link beyond adding 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

GET /v1/connect-settings Your Connect link and return URLs
PUT /v1/connect-settings Replace your return URLs

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" }
}
FieldMeaning
connect_urlYour 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_urlsYour registered return URLs, in the order you sent them. [] until you register one.
updated_atWhen 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

StatusCodeWhen
400invalid_requestThe body is not a JSON object.
400invalid_fieldfield: "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.
403insufficient_scopeThe token does not carry manage:webhooks.
404not_foundThe 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:

CallOn a platform credential
GET /v1/testsLists 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}/preview
GET /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}/warrantyA 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/connectionsThe dealers that have connected you, and their sites. Below.
GET / PUT /v1/connect-settingsYour Connect link and your return URLs. Above.
/v1/webhooksOne endpoint for every connected dealer. See One webhook endpoint.

Field-by-field detail for the test object is in the API reference and the data dictionary.


List the dealers connected to you

GET /v1/connections

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

ParamTypeDescription
pageinteger1-based page number. Default 1.
per_pageinteger1–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" }
}
FieldMeaning
dealer_id, nameThe dealer that connected you. For a group, its head office.
sitesEvery 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[].postcodeTown 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_atWhen the dealer connected you.
platform_referenceThe 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.

EventSent when
bhc.test.completedA connected dealer’s test result lands. data.test is the test object.
bhc.test.failedA test could not complete.
bhc.test.warranty_changedThe 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.createdA dealer connected you.
bhc.connection.updatedA connected dealer followed a link carrying a different ref and confirmed it, so its platform_reference changed.
bhc.connection.revokedThe 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"
  }
}

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

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:

  1. 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 through GET /v1/tests?dealer_id=<site>&current=true&per_page=100, each car’s current test at that site. A dealer that is no longer listed has disconnected you.

  2. Fetch everything that changed since the last sweep

    GET /v1/tests?updated_since=<start of your last sweep, minus a few minutes>&current=true&per_page=100, following page until meta.has_more is false. updated_since returns 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=true keeps only each car’s current test, the one to show, so a failed retest never displaces a good result.

  3. Upsert every test on its id

    The same handling as a webhook delivery: one record per test.id, keeping the copy with the latest updated_at. Most of what the sweep returns you will already hold, and that is the point.

Use 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:

DocumentWhat your credential gets
Certificate PDFGET /v1/tests/{id}/certificate, with or without ?variant=anonymised: the anonymised certificate.
Warranty PDFGET /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=full403 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 saysShow
publishable: trueThe 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: trueThe preview image and anonymised certificate only. No figure, gauge or band of your own: reason says why.
Both falseNo 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=…&current=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.