Battery Health Check Marketplace API
You have a VIN or a number plate from a listing. This API tells you whether that car has had an independent AVILOO battery test, what the test measured, and hands you a certificate image you can publish on the ad — across every Battery Health Check dealer, with one credential and no per-dealer setup.
Goal: show the battery certificate on a used-EV listing.
Three calls. Your credential holds read:tests and read:certificates; keep it server-side.
- Swap the key for a 1-hour token (cache it). The token is inside
data. - Look the vehicle up by VIN or registration.
- Fetch the publishable certificate image, store your own copy, and show your copy.
# 1. Get a token (cache for ~55 min). It is inside "data". TOKEN=$(curl -s -X POST https://api.batteryhealthcheck.co.uk/v1/oauth/token \ -d grant_type=client_credentials \ -d client_id=YOUR_CLIENT_ID -d client_secret=YOUR_CLIENT_SECRET \ | jq -r '.data.access_token') # 2. The car in front of you — by VIN... curl "https://api.batteryhealthcheck.co.uk/v1/tests?vin=WVWZZZ1KZAW000000&per_page=1" \ -H "Authorization: Bearer $TOKEN" # ...or by plate, if that is what your listing carries. # Prefer the VIN where you have one — plates transfer between cars. curl -G "https://api.batteryhealthcheck.co.uk/v1/tests" \ --data-urlencode "registration=201-D-12345" --data-urlencode "per_page=1" \ -H "Authorization: Bearer $TOKEN" # 3. Publishable certificate image (VIN removed): a link that expires in # an hour. Download the JPEG now and serve your own copy. curl https://api.batteryhealthcheck.co.uk/v1/tests/TEST_ID/preview \ -H "Authorization: Bearer $TOKEN"
Full walkthrough with Python / Node / PHP: Embedding battery test data on a listing.
Before you go live: show a figure only when the publish decision for that test (GET /v1/tests/{id}/publish) says it is publishable — not every completed test produces a quotable state of health, and a final result can still be refused for a finding on the test or its age. result_status and Nulls & beta vehicles explain why: some values are legitimately null, and vehicles still in AVILOO validation are flagged vehicle_supported: false.
GET /v1/tests requires vin or registration. It answers “what do you know about this car”. There is no endpoint that lists a dealer's tests and none that lists dealers, so naming the vehicle is the price of entry — see Every call starts with a VIN or a plate.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.batteryhealthcheck.co.uk/v1 |
Conventions
- Transport: HTTPS only (TLS 1.2+). All responses are
application/json; charset=utf-8. - Auth:
Authorization: Bearer <jwt>on every request except/oauth/token. - Content-Type:
application/jsonfor request bodies (except/oauth/token, which is form-encoded). - Dates: ISO 8601 with UTC timezone (e.g.
2026-05-27T14:22:08Z). - Pagination: page-based. Pass
?page=1&per_page=25.per_pageis capped at100. The responsemetaobject carriespage,per_page,total, andhas_more. - Idempotency: on
POST, sendIdempotency-Key: <your-key>to make retries safe. Allowed characters: ASCII alphanumeric, hyphen (-), underscore (_), and dot (.). Max 80 characters. Keys are retained for the lifetime of the resource they idempotently created — there is no purge. - Nulls: we never drop a key. Anything we don't hold is serialised as
null, so the response shape is stable and safe to deserialise into a fixed schema — but you must null-check before rendering. See Nulls & beta vehicles. - Additive changes: we may add new fields to existing responses without notice, and new values to a field whose values are listed (a new provenance section, document kind or provider status, for example). Ignore keys you don't recognise rather than failing on them, and treat a listed field's value you don't recognise as unknown. Breaking changes ship on a new version path, never in place.
- Correlation: every response includes
request_idinmeta+X-Request-Idheader. - Scoping: a dealer-group credential is locked to your group: its head office and every branch under it; a marketplace credential looks up one vehicle at a time, by VIN or registration, across every dealer. Either way, there is no call that lists anything you did not name.
Getting access
Marketplace credentials are issued by Battery Health Check by agreement. There is no self-serve route — they reach every dealer, so they are only ever created deliberately, for a named platform, under terms.
| Step | Who does it | What happens |
|---|---|---|
| 1. Agreement | You and your BHC account manager | Scopes and commercial terms. |
| 2. Invitation | BHC | We send you a single-use invitation link. Nothing exists yet at this point — the link describes the credential, it is not the credential. |
| 3. You create it | You | Open the link and create the credential yourself. The client_id and client_secret are shown on that page, in your browser. Nothing else is needed before your first call. |
Optional, and worth doing: send us the egress IP addresses your servers call from and we will lock the credential to them, so a leaked key is unusable from anywhere else. See IP allow-listing.
Authentication
OAuth 2.0 client-credentials grant. Exchange a long-lived client_id + client_secret pair for a short-lived (1 hour) JWT, then send the JWT as a Bearer token on every other request.
OAuth flow
┌────────────────┐ ┌────────────────┐
│ │ 1. POST /oauth/token │ │
│ │ ─────────────────────────────► │ │
│ │ client_id + client_secret │ │
│ │ grant_type=client_credentials│ │
│ Your server │ │ BHC API │
│ │ 2. 200 OK │ │
│ │ ◄───────────────────────────── │ │
│ │ {"data": {access_token, …}} │ │
│ │ │ │
│ │ 3. GET /tests?vin=… │ │
│ │ ─────────────────────────────► │ │
│ │ Authorization: Bearer <jwt> │ │
│ │ │ │
│ │ 4. 200 OK + JSON │ │
│ │ ◄───────────────────────────── │ │
└────────────────┘ └────────────────┘
Machine-to-machine. No user consent screen, no refresh token. Request a fresh token when the current one is about to expire.
Token endpoint
Request
Content-Type: application/x-www-form-urlencoded
| Parameter | Required | Description |
|---|---|---|
grant_type | yes | Must be client_credentials |
client_id | yes* | Your credential ID |
client_secret | yes* | Your credential secret |
scope | optional | Space-separated list of requested scopes |
* Or send them as HTTP Basic authentication instead, Authorization: Basic base64(client_id:client_secret), which is what most OAuth 2.0 client libraries do by default. Use one or the other. If a request carries the secret in the form body, the body is used and the header is ignored.
curl -s -X POST https://api.batteryhealthcheck.co.uk/v1/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=part_a1b2c3d4e5f6" \ -d "client_secret=<your-secret>" \ -d "scope=read:tests read:certificates" \ | jq -r '.data.access_token'
import requests
resp = requests.post(
"https://api.batteryhealthcheck.co.uk/v1/oauth/token",
data={
"grant_type": "client_credentials",
"client_id": "part_a1b2c3d4e5f6",
"client_secret": SECRET,
"scope": "read:tests read:certificates",
},
timeout=10,
)
resp.raise_for_status()
token = resp.json()["data"]["access_token"] # inside "data"
const params = new URLSearchParams({
grant_type: "client_credentials",
client_id: "part_a1b2c3d4e5f6",
client_secret: process.env.BHC_SECRET,
scope: "read:tests read:certificates",
});
const resp = await fetch(
"https://api.batteryhealthcheck.co.uk/v1/oauth/token",
{ method: "POST", body: params }
);
if (!resp.ok) throw new Error(`token request failed: ${resp.status}`);
const { data } = await resp.json();
const accessToken = data.access_token; // inside "data"
Response 200 OK
{
"data": {
"access_token": "eyJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read:certificates read:tests"
},
"meta": { "request_id": "req_b4c6d8e0f2a4" },
"access_token": "eyJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read:certificates read:tests"
}
The token is in data, and also at the top level. Like every other success response, the token response is wrapped in the {"data": …, "meta": …} envelope, so data.access_token and data.expires_in are there, as the examples above read them. The same four values are repeated at the top level of the body, where the OAuth 2.0 standard puts them, so a stock OAuth client library works without configuration. Both copies are always present and always equal. scope lists the scopes the token actually carries, in alphabetical order: the scopes you asked for that your credential holds, or every scope it holds if you asked for none. The response carries Cache-Control: no-store: keep the token in your own cache, as below, not in a shared HTTP cache.
Errors
A refused token request answers in the same error envelope as every other call, {"error": {"code", "message", "request_id"}}, not in the flat {"error": "...", "error_description": "..."} form of the OAuth 2.0 standard. Branch on error.code:
| Status | error.code | When |
|---|---|---|
| 400 | invalid_request | The body is not form-encoded, or client_id or client_secret is missing, or the body’s client_id differs from the HTTP Basic user name. |
| 400 | invalid_grant_type | grant_type is not client_credentials. (The standard calls this unsupported_grant_type.) |
| 400 | invalid_scope | None of the scopes you asked for is one your credential holds. The error also carries requested and granted. Asking for some you hold and some you do not is not an error: the token carries the ones you hold. |
| 401 | invalid_client | The client_id or the client_secret is wrong. |
| 403 | credential_disabled | The credential has been disabled. |
| 429 | too_many_requests | More than ten token requests a minute for one client_id (rate limits). Cache the token. |
What a stock OAuth library shows. A standard client library raises its usual error on a refusal, but because the body is not in the standard’s flat form, the error it reports is our whole error object and its description is empty. Authlib, for example, raises OAuthError with .error set to {"code": "invalid_client", "message": "Client credentials are not valid", "request_id": "req_…"}. Read code from that object, and quote its request_id if you ask us about it.
JWT structure
The access_token is a JWT signed with HS256. You don't need to verify the signature yourself — just store and present the token. We verify on our end.
{
"iss": "bhc-partner-api",
"aud": "bhc-partner-api",
"sub": "part_a1b2c3d4e5f6",
"credential_id": 57,
"kind": "dealer",
"parent_company_id": 198,
"scope": "read:certificates read:tests",
"iat": 1748354221,
"exp": 1748357821,
"jti": "Qm4xYzVkOGU3ZjJhOWIwYw"
}
kind is "marketplace" on your token and parent_company_id is null: see Your reach.
Treat the token as opaque all the same. What a credential can reach is worked out on every request from the credential itself, so read kind for your logs, never to decide what to call.
Scope catalog
A marketplace credential can hold these and nothing else. The set is enforced when the credential is created, so it cannot be widened by mistake later.
| Scope | Grants | Granted |
|---|---|---|
read:tests | Look up tests by VIN or registration; read a single test | Always |
read:certificates | Get the anonymised PDF certificate (VIN hidden) and the publishable JPEG preview | Always |
manage:webhooks | Register and manage push subscriptions for new tests | By agreement — not granted by default |
read:warranties is not available to a marketplace credential either. A marketplace key reaches tests across every dealer, and the warranty is a second document carrying the VIN — a wider exposure than rendering a certificate on a listing calls for. Ask us if you have a use for it.
read:dealers and write:dealers are never available to a marketplace credential. The dealer object behind those endpoints carries contacts, addresses, VAT numbers and hardware serial numbers — far more than rendering a certificate on a listing needs. Each test you receive already names its dealer as dealer: {id, name} — inline on the lookup, on GET /tests/{id} and in webhook deliveries alike — so putting a name on a listing never costs you a second request.
Requesting a scope at the token endpoint can only narrow what you hold, never widen it: ask for something you were not granted and it is simply dropped from the token.
Your reach
Your credential has no dealer group of its own and is not tied to a list of them. It answers about any vehicle you can name: give us a VIN or a registration and, if that car has been tested by any Battery Health Check dealer, you get the test and its certificate back.
That is deliberate. You cannot know in advance which dealer holds which car, and you should not have to — you have a listing, we have a test, and the question is only whether they are the same vehicle.
- One credential, every dealer. No per-dealer setup, nothing to add when a dealer joins, nothing to chase when one of your advertisers changes group.
- Naming the car is the price of entry. There is no call that lists tests, and no call that lists dealers. Without a VIN or a registration you get
400 invalid_request; with one for a car we have never tested you get an empty result, not an error. See Every call starts with a VIN or a plate. - Single tests follow your lookups.
GET /v1/tests/{id},/certificateand/previewanswer for any test of a vehicle you have looked up — by its VIN, or by a registration it carries. A test of any other vehicle is404 not_found, exactly as for an id that does not exist, so test ids cannot be counted through. - An untested car looks the same as one we don't cover. Both are an empty
dataarray. Treat "no test" as the ordinary case — it will be most of your stock. - Token shape. Your access token carries
"parent_company_id": nulland"kind": "marketplace". Treat it as opaque; reach is resolved server-side on every request.
/certificate gives you the anonymised certificate PDF, with the VIN hidden. The full PDF shows the VIN and carries identifiers reserved for the dealer’s own record, so it goes to dealer credentials only: your credential never receives it, and ?variant=full answers 403 variant_not_permitted.
A marketplace credential can also be issued narrowed to named dealer groups instead, if that is what an agreement calls for. A narrowed credential reads any test in its granted groups by id, with no lookup first. Yours is not narrowed, unless your account manager has told you otherwise.
Token caching
Tokens are valid for 1 hour. Cache and reuse them — request a fresh one only when the current token is within 5 minutes of expiry. The token endpoint allows 10 requests a minute for each client_id.
import time, threading, requests
TOKEN_URL = "https://api.batteryhealthcheck.co.uk/v1/oauth/token"
_cache = {"token": None, "expires_at": 0}
_lock = threading.Lock()
def get_access_token():
if _cache["token"] and time.time() < _cache["expires_at"] - 300:
return _cache["token"]
with _lock:
now = time.time()
if _cache["token"] and now < _cache["expires_at"] - 300:
return _cache["token"]
resp = requests.post(TOKEN_URL, data={
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
}, timeout=10)
resp.raise_for_status()
data = resp.json()["data"] # the token is inside "data"
_cache["token"] = data["access_token"]
_cache["expires_at"] = now + data["expires_in"]
return _cache["token"]
IP allow-listing
A credential can be locked to a set of source addresses. Once an allow-list is set, a request presenting a perfectly valid token from any other address is rejected with 403 ip_not_allowed — so a leaked client_secret is worthless to anyone who cannot also call from your infrastructure.
This is a second, independent factor on top of OAuth and we recommend it for any server-to-server integration. Ask your account manager to set it, and give us the egress addresses your integration calls from. Two things to keep in mind:
- Tell us before your egress addresses change. A NAT gateway replacement or a new region will lock you out at the moment of cutover. We can hold both old and new ranges over a migration.
- It is per credential. If your staging and production environments call from different addresses, use separate credentials rather than one broad allow-list.
If your security team requires certificate-based client authentication specifically, rather than network-level restriction, raise it with your account manager — it is a scoped piece of work rather than something we run today.
Credential rotation and revocation
Credentials do not expire automatically. We recommend rotating annually as routine practice, and immediately on suspected compromise. A secret cannot be changed in place: rotating means a new credential, with its own client_id and secret.
Rotation. Issue a second credential alongside the existing one; both remain valid concurrently. Deploy the new credential, confirm it is in use, then revoke the previous one. This allows rotation without downtime. Webhook endpoints belong to the credential that registered them, so register yours again on the new credential before you revoke the old one.
Revocation. Revocation takes effect on the next request. Every request re-reads the credential, so a token issued before the revocation stops working at once, without waiting for it to expire, and the credential cannot obtain a new one. Its queued webhook deliveries stop too.
Who performs it. Marketplace credentials are issued by Battery Health Check, so rotation goes through us — ask your account manager and we will issue the replacement before revoking the old one, so you are never without a working key. A replacement credential with global reach starts with no lookups of its own, so look a vehicle up again before reading its tests by id. A revoked credential returns 403 credential_disabled.
Endpoints
Every endpoint requires a Bearer JWT. All requests and responses follow the conventions in the Conventions section.
Every call starts with a VIN or a plate
GET /v1/tests requires vin or registration on a marketplace credential. A request with neither is refused:
# No vehicle identified — refused.
curl "https://api.batteryhealthcheck.co.uk/v1/tests" \
-H "Authorization: Bearer ACCESS_TOKEN"
HTTP/1.1 400 Bad Request
{
"error": {
"code": "invalid_request",
"message": "This credential looks up one vehicle at a time: supply vin or registration.",
"request_id": "req_9f2c1a7b3e5d"
}
}
The other filters narrow a lookup; none of them replaces one:
| Parameter | On its own | With a VIN or plate |
|---|---|---|
dealer_id | 400 invalid_request | Restricts the lookup to that one dealer |
since / until | 400 invalid_request | Restricts the lookup to a date range |
updated_since | 400 invalid_request | Restricts the lookup to tests new or changed since that instant |
page / per_page | 400 invalid_request | Pages the results for that vehicle |
Everything after the lookup works on a test you have already found: read it, then fetch its publishable image. With global reach (the default), only for a vehicle you have looked up: a test of any other vehicle is 404 not_found.
Several cars at once: POST /v1/tests/lookup takes up to 50 vehicles, each by its full VIN or its registration only, never a VIN prefix. Each vehicle counts as one lookup against a budget of 60 a minute, and unlocks GET /v1/tests/{id} for that vehicle’s tests, exactly as a GET /v1/tests lookup does.
Look up tests by VIN or registration
Find tests for a specific vehicle across every Battery Health Check dealer. The primary use case is dealer websites and listing platforms: your inventory page has a VIN or a number plate, you want the most recent battery test for that vehicle to embed on the listing.
Required scope: read:tests
This is the entry point for marketplace credentials, which must supply vin or registration on every call.
Query parameters
| Param | Type | Description |
|---|---|---|
vin | string | Vehicle Identification Number. The full 17 characters — prefix search is not available on a marketplace credential, because a short prefix would match across every dealer. A shorter value returns 400 invalid_field. |
registration | string | Vehicle registration mark (number plate). Exact match only — there is no prefix search. Spaces, hyphens and case are ignored on both sides, so WP72FKH, WP72 FKH and wp72-fkh are equivalent. |
dealer_id | integer | Restrict to one dealer you have access to. Cannot be used on its own — see the lookup rule. Combines with the filters above. |
current | boolean | true: only the car’s current test, the one its publish decision names as current_test_id (its most recent completed test with a battery-health figure or, when no completed test has one, its most recent test). Use it to show one result per car. With registration, the current test is returned only when it carries that plate; search by vin to be sure of it. Default false. |
status | string | Comma-separated. Only tests in one of these states: pending, in_progress, completed, failed, cancelled. |
warranty_state | string | Comma-separated, at most 10 values. Only tests whose warranty_state is one of these, for example ACTIVE,INELIGIBLE. A test with no warranty state never matches. |
completed_since | ISO 8601 | Only tests with results_received_at >= completed_since. A test with no completion time never matches. |
completed_until | ISO 8601 | Only tests with results_received_at <= completed_until. |
unit_id | integer | Only tests run on this unit (the test’s unit_id). |
powertrain | string | Comma-separated, at most 10 values. Only tests whose vehicle.powertrain is one of these, for example BEV,PHEV. A test with no powertrain never matches. |
model_group_id | string | Only tests whose vehicle.model_group_id is exactly this: the id of the model group the car was tested as. Case is ignored. A test with no model group id never matches. |
page | integer | 1-based page number. Default 1. |
per_page | integer | 1–100. Default 25. Results are ordered newest-first by tested_at. |
vin: 17 characters, digits and A–Z except O and Q (lower case is accepted and read as upper case). registration: letters, digits, spaces and hyphens, 2–20 characters once spaces and hyphens are stripped. Anything else returns 400 invalid_field.
So: use registration when a plate is what you have — a customer-facing lookup box, a stock feed that carries plates but not VINs. Use vin whenever you have one, and store vehicle.vin as the join key in your own database rather than the plate. If you cache results against a plate, you will eventually attach one vehicle's battery report to a different vehicle.
Example — by VIN
curl -G https://api.batteryhealthcheck.co.uk/v1/tests \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "vin=VR3UHZKXZNT123456" \ --data-urlencode "current=true"
Example — by registration
curl -G https://api.batteryhealthcheck.co.uk/v1/tests \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "registration=WP72 FKH" \ --data-urlencode "current=true"
Handling more than one result
Both filters return a paginated array, not a single object — ordered newest-first by tested_at. There are three reasons you may get more than one row, and they need different handling:
| Why | What you see | What to do |
|---|---|---|
| The car was retested (the common case) | Several rows, same vehicle.vin, different tested_at |
Add current=true: you get only the car’s current test (by registration, only when that test carries the plate: search by vin to be sure of it). Without it the first row is merely the newest, which can be a failed or inconclusive retest of a car with an earlier result. |
The plate was transferred (registration only) |
Several rows with different vehicle.vin values |
These are genuinely different vehicles that have worn the same plate. Do not merge them. Disambiguate on vehicle.vin, or re-query by VIN. |
| Two dealers tested the same car | Several rows, same VIN, different dealer_id |
Normal in a group. Filter with dealer_id if you want one branch's view. |
registration returns rows whose vehicle.vin values differ, you are looking at more than one vehicle — taking data[0] blindly will publish the wrong car's battery health. A one-line guard:
rows = get("/v1/tests", registration=plate)["data"]
vins = {r["vehicle"]["vin"] for r in rows if r["vehicle"]["vin"]}
if len(vins) > 1:
# Plate has transferred. Ask for a VIN rather than guessing.
raise Ambiguous(plate, vins)
An unknown plate or VIN is not an error — it returns 200 with "data": [] and "total": 0. Treat empty as “no test on record”, never as a failure.
vehicle.registration: null and cannot be found by registration at all. It is still findable by vin. This is the other reason to prefer VIN where you have one: vin can match every test we hold, registration can only match the plated ones.
Response 200 OK
{
"data": [
{
"id": 9182,
"internal_reference": "BHC-TEST-009182",
"dealer_id": 247,
"unit_id": 412,
"status": "completed",
"vehicle": {
"registration": "AB23 CDE",
"vin": "VR3UHZKXZNT123456",
"make": "Peugeot",
"model": "e-208",
"year": 2022,
"mileage_km": 29644,
"odometer": { "value": 47707, "unit": "km", "km": 47707, "miles": 29644 }
},
"battery": {
"soh_percent": 91.4,
"capacity_kwh": 45.7,
"nominal_kwh": 50.0,
"estimated_range_miles": 152,
"cell_count": null,
"cell_variance": 0.012,
"usable_capacity_kwh": 41.0,
"usable_nominal_kwh": 45.0
},
"tested_at": "2026-05-26T14:22:08Z",
"results_received_at": "2026-05-26T14:25:09Z",
"result_status": "final",
"certificate_number": "BHC-7K2M-Q9XD-4HTA",
"certificate_available": true,
"preview_available": true,
"created_at": "2026-05-26T14:22:08Z",
"updated_at": "2026-05-26T14:25:09Z"
}
],
"meta": {
"page": 1,
"per_page": 25,
"total": 1,
"has_more": false,
"request_id": "req_91c2d4e6f8a0"
}
}
Empty data array means no tests of that vehicle are within your reach — either it hasn't been tested, or it was tested by a dealer whose tests you cannot read.
diagnostics object — the full measurement record, the per-subsystem check results — plus top-level vehicle_supported (the beta-model flag) and warnings. Both are omitted from the example for length; see The diagnostics block and Warnings.
Look up several vehicles
Look up to 50 vehicles in one request, each by its full VIN or by its registration. For each one you get the newest test of that vehicle across every Battery Health Check dealer, exactly as GET /v1/tests/{id} returns it, and that test’s publish decision, exactly as GET /v1/tests/{id}/publish returns it. Results come back in the order you sent the vehicles.
Show current_test, not latest_test. current_test is the test that speaks for the car, the one the publish decision names as current_test_id: its most recent completed test with a battery-health figure or, when no completed test has one, its most recent test. It is the same object as latest_test unless the newest test is a failed or inconclusive retest of a car with an earlier result. Both are the full GET /v1/tests/{id} object. current_publish is the publish decision for current_test, made with the same mileage_miles: decide from it, and you never need a second GET /v1/tests/{id}/publish. It is the same object as publish when the two tests are the same, and null exactly when current_test is. You get current_test only when you could then read it by id: a lookup by VIN covers every test of that VIN, a lookup by registration only the tests that carry that registration. So when the current test was recorded without the plate, or under an earlier one, a registration lookup returns current_test: null and publish.current_test_id gives its id: look the car up by latest_test.vehicle.vin to get it.
Required scope: read:tests
Request body
| Field | Type | Description |
|---|---|---|
vehiclesrequired | array | 1–50 vehicle objects (fields below). |
dealer_id | integer | Restrict every lookup to one dealer and its branches. An id outside your reach returns 404 not_found. |
Each vehicle
| Field | Type | Description |
|---|---|---|
vin | string | The full 17 characters; there is no prefix search here. Digits and A–Z except O and Q. |
registration | string | Exact match. Spaces, hyphens and case are ignored, as on GET /v1/tests. |
ref | string | Your own identifier for the vehicle, echoed back on its result: up to 64 letters, digits, ., _, : and -. |
mileage_miles | integer | The odometer reading on your advert, in miles (0–1,000,000). The publish decision then also checks the advert against the reading at the test. |
Each vehicle needs vin or registration. If you send both, the VIN is used and the registration is ignored.
Example
curl -X POST https://api.batteryhealthcheck.co.uk/v1/tests/lookup \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vehicles": [
{ "ref": "stk-118", "vin": "VR3UHZKXZNT123456" },
{ "ref": "stk-119", "registration": "WP72 FKH" },
{ "ref": "stk-120", "vin": "VR3UHZKXZNT654321" }
]
}'
Response 200 OK
{
"data": [
{
"object": "lookup_result",
"index": 0,
"ref": "stk-118",
"query": { "vin": "VR3UHZKXZNT123456", "registration": null },
"matched_on": "vin",
"found": true,
"tests_found": 2,
"distinct_vins": 1,
"ambiguous": false,
"latest_test": { "id": 9183, "status": "failed", "...": "the GET /v1/tests/{id} object" },
"current_test": { "id": 9182, "status": "completed", "...": "the GET /v1/tests/{id} object" },
"publish": { "object": "publish", "test_id": 9183, "current_test_id": 9182, "...": "the GET /v1/tests/{id}/publish object" },
"current_publish": { "object": "publish", "test_id": 9182, "publishable": true, "...": "the decision for current_test" },
"error": null,
"warnings": []
},
{
"object": "lookup_result",
"index": 1,
"ref": "stk-119",
"query": { "vin": null, "registration": "WP72FKH" },
"matched_on": "registration",
"found": true,
"tests_found": 2,
"distinct_vins": 2,
"ambiguous": true,
"latest_test": { "id": 9240, "...": "the newer of the two" },
"current_test": { "id": 9240, "...": "the same test" },
"publish": { "object": "publish", "test_id": 9240, "publishable": false, "reason": "AMBIGUOUS_REGISTRATION", "...": "..." },
"current_publish": { "object": "publish", "test_id": 9240, "publishable": false, "reason": "AMBIGUOUS_REGISTRATION", "...": "..." },
"error": null,
"warnings": []
},
{
"object": "lookup_result",
"index": 2,
"ref": "stk-120",
"query": { "vin": "VR3UHZKXZNT654321", "registration": null },
"matched_on": null,
"found": false,
"tests_found": 0,
"distinct_vins": 0,
"ambiguous": false,
"latest_test": null,
"current_test": null,
"publish": null,
"current_publish": null,
"error": null,
"warnings": []
}
],
"meta": { "count": 3, "found": 2, "request_id": "req_91c2d4e6f8a0" }
}
ambiguous: true means a transferred plate. The registration matched tests of more than one vehicle. Do not merge them and do not publish latest_test against your advert on the strength of the plate alone: check latest_test.vehicle.vin, or send the VIN. Both publish decisions say so: publishable is false and reason is AMBIGUOUS_REGISTRATION, whatever the test itself found. latest_test and current_test are still returned, so you can compare their vehicle.vin with yours. Store and join on vehicle.vin, never the plate.
Not found is not an error. "found": false means no test of that vehicle is on record at any Battery Health Check dealer: the car has not been tested. Never show a battery figure for it.
Errors
A problem with one vehicle never fails the batch. That item comes back with an error, found: null, and is not looked up; the others are answered:
{
"object": "lookup_result",
"index": 3,
"ref": "stk-121",
"query": { "vin": null, "registration": null },
"matched_on": null, "found": null, "tests_found": null,
"distinct_vins": null, "ambiguous": null,
"latest_test": null, "current_test": null, "publish": null,
"current_publish": null,
"error": {
"code": "invalid_field",
"field": "vin",
"message": "vin must be the full 17-character VIN on this credential; prefix search is not available."
},
"warnings": []
}
The whole request fails only when it cannot be read:
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | The body is not a JSON object, or vehicles is missing, not a list, empty, or longer than 50. |
| 400 | invalid_field | dealer_id is not a positive integer. |
| 404 | not_found | dealer_id is outside your reach (the message says “partner tree”). |
Limits
10 requests a minute. Each vehicle in a batch also counts as one lookup against a budget of 60 a minute, so a batch larger than what is left of the minute is refused whole with HTTP 429; wait the seconds in its Retry-After header (never more than 60). Looking a vehicle up here works exactly as a GET /v1/tests lookup does: it is what lets you read that vehicle’s tests by id afterwards (Get a test), and only that vehicle’s.
Get a test
Full JSON for a single test, including all vehicle and battery details.
Required scope: read:tests
vehicle.odometer, not vehicle.mileage_km. Despite its name, mileage_km carries the reading in miles. It is kept unchanged so existing integrations do not break. vehicle.odometer gives the reading as AVILOO reported it, its unit (km for almost every model, mi for the few that report miles themselves) and the same reading in kilometres and in whole miles:
"odometer": { "value": 47707, "unit": "km", "km": 47707, "miles": 29644 }
It is null when no reading is held for the test. See the data dictionary.
AVILOO’s own codes for the test
Beside our own status and result_status, each test object carries AVILOO’s codes, passed through unchanged. Branch on status and result_status; use these for detail and diagnosis.
| Field | What it holds |
|---|---|
result_type | AVILOO’s overall result: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null until the test is evaluated, and on tests that did not complete. |
error_reason | Why a test stopped, for example DONGLE_NO_VEHICLE_EXCEPTION (no vehicle detected) or INCOMPLETE. Null for a test that did not stop. |
provider_state | AVILOO’s nine-state lifecycle for the test (DATA_ACQUISITION, VERIFYING, EVALUATION_DONE, EXECUTION_ERROR and so on), of which status is our four-state reading. |
warning_details | The test’s warnings with AVILOO’s own sentence for each: [{code, text, public_display}], in the same order as warnings. public_display is always false: the sentences are advice to whoever ran the test, not copy for an advert. See Warnings. |
vehicle.model_group_id | AVILOO’s identifier for the model group the car was tested as, for example VMD-0638. Use it to group results by model; vehicle.model is a display string. |
Treat a value you do not recognise as unknown, not as an error: the lists are AVILOO’s.
The certificate PDFs: certificate_documents
Every test object lists both versions of the certificate PDF in certificate_documents, full first, each {variant, available, path, content_type, public_display, withheld_reason}, as warranty.documents lists the warranty PDFs. full shows the VIN and is never for a public page (public_display false); anonymised hides the VIN (public_display true), which describes the copy, not the test: when a public page may carry it is set out under Get the certificate. available is certificate_available for both: the copy can be requested, so a version not stored yet answers 409 once and is fetched. Fetch either from its path, as described in Get the certificate.
Which copies your credential receives. The full certificate and the full warranty documents carry identifiers reserved for the dealer’s own record, so only a dealer credential receives them. To a platform, marketplace or sandbox credential, the full item of certificate_documents and warranty.documents is listed with available false, path and content_type null, and withheld_reason "DEALER_CREDENTIALS_ONLY", so the lists keep the same shape for every credential. withheld_reason is null on every other item, including the full item of warranty.images: the full image is served to no credential, dealers included, so it is unavailable to everyone rather than withheld from you. Treat a withheld_reason you do not recognise as “not available to this credential”.
The battery warranty: warranty
Every test object carries a warranty block: AVILOO’s battery warranty for the car in one normalised shape. It gives the state and reasons (the same values as the flat warranty_state and warranty_reasons, which are unchanged), when the state was recorded and last confirmed (state_changed_at, as_of), when AVILOO created the warranty (created_at, where AVILOO has sent it), the period, mileage limit and state-of-health threshold where AVILOO has sent them (issued_at, expires_at, mileage_limit, soh_threshold_percent, otherwise null), the issuer, the document (the PDF GET /v1/tests/{id}/warranty serves your credential without a variant: the full one to a dealer credential, the anonymised one otherwise; available is warranty_available), documents (the full and the anonymised PDF, each with public_display and withheld_reason; only the anonymised one may go on a public page), images (the same two versions as preview images, JPEG, with the same rule) and terms_url, AVILOO’s own page for the warranty’s conditions. compensation is null in production. The whole block is null exactly when warranty_state is null. Field by field: the data dictionary.
"warranty": {
"provider": "aviloo", "product": "aviloo_battery_warranty",
"issuer": { "name": "Aviloo GmbH", "country": "AT" },
"state": "INELIGIBLE", "state_changed_at": "2026-09-21T10:31:00Z", "as_of": "2026-09-21T10:31:00Z",
"created_at": null, "issued_at": null, "expires_at": null, "mileage_limit": null, "soh_threshold_percent": null,
"compensation": null, "reasons": ["VEHICLE_NOT_SUPPORTED"],
"document": { "available": false, "path": null, "content_type": null },
"documents": [
{ "variant": "full", "available": false, "path": null, "content_type": null, "public_display": false, "withheld_reason": null },
{ "variant": "anonymised", "available": false, "path": null, "content_type": null, "public_display": true, "withheld_reason": null }
],
"images": [
{ "variant": "full", "available": false, "path": null, "content_type": null, "public_display": false, "withheld_reason": null },
{ "variant": "anonymised", "available": false, "path": null, "content_type": null, "public_display": true, "withheld_reason": null }
],
"terms_url": "https://aviloo.com/en/aviloo-warranty",
"source": "provider_record"
}
The diagnostics block
Every test object — from GET /v1/tests, GET /v1/tests/{id} and the webhook payload alike — carries a diagnostics object alongside vehicle and battery. It is the normalised form of the full AVILOO measurement record: the same data the certificate is generated from, including the per-subsystem check results and the vehicle support flag.
vehicle_supported on the test object. It carries the same meaning as diagnostics.vehicle_supported below, but it survives a null diagnostics block and is reconciled against every signal AVILOO gives us — so it is guaranteed to agree with the BETA badge the dealer sees in their portal. Prefer it; read the nested one only if you are already working inside the diagnostics block. AVILOO’s vehicle coverage is continually expanding, and models still in validation are tested on a beta basis:
true— fully supported model. All derived figures are validated for this vehicle.false— beta / not yet fully supported. The test still runs and a certificate is still issued, but AVILOO marks the certificate accordingly, and derived figures (estimated range, cell count, and occasionally SoH itself) may be missing or outside the expected range. The dealer portal shows a BETA badge on these tests.null— unknown, because no measurement record is stored for this test (see below).
Fields
| Field | Type | Description |
|---|---|---|
vehicle_supported | boolean | null | false = beta / not yet fully supported model. Mirrored to the top level of the test object, which is the copy you should read — see the callout above. |
overall_battery_status | string | null | AVILOO’s headline verdict: OK, WARNING, NOT_CONCLUSIVE or SAFETY_ISSUE. |
soh_status | string | null | AVILOO’s status for its own state-of-health reading (battery.soh_percent), in the same four values. |
battery_checks | object | Per-subsystem results, each OK / WARNING / NOT_CONCLUSIVE / SAFETY_ISSUE: battery_management_system, battery_sensors, battery_pack_parameters, battery_cell_voltages, vehicle_communication. |
sensor_checks | object | Sensor-level results: voltage_sensor, current_sensor, temperature_sensors, cell_voltage_sensors. |
energy_kwh | object | Gross / net / usable energy, both *_nominal_new (when the battery was new) and *_current (measured now). All kWh. battery.capacity_kwh and battery.nominal_kwh are the gross pair; battery.usable_capacity_kwh and battery.usable_nominal_kwh are the usable pair. |
range | object | AVILOO reports its ranges in km. typical_*_km and personal_*_km carry its figures unchanged; typical_*_miles and personal_*_miles are the same figures converted to whole miles, and typical_current_miles equals battery.estimated_range_miles. Where AVILOO’s typical range new is under 55% of the car’s own official WLTP figure (or, where AVILOO gives no figure for the car new, its typical range now against WLTP now), the range is inconsistent with that figure and is withheld, not guessed: the typical and personal figures, *_miles and *_km alike, and battery.estimated_range_miles are null, and battery-readings carries no typical or personal entry for the test. The WLTP figures are still given. wltp_*_km are {from, to} pairs in km. Any of these may be null. |
measurements | object | cell_temperature_c and cell_voltage_v as {min, max, delta, status}, with each reading’s own status as min_status, max_status and delta_status; plus pack_voltage_v, average_current_a, mileage_km, and the statuses pack_voltage_status and average_current_status. |
bms | object | What the car’s own battery management system reported: soc_percent and soh_percent, plus the numeric soc_calculation_accuracy / soh_calculation_accuracy figures AVILOO derives for them, each with AVILOO’s status (soc_status, soh_status, soc_accuracy_status, soh_accuracy_status). The BMS SoH is the car’s self-assessment — useful as a cross-check against AVILOO’s independently measured battery.soh_percent, but it is the latter that appears on the certificate. |
Example
{
"data": {
"id": 9182,
"status": "completed",
"vehicle": { "vin": "VR3UHZKXZNT123456", "make": "Peugeot", "model": "e-208" },
"battery": { "soh_percent": 91.4, "capacity_kwh": 45.7, "usable_capacity_kwh": 41.0, "estimated_range_miles": 152 },
"vehicle_supported": true,
"warnings": [],
"diagnostics": {
"vehicle_supported": true,
"overall_battery_status": "OK",
"soh_status": "OK",
"battery_checks": {
"battery_management_system": "OK",
"battery_sensors": "OK",
"battery_pack_parameters": "OK",
"battery_cell_voltages": "OK",
"vehicle_communication": "OK"
},
"sensor_checks": {
"voltage_sensor": "OK",
"current_sensor": "OK",
"temperature_sensors": "OK",
"cell_voltage_sensors": "OK"
},
"energy_kwh": {
"gross_nominal_new": 50.0, "gross_current": 45.7,
"net_nominal_new": 46.3, "net_current": 42.1,
"usable_nominal_new": 45.0, "usable_current": 41.0
},
"range": {
"typical_new_miles": 166, "typical_current_miles": 152,
"personal_new_miles": null, "personal_current_miles": null,
"typical_new_km": 267.0, "typical_current_km": 244.0,
"personal_new_km": null, "personal_current_km": null,
"wltp_new_km": { "from": 340.0, "to": 362.0 },
"wltp_current_km": { "from": 310.8, "to": 330.9 }
},
"measurements": {
"cell_temperature_c": { "min": 17.0, "max": 17.4, "delta": 0.4, "status": "OK",
"min_status": "OK", "max_status": "OK", "delta_status": "OK" },
"cell_voltage_v": { "min": 4.146, "max": 4.159, "delta": 0.013, "status": "OK",
"min_status": "OK", "max_status": "OK", "delta_status": "OK" },
"pack_voltage_v": 398.7,
"average_current_a": 1.2,
"mileage_km": 47707,
"pack_voltage_status": "OK",
"average_current_status": "OK"
},
"bms": {
"soc_percent": 96.0,
"soh_percent": 92.1,
"soc_calculation_accuracy": 1.94,
"soh_calculation_accuracy": 0.95,
"soc_status": "OK",
"soh_status": "OK",
"soc_accuracy_status": "OK",
"soh_accuracy_status": "OK"
}
}
}
}
diagnostics can be null. The block is built from the detailed AVILOO measurement record, which we fetch and store when the test completes. A small number of older tests were ingested before we captured that record and have never been backfilled — for those, diagnostics is null in its entirety. Treat the whole block as optional: test.diagnostics?.vehicle_supported, not test.diagnostics.vehicle_supported.
Warnings
Alongside diagnostics, each test object carries a top-level warnings array — the conditions AVILOO flagged while evaluating the test, as enum strings. Where vehicle_supported tells you the model is still in validation, warnings tells you what was unusual about this particular test.
{
"data": {
"id": 9182,
"battery": { "soh_percent": 102.9 },
"vehicle_supported": false,
"warnings": ["SOH_GREATER_THAN_100"],
"diagnostics": { ... }
}
}
An empty array means AVILOO raised no warnings. null means we hold no evaluation record for the test and therefore can't say either way — treat it as unknown, not as “clean”.
AVILOO’s sentence for each warning: warning_details
The test object also carries warning_details: the same warnings, in the same order, each with the explanation AVILOO prints for it. code is the entry of warnings; text is AVILOO’s sentence in English, or null when AVILOO sent none we can pair with the code. It is null exactly when warnings is, and [] when there are no warnings.
"warning_details": [
{
"code": "SOH_GREATER_THAN_100",
"text": "The calculated SoH is over 100%, which means that your vehicles battery can store more energy than that of an average new vehicle of the same type. For more information, please scan the QR code.",
"public_display": false
}
]
public_display is always false. The sentences are AVILOO’s advice to whoever ran the test (to recharge and retest, or to have the car checked at a workshop), not wording for an advert. Use them in your own staff screens; on a public page, say what the warning means in your own words, or show the certificate image.
Warning types
| Value | Meaning |
|---|---|
SOH_GREATER_THAN_100 | Battery evaluated as having more than 100% of its specified capacity. Usually seen on models still in validation — check vehicle_supported. |
UNCLEAR_MODEL | Vehicle data was ambiguous about the exact model. Verify the model shown on the certificate. |
MISSING_SIGNAL | At least one required signal could not be read from the vehicle. |
IMPLAUSIBLE_SIGNAL | The vehicle reported a value outside the plausible range (e.g. voltage > 2000 V). |
NOT_ENOUGH_DATA | The vehicle did not deliver enough data for at least one required signal type. |
NO_RELAXED_PHASES | No phase without load on the battery could be detected during the test. |
NO_GOOD_RELAXED_PHASES | A relaxed phase was detected but its quality was too low to use. |
BATTERY_TEMP_TOO_LOW | Battery was below the recommended operating window during the test. |
BATTERY_TEMP_TOO_HIGH | Battery was above the recommended operating window during the test. |
BATTERY_TEMP_DELTA_TOO_LARGE | Discrepancy in battery temperature across the pack — potential cooling-system defect. |
BATTERY_TEMP_CRITICALLY_HIGH | Temperature outside the maximum operating window. A safety concern. |
BMS_SOC_IMPLAUSIBLE | The car's own state-of-charge reading is implausible — the BMS may need recalibrating. |
SOH_TOO_LOW | The state of health is below the recommended limit for normal operation. |
SOH_CRITICALLY_LOW | The state of health is below the recommended limit for safe operation. A safety concern. |
CELL_VOLTAGE_SPREAD_TOO_HIGH | A significant difference between the highest and lowest charged cells: a battery left below full charge for long, or a balancing issue. |
CELL_VOLTAGE_SPREAD_CRITICALLY_HIGH | The difference between the highest and lowest charged cells points to a battery balancing fault. A safety concern. |
CURRENT_OUTSIDE_ACCEPTABLE_RANGE | The battery current measurement deviated, which points to a defective current sensor. |
A code can appear more than once: real inconclusive tests carry MISSING_SIGNAL up to twelve times. Count or de-duplicate as your display needs.
A practical use: warnings let you explain an anomalous reading rather than inferring it. An SoH of 102.9% is far more actionable when it arrives with ["SOH_GREATER_THAN_100"] attached.
Can you publish this number? result_status
Every test object carries a top-level result_status. It answers one question directly: how much weight can this test’s numbers carry? It is cheaper to read than reasoning across status, soh_percent, vehicle_supported and warnings yourself.
It is not, on its own, permission to publish. Whether a figure may go on a public page is the publish decision’s call (GET /v1/tests/{id}/publish): it reads result_status and vehicle_supported, and also refuses a "final" result when the test has a finding, is more than 90 days old or has a newer result. Show a figure only when its publishable is true. Read result_status to understand why it is not, and to handle the cases below.
| Value | Meaning | What to do |
|---|---|---|
"final" |
A usable state of health. The normal case. | A figure the publish decision can allow. Show it when publishable is true: a finding on the test, its age or a newer test can still refuse it. |
"provisional" |
A number exists but is not safe to quote — a state of health above 100%, which means AVILOO’s reference data for the model isn’t final. | Do not publish the figure. Show the preview image only, where the publish decision allows it; its sentence says why no figure can be quoted. |
"inconclusive" |
AVILOO ran the test and could not determine battery health. There will never be a number for this test — it is finished, not pending. | Show nothing, or “battery health not determined”. Do not render a gauge, a zero, or a loading state. |
null |
Not answerable: the test is still running, it stopped before it finished (failed or cancelled), or it completed without a result recorded. | Treat as unknown. Never assume "final" from null. |
status: "completed" with soh_percent: null — indistinguishable from a test whose result was still landing. Integrations null-checked, rendered a blank card and waited for a number that was never coming. result_status names the state so you don’t have to infer it.
vehicle_supported. vehicle_supported describes the model (still in AVILOO validation); result_status describes this test’s result. A beta model routinely returns a perfectly usable "final" reading, and a fully-supported model can still return "inconclusive". Read both — neither substitutes for the other.
One branch for every case
test = get_test(test_id) decision = get_publish_decision(test_id) # GET /v1/tests/{id}/publish if decision["publishable"]: # The figure exactly as given, never rounded, with its grade and date. render_soh(decision["soh_display"], decision["band"]["label"], decision["tested_on"]) elif test.get("result_status") == "inconclusive": # Finished, no verdict. Never coming. Don't show a spinner. render_note("Battery health could not be determined") elif decision["image"]["publishable"]: # A provisional reading, a model still in validation, an older # test: the preview image only, never the figure. render_preview_image(test) else: # Still processing (result_status null), failed, or a finding on # the test: nothing. Never assume "final" from null. render_nothing()
{
"data": {
"id": 9184,
"status": "completed",
"battery": { "soh_percent": null },
"result_status": "inconclusive",
"vehicle_supported": true,
"warnings": []
}
}
Nulls & beta vehicles
We never omit keys — a value we don’t have is serialised as null rather than dropped, so the schema is stable. That means every consumer must null-check before rendering. These are the fields that are null often enough to matter in production:
| Field | Null when |
|---|---|
battery.estimated_range_miles | AVILOO has no validated range model for the vehicle. Common on vehicle_supported: false models. Also null, with the diagnostics.range typical and personal figures (*_miles and *_km), when the range AVILOO reports is inconsistent with the car’s own official figure (its typical range new is under 55% of its WLTP figure, or, where AVILOO gives no figure for the car new, its typical range now against WLTP now): such a range is withheld, not guessed. |
battery.cell_count | Always, today. The key is reserved: AVILOO’s result does not report a cell count. Do not build a UI that depends on it. |
battery.nominal_kwh, battery.capacity_kwh, battery.usable_nominal_kwh, battery.usable_capacity_kwh, battery.cell_variance | Sourced from the detailed measurement record — null on the same older tests where diagnostics is null. |
certificate_number | The test has no certificate (certificate_available is false). It can also be null for a while after certificate_available becomes true, until the number is given: read the test again later rather than treating the null as final. Otherwise it is Battery Health Check’s own certificate number, BHC-XXXX-XXXX-XXXX: twelve characters chosen at random from the digits and the capital letters except I, L, O and U. It carries no meaning (no date, no count), so never parse it. It is given once and never changes afterwards. It is not the number printed on the certificate documents, which is AVILOO’s own and is not returned as data. Check certificate_available to decide whether to offer a download, and key your records on the test id. |
vehicle.powertrain | The test was recorded before AVILOO began publishing the vehicle category. Otherwise BEV, PHEV or HEV; treat any other value as unknown. |
vehicle.registration | The test was performed against a VIN with no plate recorded — tests arrive from the box VIN-only, and the plate is added afterwards. Such a test cannot be found by ?registration=; it is still findable by vin. You may search by plate, but store vehicle.vin as your join key — plates transfer between vehicles, VINs don't. |
diagnostics | See the callout above. |
vehicle_supported | Neither of AVILOO's support signals is stored for the test. Note this is not the same as diagnostics being null — the top-level flag is answerable from either source, so it is populated in cases where the diagnostics block isn't. |
warranty | Exactly when warranty_state is null: no warranty state has been established for the test yet. Inside the block, issued_at, expires_at, mileage_limit and soh_threshold_percent are null until AVILOO has sent them, and compensation is null in production. |
warranty_reasons | Exactly when warranty_state is null. Note the distinction from [], which means there is nothing to explain — and which you can also see on an INELIGIBLE test, because codes about the account rather than the vehicle are not published. |
warnings | No evaluation record is held for the test. Note the distinction from [], which positively means “no warnings raised”. See Warnings. |
Handling a beta vehicle
A worked example. A Honda e tested in July 2026 returned a state of health of 102.9% with a null estimated range, and warnings: ["SOH_GREATER_THAN_100"] — all artefacts of the model still being in AVILOO validation. The test is genuine and the certificate is valid, but the result is provisional: publish the preview image only, never “102.9% battery health” (see Can you publish this number?). The publish decision already reads both signals, and refuses the figure with PROVISIONAL_OVER_100 or MODEL_IN_VALIDATION. Branch on it:
test = get_test(test_id) decision = get_publish_decision(test_id) # GET /v1/tests/{id}/publish if decision["publishable"]: render_full_summary(test, decision) # the figure as decision["soh_display"] gives it elif decision["image"]["publishable"]: # Beta model, or a provisional reading. The certificate is valid; # the figures are not quotable. The preview image only, no figure. render_preview_image(test) else: render_nothing()
A simple belt-and-braces check that catches the same class of result without reading either field: treat any soh_percent above 100, or any missing estimated_range_miles, as a signal to fall back to the preview image, with no figure.
/certificate(PDF) — your credential receives the anonymised copy, with the VIN hidden. Put it on a page only where the publish decision’simage.publishableis true./preview(JPEG) — VIN-redacted, single-page summary branded by AVILOO as “Battery Certificate Preview”. AVILOO’s certificate number printed on it is also masked. This is the one for a public car listing page, where the publish decision allows it: fetch the image and serve it yourself, never the signed link, which expires within the hour.
Get the publish decision for a test
Battery Health Check’s decision on what may be published about this test beside the car, and in which words. One call answers whether the figure may be quoted, why not when it may not, whether the preview image may be shown, ready-made advert copy, plain sentences to repeat as given, and what never to say.
Read publishable rather than deciding from the test fields yourself. The rules behind it (the result, the model, how recent the test is, whether a newer test exists, what the test found) are ours to keep right, and they can tighten without your code changing. The response contains no VIN.
Required scope: read:tests
Query parameters
| Parameter | Type | Description |
|---|---|---|
advert_mileage_miles | integer | Optional. The mileage on the advert the result will sit beside, in miles, a whole number from 0 to 1,000,000. When the advert is more than 1,000 miles past the reading at the test, or more than 500 miles below it, the result is not publishable for that advert. Anything else returns 400 invalid_field. |
include | string | Optional. Comma-separated opt-in blocks: dated_result and warranty_status, described below. Each block you name is always in the response, null when it does not apply. Without include the response is exactly as shown here. Anything else returns 400 invalid_field. |
Response 200 OK
{
"data": {
"object": "publish",
"version": "statements-v4",
"test_id": 48213,
"publishable": true,
"reason": "OK",
"reasons": [],
"result_status": "final",
"vehicle_supported": true,
"soh_display": "96.4%",
"band": { "scheme": "aviloo", "code": "excellent", "label": "Excellent health", "range": "Judged by AVILOO against similar vehicles", "short": "Excellent", "headline": "EXCELLENT HEALTH - NO ABNORMALITIES DETECTED", "source": "aviloo_certificate" },
"tested_on": "2026-09-21",
"valid_until": "2026-12-20T10:12:00Z",
"current_test_id": 48213,
"superseded_by": null,
"image": { "publishable": true, "reason": "OK", "available": true, "path": "/v1/tests/48213/preview" },
"copy": {
"seller_highlight": "Battery health 96.4% (AVILOO: Excellent), Sep 2026",
"attention_grabber": "Battery health 96.4% (Sep '26)",
"description": "Battery tested 21 September 2026 with Battery Health Check: state of health 96.4%. AVILOO's grade, against similar vehicles: Excellent health. Every battery check the test reported was OK. The figure describes the battery on the test date."
},
"copy_withheld_reason": null,
"statements": [
{ "id": "result", "text": "This car's battery was tested on 21 September 2026. Its state of health was 96.4%." },
{ "id": "grade", "text": "AVILOO's grade, against similar vehicles: Excellent health." },
{ "id": "checks", "text": "Every battery check the test reported was OK." },
{ "id": "dated", "text": "The figure describes the battery on the test date." }
],
"must_not_say": [
{ "code": "NO_ROUNDING", "text": "Quote the figure exactly as given (96.4%); never round it up." },
{ "code": "DATE_REQUIRED", "text": "Always give the test date with the figure." },
…
],
"warnings": []
},
"meta": { "request_id": "req_a1b2c3d4e5f6" }
}
When the test cannot be published, soh_display, band, valid_until and copy are null, statements holds one sentence explaining reason (none outside the UK; see Outside the UK below), and must_not_say gains NO_FIGURE. A figure above 100% looks like this:
{
"publishable": false,
"reason": "PROVISIONAL_OVER_100",
"reasons": ["PROVISIONAL_OVER_100", "AVILOO_FINDING"],
"result_status": "provisional",
"soh_display": null,
"band": null,
"image": { "publishable": true, "reason": "OK", "available": true, "path": "/v1/tests/48214/preview" },
"copy": null,
"statements": [
{ "id": "reason", "text": "The battery was tested on 21 September 2026, but the result is not yet confirmed for this model, so no figure can be quoted." }
],
…
}
Reasons
reasons lists every reason that applies, in this order, and reason is the first. Treat a code you do not recognise as a reason not to publish.
| Code | Meaning | Image |
|---|---|---|
AMBIGUOUS_REGISTRATION | Batch lookup only (publish and current_publish): the vehicle was looked up by a registration that matched tests of more than one car (ambiguous: true), so this test may be another car’s. Send the VIN. This endpoint, which names one test by id, never returns it. | No |
NO_RESULT_YET | The test is still running. | No |
TEST_DID_NOT_COMPLETE | The test stopped before it finished. | No |
INCONCLUSIVE | The test finished without a figure. None will follow. | No |
PROVISIONAL_OVER_100 | The figure is above 100%: the model’s reference data is not final. | Yes |
DISPUTED | The result is being reviewed. | No |
SUPERSEDED | A newer completed test of the same car has a figure; superseded_by names it. | No |
SAFETY_FINDING | The test reported a possible safety issue with the battery. | No |
AVILOO_FINDING | The test reported a warning about the battery. The certificate gives the detail. | Yes |
RESULT_NOT_RECORDED | The full result was not recorded for this test. | Yes |
CHECKS_NOT_ALL_OK | Not every battery check was OK. | Yes |
MODEL_IN_VALIDATION | The model is still being validated: show the image, not your own rendering of the figure. | Yes |
MODEL_SUPPORT_UNKNOWN | Whether the model is validated was not recorded for this test. | Yes |
TEST_OLDER_THAN_90_DAYS | The test is more than 90 days old, or has no date. | Yes, when dated |
ADVERT_MILEAGE_PAST_TEST | The advert’s mileage is more than 1,000 miles past the reading at the test. | Yes |
ADVERT_MILEAGE_BELOW_TEST | The advert’s mileage is more than 500 miles below the reading at the test. | Yes |
image.publishable is true only when every reason that applies allows the image, so it can be true while publishable is false. Fetch the image from image.path, the same signed-link endpoint described in the preview image; image.available says whether it is ready yet. The path already starts /v1/, so join it to the host, https://api.batteryhealthcheck.co.uk, not to the /v1 base URL. Ask for the image only when image.publishable is true: the preview endpoint serves any test’s image that is ready, including one this decision rules out, so the decision is what keeps it off a page. The same goes for the anonymised certificate, GET /v1/tests/{id}/certificate?variant=anonymised: it carries the same result as the preview image, so put it on a page only when image.publishable is true, whatever its public_display says.
Publishing it
- Use the words as given.
copyfits the Auto Trader slots (seller_highlightat most 55 characters,attention_grabberat most 30) anddescription.statementsare for a person or an assistant to repeat. Every number in them comes from the test. - Quote the figure exactly as
soh_displaygives it, with its date. It is floored to one decimal place and never rounded up. - Put no text on car photos. The words go in the advert text, never on a photo, and any image you publish, such as AVILOO’s preview, goes on the page unaltered. The one exception is AVILOO’s own AVILOO Certified label, where AVILOO has agreed its use with you and the site you publish on allows it: it may go on the car’s photos, unaltered, never on the preview image, and only while
image.publishableis true (NO_AVILOO_MARKS). - Respect
must_not_say. Branch on its codes; thetextis the rule in plain words. - The grade is AVILOO’s, named as AVILOO’s.
bandis AVILOO’s own grade for the test, exactly as its certificate prints it (for example “GOOD HEALTH”), judged against similar vehicles. Show it as AVILOO’s, for example “AVILOO: Good health”, never as your own or Battery Health Check’s, and never beside a grade on another scale. While we have not yet read AVILOO’s grade,bandisnullandmust_not_sayholdsNO_GRADE: show the figure and its date alone. - Refresh it. The decision lapses at
valid_until, 90 days after the test. Fetch it again whenbhc.test.completedorbhc.test.warranty_changedarrives for the same car, because a newer test can replace this one. - Outside the UK,
copyisnull,statementsis empty, whether or not the test is publishable, andcopy_withheld_reasonisREGION_NOT_REVIEWED: our English wording has not been reviewed for that market. The figure itself is still publishable, andmust_not_sayis returned in full, so write your own words to the same rules.
Optional blocks: include
dated_result: a result more than 90 days old. After 90 days a result no longer describes the car today, so the decision above says TEST_OLDER_THAN_90_DAYS and withholds the figure. If the car is still for sale, you may show the figure as a dated, historical result instead. dated_result is filled only when the result is final and its age is the only reason it cannot be published; for anything else it is null, and the decision above stands.
"dated_result": {
"soh_display": "94.2%",
"tested_on": "2026-06-21",
"age_days": 121,
"statement": "This car's battery was tested on 21 June 2026, more than 90 days ago. Its state of health was 94.2% on that date.",
"statement_withheld_reason": null,
"rules": [
{ "code": "EXCEPTION_TO_NO_FIGURE", "text": "This figure is the one exception to NO_FIGURE in must_not_say: show it only as given here, as a dated result." },
{ "code": "DATE_BESIDE_FIGURE", "text": "Show the test date right beside the figure, at least as prominent as the figure itself." },
{ "code": "NOT_CURRENT", "text": "Do not present the figure as the battery's condition today: it describes the battery on the test date." },
{ "code": "NO_GRADE", "text": "Do not show a grade for a result more than 90 days old." },
{ "code": "NO_ROUNDING", "text": "Never round a battery figure up; quote it exactly as given." }
]
}
age_days is the whole days elapsed since the test, so it is always at least 90 here. Outside the UK, statement is null and statement_withheld_reason is REGION_NOT_REVIEWED; the figure and date may still be shown, under the same rules. The block does not change publishable, the image verdict or must_not_say above (which still carries NO_FIGURE): its first rule, EXCEPTION_TO_NO_FIGURE, makes it the only figure you may show for such a test, and only in this dated form.
warranty_status: the AVILOO Battery Warranty. When the car’s AVILOO Battery Warranty is active, as of our last check with AVILOO, this block gives the one line you may show about it, word for word, with a link to the terms. We re-check active warranties every day or two. The block is null, so take the line down, for any other state, when our last check is more than 4 days old, when the test is disputed or reported a possible safety issue, and when the test is not the car’s current test (current_test_id): ask for that one instead.
"warranty_status": {
"state": "ACTIVE",
"as_of": "2026-10-20T06:00:00Z",
"line": "AVILOO Battery Warranty: active on 20 October 2026, according to AVILOO. Terms are set by Aviloo GmbH.",
"terms_url": "https://aviloo.com/en/aviloo-warranty",
"rules": [
{ "code": "EXCEPTION_TO_NO_WARRANTY_CLAIM", "text": "This line is an exception to NO_WARRANTY_CLAIM and NO_AVILOO_MARKS in must_not_say: …" },
{ "code": "WORD_FOR_WORD", "text": "Show this line word for word, with its date and a link to the terms. …" },
{ "code": "REMOVE_WHEN_NOT_ACTIVE", "text": "Take the line down when this block is null: …" }
]
}
The line is the only warranty wording you may use; NO_WARRANTY_CLAIM and NO_AVILOO_MARKS in must_not_say still govern everything else. Do not describe the cover, its value or what it means for a buyer, and do not add AVILOO’s logo to it. The terms are the provider’s to state: link to them.
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_field | advert_mileage_miles is not a whole number from 0 to 1,000,000, or include names something other than dated_result and warranty_status. |
| 403 | insufficient_scope | The token does not carry read:tests. |
| 404 | not_found | No such test, or, with global reach, a test of a vehicle you have not looked up by vin or registration. |
| 429 | too_many_requests | Rate limited. Wait the seconds in the Retry-After header (never more than 60). |
Get the certificate (PDF) — anonymised version, VIN hidden
variant this returns the certificate with the VIN hidden, and says so: the response carries "variant": "anonymised" and "public_display": true. The full version shows the VIN, and publishing a VIN on an advert is not something the dealer agreed to; it also carries identifiers reserved for the dealer’s own record. So it goes to dealer credentials only: ?variant=full answers 403 variant_not_permitted. On the listing, use the preview image or this anonymised version.
Returns a 1-hour signed URL for the multi-page AVILOO PDF certificate in its anonymised version, which hides the VIN. Every certificate also has a full version, which prints the VIN; it is for dealer credentials only, so your credential never receives it.
Required scope: read:certificates
Query parameters
| Parameter | Type | Description |
|---|---|---|
variant | string | Optional. full or anonymised; anonymized is accepted too, and case is ignored. The default is full for a dealer credential and anonymised for a platform, marketplace or sandbox credential, which receives 403 variant_not_permitted for full. Anything else is 400 invalid_field with field: "variant", so a mistyped request never receives the full version by default. |
Every response to your credential, with or without ?variant=anonymised, carries variant (the version returned, always anonymised) and public_display (true) beside the four keys every certificate response has. certificate_number is Battery Health Check’s own reference for the test’s certificate; it is not AVILOO’s certificate number printed on the document. public_display describes the version, not the test: true says the VIN is hidden, never that this test’s result may be shown.
The anonymised certificate goes on a public page only when the test’s publish decision says image.publishable: true, the same rule as the preview image, which carries the same result. This endpoint serves it whatever the decision says, including for an inconclusive test, a safety finding or a disputed result, so the decision is what keeps it off a page.
Each version is cached separately, so one can be ready while the other is not. If AVILOO does not supply the anonymised version for a test, ?variant=anonymised answers 404 not_found rather than 409, and we ask AVILOO again after a day.
Check the test first. Each test’s certificate_documents lists both versions with their path and public_display, as warranty.documents does for the warranty (see Get a test). Its available is certificate_available for both versions: it says a version can be requested, not that it is stored, so the first request for a version not stored yet is the 409 below. To a platform, marketplace or sandbox credential the full item is always available: false, with path null and withheld_reason: "DEALER_CREDENTIALS_ONLY".
Response 200 OK — cached, with or without ?variant=anonymised
{
"data": {
"url": "https://files.batteryhealthcheck.co.uk/certificates/.../X-Amz-Signature=...",
"expires_at": "2026-05-27T12:47:00Z",
"content_type": "application/pdf",
"certificate_number": null,
"variant": "anonymised",
"public_display": true
},
"meta": { "request_id": "req_e2a4f6c8b1d3" }
}
Response 409 Conflict — not cached yet
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error": {
"code": "certificate_not_ready",
"message": "Certificate is not yet available — retry shortly",
"request_id": "req_e2a4f6c8b1d3",
"retry_after_seconds": 30
}
}
Response 400 Bad Request — unknown variant
{
"error": {
"code": "invalid_field",
"message": "variant must be full or anonymised.",
"request_id": "req_c5e7a9b1d3f5",
"field": "variant"
}
}
Response 403 Forbidden — ?variant=full on a platform, marketplace or sandbox credential
Checked before the test is looked up, so it says nothing about whether the test exists. No scope changes it: send no variant, or variant=anonymised.
{
"error": {
"code": "variant_not_permitted",
"message": "This credential receives the anonymised copy only: the full copy is for dealer credentials. Omit variant, or send variant=anonymised.",
"request_id": "req_a8c1e3f5b7d9",
"field": "variant",
"available_variants": ["anonymised"]
}
}
Get the public-facing certificate image (JPEG)
Returns a 1-hour signed URL for a JPEG image — the AVILOO-branded “Battery Certificate Preview”.
Single-page summary showing State of Health %, range, vehicle make/model, mileage, test date, and the testing dealer. The VIN is not on the image, and AVILOO’s certificate number printed on it is masked (e.g. 8C1E4F2A-6B3D-4E9A-****-************). A QR code on the image links back to AVILOO's hosted validation page.
Designed for public display: no personally-identifying vehicle data leaks to the public. Re-host it, never hot-link it: the URL expires after an hour, so download the JPEG once, store it on your own storage or CDN, and put your own copy in the listing’s <img> (see Example C).
Required scope: read:certificates
Response 200 OK
{
"data": {
"url": "https://files.batteryhealthcheck.co.uk/previews/.../X-Amz-Signature=...",
"expires_at": "2026-05-27T12:47:00Z",
"content_type": "image/jpeg"
},
"meta": { "request_id": "req_f3g5h7i9k1m3" }
}
- Embedding on a public car listing page →
/preview(JPEG), and if you want the PDF too,/certificate?variant=anonymised(VIN hidden); either one only when the test’s publish decision saysimage.publishable: true - Customer download / sales record / internal tool →
/certificate(PDF), the full version, which shows the VIN: on a dealer credential only, because platform and marketplace credentials receive the anonymised version - Raw values for your own UI components →
GET /tests/{id}JSON
manage:webhooks, which is granted per marketplace rather than issued by default: a lookup-only integration does not need it, and most start without it. To have it added to your credential, ask your account manager; without it these calls return 403 insufficient_scope.
- With it, we send you
bhc.test.completed,bhc.test.failedandbhc.test.warranty_changedfor a car you have looked up in the last 120 days, including a later test of the same car, such as a retest or a first result after an inconclusive one. - Looking a car up by VIN always counts. Looking it up by registration counts only when that registration matched this car’s VIN and no other car in our records carries it, so look cars up by VIN if you want every update.
- Looking a car up again restarts its 120 days. A car you have not looked up for 120 days sends no events until you look it up again.
- You receive no events for cars you have not looked up, and none for a test you could not read by id.
- The event body is what
GET /v1/tests/{id}returns you: the test object and the dealer’s id and name. Join onvehicle.vin.
Manage webhook subscriptions
See Webhooks below for event payloads and signing. The endpoints to manage them:
Required scope: manage:webhooks
Register a webhook
curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/bhc/v1",
"events": ["bhc.test.completed", "bhc.test.failed"]
}'
Response 201 Created:
{
"data": {
"id": 42,
"url": "https://hooks.example.com/bhc/v1",
"events": ["bhc.test.completed", "bhc.test.failed"],
"secret": "whsec_8f9a3b2c...",
"disabled_at": null,
"consecutive_failures": 0,
"last_success_at": null,
"last_attempt_at": null,
"last_failure": null,
"created_at": "2026-10-14T09:15:02Z"
},
"meta": { "request_id": "req_c5d7e9f1a3b5" }
}
The response is the only time secret is returned. Store it immediately: we cannot show it again. GET /v1/webhooks and GET /v1/webhooks/{id} return the same object without it.
events is any of bhc.test.completed, bhc.test.failed and bhc.test.warranty_changed. Anything else is refused with 422 validation, and the error lists the events you may use as allowed.
URL rules
A URL that breaks one of these is refused with 422 invalid_webhook_url, and message says why:
https://only, and at most 500 characters.- Not one of Battery Health Check’s own domains.
- Not a private, loopback, link-local or otherwise reserved address, whether you give an IP address or a host name that resolves to one.
- The host name has to answer a DNS lookup within two seconds. A name that does not exist yet is accepted; its deliveries fail until it does.
We do not follow redirects; a 3xx response counts as a failed delivery. Register the final URL: the rules above are checked on the URL you register.
At most five
A credential may have five enabled webhooks. A sixth is refused with 422 webhook_limit_reached, whose body carries limit. A disabled webhook does not count; delete it to tidy up.
Delete a webhook
DELETE /v1/webhooks/{id} deletes the webhook outright and answers 204 No Content. Its queued deliveries are not sent. To use the URL again, register it again: you get a new id and a new secret.
When a webhook is disabled
A webhook whose deliveries fail 50 times in a row, across all its deliveries, is disabled automatically: nothing more is sent to it, and its queued retries stop. We do not email you about it. GET /v1/webhooks shows it, so check it regularly, for example once an hour:
disabled_atis set from the moment it is disabled;consecutive_failurescounts the failures in a row, and goes back to0on any success;last_attempt_atandlast_success_atsay when we last tried and last succeeded;last_failuresays what went wrong on the most recent failed attempt:{"at", "http_status", "error_code"}, for example{"at": "2026-10-14T10:02:11Z", "http_status": 503, "error_code": "http_error"}.http_statusis null when your endpoint never answered. It stays after a later success, so compareatwithlast_success_at. Null until a failure is recorded.
error_code | Meaning |
|---|---|
http_error | Your endpoint answered with a status other than 2xx or 3xx (see http_status). |
redirect_not_followed | It answered 3xx. We never follow redirects. |
timeout | No answer within 10 seconds. |
tls_error | The TLS handshake failed, for example an expired or untrusted certificate. |
connection_failed | The host name did not resolve, or now resolves to an address we never deliver to (private, loopback, link-local or reserved, the same rule as when you register), or the connection was refused or reset. |
transport_error | Any other failure to send the request. |
internal_error | On our side, not your endpoint’s. Contact support with the webhook id. |
Turning it back on: a disabled webhook cannot be re-enabled. Fix the receiver, prove it, then DELETE the disabled webhook and register the URL again, which gives you a new secret. Deliveries the old webhook missed are not re-sent to the new one, so recover them by looking each listed car up again (GET /v1/tests?vin= or ?registration=, with updated_since= from the time of the last success if you like; updated_since on its own is refused for a marketplace).
Rotating a webhook secret
A secret cannot be changed in place, and we never show it twice. To rotate it, register a second webhook with the new secret, at a different path on your receiver (for example /bhc/v2), so your code knows which secret to check. Deploy, confirm deliveries verify at the new path, then DELETE the old webhook. While both exist, every event reaches both, each with its own webhook-id and signature, so upsert on the test id as usual. The second webhook counts towards your five.
201 whether or not anything will ever reach you — a subscription can look perfectly healthy and still never fire. POST /v1/webhooks/{id}/test sends a real, signed delivery immediately, so you can confirm connectivity, TLS and your signature verification before you depend on it.
curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks/42/test \ -H "Authorization: Bearer $TOKEN"
It works even if the endpoint is subscribed to nothing useful yet — which is exactly the case worth catching. It answers 200 with {"queued": true, "event": "bhc.webhook.test", "endpoint_id": 42, …}; the delivery itself is asynchronous. A disabled webhook answers 400 invalid_request.
The answer does not say whether your endpoint accepted the delivery: that happens after the response. Watch your receiver. Afterwards GET /v1/webhooks/{id} shows last_attempt_at, last_success_at, consecutive_failures and, for the most recent failed attempt, last_failure {"at", "http_status", "error_code"}, with the error_code values in the table above. Your receiver’s own logs, or the absence of any request in them, say the rest.
What the test event looks like
It is not a synthetic bhc.test.completed. It has its own event type and carries no vehicle or battery data at all, so it can never be mistaken for a real result and published:
{
"event": "bhc.webhook.test",
"data": {
"message": "This is a test event from Battery Health Check. …",
"test_event": true,
"endpoint_id": 42,
"sent_at": "2026-08-17T13:22:14Z",
"triggered_by": "partner_api"
}
}
2xx and ignore the body — that alone proves the pipe. bhc.webhook.test is not subscribable: you cannot register for it, and it is never fanned out by a real domain event, so it only ever arrives because you asked for it. If your handler switches on event, let unknown types fall through to a 200 rather than erroring — that is the correct behaviour for every future event type too.
Re-send failed deliveries
POST /v1/webhooks/{id}/replay re-sends this webhook’s deliveries that have not succeeded, from since onwards, each with a fresh set of retries. Deliveries that succeeded are never re-sent.
curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks/42/replay \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "since": "2026-10-14T00:00:00Z", "event_types": ["bhc.test.completed"] }'
| Field | Description |
|---|---|
since | Required. ISO 8601; a time without an offset is read as UTC. At most 30 days back: an earlier value is treated as 30 days ago. |
event_types | Optional. Up to 50 event type names; only deliveries of those types are re-sent. An unknown name is refused with 400 invalid_field. |
It answers 202 Accepted with {"count": …, "since": …}: how many deliveries were queued, and the since actually used. At most 5,000 go in one call; when there were more, the body adds "truncated": true and total_matching, so call again with a later since. A replay of a disabled webhook queues deliveries that are then not sent; delete and re-register it first.
Worked Example
End to end, runnable, in three languages. The responses match what you would see in production.
C. Embedding battery test data on a car listing page
Scenario: Your dealer-website team wants to show battery health on every used-EV listing. A customer browsing a 2022 Peugeot e-208 should see the SoH%, estimated range and the certificate image without having to call the dealer.
You have the VIN on every listing (from your inventory feed). You don't know which dealer ran the test — could be Leeds, could be any of your branches. The lookup endpoint solves that.
vin= for registration= in Step 1 — everything downstream is identical. Before you do, read the plate-vs-VIN guidance: a plate lookup can return two different vehicles if the registration has been transferred, and tests with no plate on record won't be found at all. For a listing site that renders unattended, the VIN is the safer key.
read:tests and read:certificates, which a marketplace credential holds. Keep it server-side — never in browser code.
Step 1. Look up the car’s current test by VIN
On your listing page's server-side render (or via your inventory backend). current=true asks us for the test that speaks for the car: its most recent completed test with a battery-health figure or, when no completed test has one, its most recent test. Never take the newest row of an unfiltered list instead: a failed or inconclusive retest is newer than the good result it must not hide.
import requests
def get_battery_data_for_vin(vin):
token = get_access_token() # cached, see auth section
resp = requests.get(
"https://api.batteryhealthcheck.co.uk/v1/tests",
headers={"Authorization": f"Bearer {token}"},
params={"vin": vin, "current": "true"},
timeout=5,
)
current = resp.json()["data"] # current=true: the car's current test, the one to show
return current[0] if current else None # newest first; None if no test exists
async function getBatteryDataForVin(vin) {
const token = await getAccessToken();
const url = new URL("https://api.batteryhealthcheck.co.uk/v1/tests");
url.searchParams.set("vin", vin);
url.searchParams.set("current", "true");
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${token}` }
});
const { data: current } = await resp.json(); // current=true: the car's current test
return current.length ? current[0] : null; // newest first; null if no test exists
}
<?php
function get_battery_data_for_vin($vin) {
$token = get_access_token();
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://api.batteryhealthcheck.co.uk/v1/tests?"
. http_build_query(["vin" => $vin, "current" => "true"]),
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$current = $body["data"]; // current=true: the car's current test
return $current ? $current[0] : null; // newest first; null if no test exists
}
Step 2. Choose how to display it
You now have the car’s current test. Before you show anything from it, ask for its publish decision, GET /v1/tests/{id}/publish: it says whether the figure may be published (publishable) and whether the image may (image.publishable), and gives the figure as it may be quoted. Three useful ways to surface what it allows:
Option A — Show key values as text
Best for clean, brand-consistent listings. Write your own HTML, only when the decision’s publishable is true: the figure exactly as its soh_display gives it (never round it), its grade and date, and other values from the test — guarding each, since any of them can legitimately be null (see Nulls & beta vehicles):
{% if decision.publishable %}
<div class="battery-summary">
<h3>Battery Health Check</h3>
<dl>
<dt>State of Health</dt>
<dd>{{ decision.soh_display }}{% if decision.band %} (AVILOO: {{ decision.band.label }}){% endif %}</dd>
{% if test.battery.estimated_range_miles %}
<dt>Estimated range when tested</dt>
<dd>{{ test.battery.estimated_range_miles }} miles (typical, at the battery health measured)</dd>
{% endif %}
<dt>Tested</dt>
<dd>{{ decision.tested_on }}</dd>
</dl>
</div>
{% endif %}
Show the range, if at all, as here: the test’s estimate on its date, never a promise of what the car will do. Every decision’s must_not_say carries NO_RANGE_PROMISE. estimated_range_miles is null when no trustworthy figure is held; show no range then. For the odometer, use vehicle.odometer.miles, not vehicle.mileage_km (why).
Render your own numbers only when publishable is true. When it is false, show the certificate image (Option B) if image.publishable is true, and otherwise nothing; for an inconclusive test (INCONCLUSIVE in reasons), at most “battery health could not be determined”. Treat a reason you do not recognise as a reason not to publish. See the publish decision.
The publish decision reads test.result_status (only "final" can ever be quoted: see Can you publish this number?) and test.vehicle_supported (a model still in AVILOO validation: see The diagnostics block and Warnings). It also refuses a final result from a supported model when the test has a finding, is more than 90 days old or has a newer result, so those two fields on their own would put a figure on cars it must not appear on.
Option B — Show the certificate image (JPEG)
Best when you want the official image on the listing, and the one to use when the decision allows the image but not the figure: the VIN removed, AVILOO’s certificate number masked, and a QR code to AVILOO’s validation page. Show it when the decision’s image.publishable is true. GET /v1/tests/{id}/preview returns a signed link that expires after an hour, so never put that link on your page. Download the JPEG once, store it on your own storage or CDN, and serve your copy:
def rehost_preview(test_id, token):
resp = requests.get(
f"https://api.batteryhealthcheck.co.uk/v1/tests/{test_id}/preview",
headers={"Authorization": f"Bearer {token}"},
timeout=5,
)
if resp.status_code == 409: # not rendered yet: try again in retry_after_seconds
return None
resp.raise_for_status()
image = requests.get(resp.json()["data"]["url"], timeout=30) # expires in an hour
image.raise_for_status()
# Your own storage; key it on the test id and its updated_at.
return cdn_put(f"bhc/{test_id}.jpg", image.content, "image/jpeg")
Then in the listing template, your own URL:
<img src="{{ battery_image_url }}"
alt="Battery certificate preview"
loading="lazy"
style="max-width: 400px;">
Step 3. Handle the “no test exists” case
Not every car on your forecourt has been tested yet. Decide upfront what your listing shows when get_battery_data_for_vin() returns None:
- Hide the battery section entirely
- Show “Battery test scheduled” with the dealer's next available appointment
- Show a generic “Pre-owned EV — Battery Health Check available on request” CTA
Putting it together
A typical flow, run when a listing is created and again whenever the test changes (not on every page view). The figure and the image come from the publish decision; the test supplies the rest:
def battery_section_for(vehicle):
test = get_battery_data_for_vin(vehicle.vin) # Step 1: the car's current test
if not test or test["status"] != "completed":
return None # Step 3: no result to show
token = get_access_token()
# What may be shown is the publish decision's call, never your own
# reading of result_status and vehicle_supported: it also refuses a
# final result with a finding on the test, one more than 90 days old,
# and one a newer test of the car replaces.
resp = requests.get(
f"https://api.batteryhealthcheck.co.uk/v1/tests/{test['id']}/publish",
headers={"Authorization": f"Bearer {token}"},
timeout=5,
)
resp.raise_for_status()
decision = resp.json()["data"]
publishable = decision["publishable"]
image_url = None
if decision["image"]["publishable"]:
image_url = rehost_preview(test["id"], token) # None: try again later
return {
"test_id": test["id"],
"updated_at": test["updated_at"], # refresh when this moves
"soh_display": decision["soh_display"] if publishable else None, # as given
"band": ("AVILOO: " + decision["band"]["label"] # AVILOO's grade, named
if publishable and decision["band"] else None),
"range_miles": test["battery"]["estimated_range_miles"] if publishable else None,
"tested_on": decision["tested_on"],
"recheck_at": decision["valid_until"], # the figure lapses then
"battery_image_url": image_url, # your own copy, or None
"not_determined": "INCONCLUSIVE" in decision["reasons"],
}
id and its updated_at, never on certificate_number, which can be null. To keep it current, take the webhooks (bhc.test.completed and bhc.test.warranty_changed, sent for the cars you have looked up in the last 120 days) or look each listed car up again once a day, and replace your copy when updated_at has moved or a newer test has appeared. A publishable figure also lapses at the decision’s valid_until, 90 days after the test: look the car up again then. With that in place your listing renders fast and does not depend on our availability.
Webhooks
Subscribe to events and we'll push them to your endpoint within seconds. Signed using the Standard Webhooks scheme (HMAC-SHA256, base64-encoded). A delivery that fails is retried three times over about seven minutes; a webhook that fails 50 times in a row is switched off (see Retries).
Event catalog (v1)
| Event | Fires when | Typical use |
|---|---|---|
bhc.dealer.activated |
A dealer is provisioned through the API (dealers created that way start in the active state). Dealer-group credentials only. |
Update your CRM, trigger your own welcome flow |
bhc.test.completed |
A test result arrives, certificate is rendered, status moves to completed |
Pull the certificate, attach to the vehicle record, notify the customer |
bhc.test.failed |
A test was started but couldn't complete (interrupted, cancelled, hardware fault) | Refund the customer if you charged up-front; schedule a retest |
bhc.test.warranty_changed |
The AVILOO battery warranty on an already-reported test moves to a new state: issued (PENDING → ACTIVE), expired, claimed, or withdrawn. Not sent for the state a test first arrives with — that is already on bhc.test.completed. Changes are picked up by a daily check, so this can arrive up to a day after the change at AVILOO. |
Fetch the publish decision again with include=warranty_status and add or take down the warranty line it gives; re-read warranty_available before offering the document |
The three bhc.test.* events carry the same payload, shown under Event envelope. You receive only the events your webhook is subscribed to.
bhc.dealer.activated event exists.
bhc.test.completed, bhc.test.failed and bhc.test.warranty_changed — and their deliveries carry a slim data.dealer object of {id, name} in place of the full dealer record shown below, and a data.test object exactly as GET /v1/tests/{id} gives that credential: the full items of its document lists are withheld (withheld_reason "DEALER_CREDENTIALS_ONLY"), because the full certificate and warranty copies are for dealer credentials. Everything else in the envelope — signing, retries, replay — is identical.
Event envelope
{
"event": "bhc.test.completed",
"data": {
"test": {
"id": 9182,
"internal_reference": "BHC-TEST-009182",
"dealer_id": 247,
"unit_id": 412,
"status": "completed",
"vehicle": {
"registration": "AB23 CDE",
"vin": "VR3UHZKXZNT123456",
"make": "Peugeot",
"model": "e-208",
"year": 2022,
"mileage_km": 29644,
"odometer": { "value": 47707, "unit": "km", "km": 47707, "miles": 29644 }
},
"battery": {
"soh_percent": 91.4,
"capacity_kwh": 45.7,
"nominal_kwh": 50.0,
"estimated_range_miles": 152,
"cell_count": null,
"cell_variance": 0.012,
"usable_capacity_kwh": 41.0,
"usable_nominal_kwh": 45.0
},
"tested_at": "2026-05-26T14:22:08Z",
"results_received_at": "2026-05-26T14:25:09Z",
"certificate_number": "BHC-7K2M-Q9XD-4HTA",
"certificate_available": true,
"preview_available": true,
"dealer": { "id": 247, "name": "Example Motors Leeds" },
"result_status": "final",
"vehicle_supported": true,
"warnings": [],
"diagnostics": { ... full measurement record ... }
},
"dealer": { ... full dealer object ... }
}
}
The test object in the payload is byte-for-byte the same shape returned by GET /v1/tests/{id}, diagnostics and warnings included — so a beta vehicle (vehicle_supported: false) or a flagged reading can be detected at delivery time, without a follow-up call.
The envelope has exactly two top-level keys: event (the event type string) and data (the payload). The unique event identifier for idempotency is delivered in the webhook-id HTTP header — not as a field inside the JSON body. Persist that header value when you record the event, and reject re-deliveries with the same webhook-id.
Signature scheme (Standard Webhooks)
We implement the Standard Webhooks spec. If your stack already has a Standard Webhooks verifier library, you can use it as it is with your webhook’s secret; otherwise the examples below are complete.
Headers we send
| Header | Description |
|---|---|
webhook-id | Unique identifier for this delivery (URL-safe base64, ~22 chars). Use this for idempotency. |
webhook-timestamp | Unix epoch seconds (string). |
webhook-signature | A space-separated list of versioned signatures, each v1,<base64-hmac>. We send one today; the format allows several, so accept the delivery if any one of them verifies. |
content-type | application/json |
User-Agent | BatteryHealthCheck-Webhook/1.0. Informational: verify the signature, never this header. |
How we compute the signature
The secret you receive at registration is base64-encoded behind a whsec_ prefix (e.g. whsec_8f9a3b2c...). Decode the base64 portion to recover the raw 32-byte key, then:
- Build the signed message:
<webhook-id> + "." + <webhook-timestamp> + "." + <raw body bytes>. - Compute
HMAC-SHA256(decoded_secret, signed_message). - Base64-encode the digest (standard alphabet, with padding).
- Send the header value as
v1,<base64>.
Verifying signatures
import base64, hmac, hashlib, time from flask import request, abort SECRET = "whsec_8f9a3b2c..." # exact value from /v1/webhooks creation TOLERANCE = 300 # 5 min replay window def _key_bytes(secret): if not secret.startswith("whsec_"): raise ValueError("secret must start with whsec_") return base64.b64decode(secret[len("whsec_"):]) @app.route("/webhooks/bhc", methods=["POST"]) def bhc_webhook(): msg_id = request.headers.get("webhook-id", "") ts_str = request.headers.get("webhook-timestamp", "0") sig_hdr = request.headers.get("webhook-signature", "") body = request.get_data() # RAW bytes — never re-serialise try: ts = int(ts_str) except ValueError: abort(400, "bad timestamp") if abs(time.time() - ts) > TOLERANCE: abort(400, "stale timestamp") signed = f"{msg_id}.{ts}.".encode() + body expected = "v1," + base64.b64encode( hmac.new(_key_bytes(SECRET), signed, hashlib.sha256).digest() ).decode() # The header is a space-separated list: accept any one that matches if not any(hmac.compare_digest(expected, part) for part in sig_hdr.split(" ")): abort(400, "invalid signature") event = request.get_json() handle_event(msg_id, event) # idempotent on webhook-id return "", 200
const crypto = require("crypto");
const SECRET = "whsec_8f9a3b2c...";
const TOLERANCE = 300;
function keyBytes(secret) {
if (!secret.startsWith("whsec_")) {
throw new Error("secret must start with whsec_");
}
return Buffer.from(secret.slice("whsec_".length), "base64");
}
app.post("/webhooks/bhc",
express.raw({ type: "application/json" }),
(req, res) => {
const msgId = req.headers["webhook-id"] || "";
const tsStr = req.headers["webhook-timestamp"] || "0";
const sigHdr = req.headers["webhook-signature"] || "";
const body = req.body; // Buffer of RAW bytes
const ts = parseInt(tsStr, 10);
if (!Number.isFinite(ts) ||
Math.abs(Date.now()/1000 - ts) > TOLERANCE) {
return res.status(400).send("stale timestamp");
}
const signed = Buffer.concat([
Buffer.from(`${msgId}.${ts}.`),
body,
]);
const expected = "v1," + crypto
.createHmac("sha256", keyBytes(SECRET))
.update(signed).digest("base64");
const ok = sigHdr.split(" ").some(part => {
const a = Buffer.from(expected);
const b = Buffer.from(part);
return a.length === b.length && crypto.timingSafeEqual(a, b);
});
if (!ok) return res.status(400).send("invalid signature");
handleEvent(msgId, JSON.parse(body)); // idempotent on webhook-id
res.status(200).send();
}
);
<?php
$secret = "whsec_8f9a3b2c...";
$tolerance = 300;
$msgId = $_SERVER["HTTP_WEBHOOK_ID"] ?? "";
$tsStr = $_SERVER["HTTP_WEBHOOK_TIMESTAMP"] ?? "0";
$sigHdr = $_SERVER["HTTP_WEBHOOK_SIGNATURE"] ?? "";
$body = file_get_contents("php://input"); // RAW bytes
$ts = (int)$tsStr;
if (abs(time() - $ts) > $tolerance) {
http_response_code(400); exit("stale");
}
if (strpos($secret, "whsec_") !== 0) {
http_response_code(500); exit("bad secret");
}
$key = base64_decode(substr($secret, strlen("whsec_")));
$signed = $msgId . "." . $ts . "." . $body;
$expected = "v1," . base64_encode(hash_hmac("sha256", $signed, $key, true));
$ok = false;
foreach (explode(" ", $sigHdr) as $part) {
if (hash_equals($expected, $part)) { $ok = true; break; }
}
if (!$ok) { http_response_code(400); exit("invalid"); }
handleEvent($msgId, json_decode($body, true));
http_response_code(200);
Retry policy
In short: a delivery that fails is retried three times over about seven minutes, then given up. We try once, and if that fails we wait one minute, then two, then four, so the last attempt is about seven minutes after the first. After four failed attempts in all, that delivery is not sent again unless you replay it.
| Attempt | Sent |
|---|---|
| 1 | As soon as the event happens |
| 2 (first retry) | 1 minute after attempt 1 failed |
| 3 (second retry) | 2 minutes after attempt 2 failed |
| 4 (third and last retry) | 4 minutes after attempt 3 failed |
A webhook that keeps failing is switched off. Every failed attempt, of any delivery, adds one to the webhook’s consecutive_failures, and any success puts it back to 0. At 50 in a row the webhook is disabled: nothing more is sent to it, its waiting retries are dropped, and disabled_at is set on GET /v1/webhooks. A disabled webhook cannot be switched back on; see Manage webhook subscriptions for what to do.
What counts as success vs failure
| Your response | Treated as |
|---|---|
200–299 | Success. We stop. |
4xx / 5xx | Failure. We retry. |
3xx (a redirect) | Failure. We retry. We do not follow redirects; a 3xx response counts as a failed delivery, so register the final URL. |
| Timeout (10s) or no connection | Failure. We retry. |
Errors
Stable error codes, standard HTTP semantics, and a request ID on every response. Branch on error.code, not on the message.
Error envelope
{
"error": {
"code": "invalid_field",
"message": "primary_contact_email is required",
"request_id": "req_a9f2e1c4b7d8",
"field": "primary_contact_email"
}
}
HTTP status codes
| Status | Class | When |
|---|---|---|
200 / 201 / 202 / 204 | Success | Request succeeded |
400 | Client | Malformed request, missing parameters |
401 | Client | Missing or invalid Bearer token |
403 | Client | Token valid but lacks required scope, or asks for a copy its credential does not receive |
404 | Client | Resource doesn't exist or isn't yours |
409 | Client | Resource state prevents the action |
422 | Client | Validation failure |
429 | Client | Rate-limit exceeded. Back off and retry. |
500 / 502 / 503 / 504 | Server | Our side. Retry; contact support if persistent. |
Common error codes
| Status | Code | When |
|---|---|---|
| Authentication | ||
| 401 | missing_authorization | No Authorization: Bearer header |
| 401 | invalid_token | Token signature, issuer or audience invalid |
| 401 | invalid_audience | Token audience does not match this API |
| 401 | token_expired | Request a fresh token, then retry once |
| 401 | invalid_client | client_id / client_secret not recognised (token endpoint) |
| 403 | insufficient_scope | Your credential does not have that scope |
| 403 | credential_disabled | Credential has been revoked |
| 403 | credential_not_found | Credential no longer exists |
| 403 | ip_not_allowed | Source address is not on the credential’s allow-list |
| Token endpoint | ||
| 400 | invalid_grant_type | Only client_credentials is supported |
| 400 | invalid_scope | Requested scope is not granted to this credential |
| Requests | ||
| 400 | invalid_request | Malformed request; a missing / unusable Idempotency-Key; or a marketplace credential calling GET /v1/tests without vin or registration |
| 400 or 422 | invalid_field | A field value was rejected. The response carries field naming which one |
| 422 | validation | Validation failure |
| 403 | variant_not_permitted | ?variant=full on a certificate or warranty document from a credential that receives the anonymised copies only (platform, marketplace, sandbox). The body carries field (variant) and available_variants. No scope changes it: omit variant, or send variant=anonymised |
| 404 | not_found | Resource does not exist, or is not yours |
| 409 | certificate_not_ready | No certificate has been rendered for this test yet. Body carries retry_after_seconds |
| 409 | preview_not_ready | No preview image has been rendered for this test yet. Body carries retry_after_seconds |
| 422 | invalid_webhook_url | Webhook URL rejected — see Manage webhook subscriptions |
| 422 | webhook_limit_reached | The credential already has five enabled webhooks. The body carries limit |
| Limits and server | ||
| 429 | too_many_requests | Rate limit exceeded. Wait the seconds in the Retry-After header, also in the body as retry_after_seconds |
| 500 | internal_error | Our side. Retry; quote the request_id if it persists |
| 502 | bad_gateway | Our side |
| 503 | service_unavailable | A downstream dependency is unavailable. Retry with backoff |
Rate limits
Limits are counted per credential and per endpoint, in requests a minute, whichever address the credential calls from. The token endpoint is the exception: it counts per client_id.
| Endpoint | Requests a minute |
|---|---|
POST /v1/oauth/token — cache your token | 10 |
GET /v1/tests | 60 |
GET /v1/tests/{id}, /certificate, /preview | 120 |
GET /v1/tests/{id}/publish | 120 |
POST /v1/tests/lookup, and 60 vehicles a minute across all your batches | 10 |
POST /v1/webhooks, DELETE /v1/webhooks/{id} | 30 |
GET /v1/webhooks, GET /v1/webhooks/{id} | 60 |
POST /v1/webhooks/{id}/test | 10 |
POST /v1/webhooks/{id}/replay | 5 |
Over a limit, you receive 429 with the usual error envelope. Its message names the limit you went over, and the Retry-After header and retry_after_seconds both give the seconds until that limit's window resets. Wait at least that long before you try the same endpoint again:
HTTP/1.1 429 Too Many Requests
Retry-After: 37
{
"error": {
"code": "too_many_requests",
"message": "60 per 1 minute",
"request_id": "req_e9d8c7b6a5f4",
"retry_after_seconds": 37
}
}
On POST /v1/oauth/token the message is a sentence instead: Too many token requests: the limit is 10 a minute per client_id. Cache the access token and reuse it until it expires. A token lasts an hour (expires_in), so one request an hour per client_id is all you need.
Request ID correlation
Every response includes request_id. On success responses it lives inside meta.request_id; on error responses it lives inside error.request_id. The same value is mirrored on the X-Request-Id response header. Log it alongside your own trace IDs and quote it in support tickets — we use it to find your specific request in our logs in seconds.
Retry guidance
| Status | Retry? | How |
|---|---|---|
2xx | n/a | Success |
400 / 422 | No | Fix the request |
401 + token_expired | Yes (once) | Refresh token, retry once |
403 / 404 | No | Retrying won't help |
409 + certificate_not_ready / preview_not_ready | Yes (later) | The response body carries retry_after_seconds. Wait that long, then retry |
429 | Yes | Wait the seconds in the Retry-After header (also retry_after_seconds in the body), then retry. Limits are per-minute windows, so it is never more than 60 |
5xx / network error | Yes | Exponential backoff with jitter, e.g. starting at 2s and doubling each attempt. Cap at 5 attempts. Use Idempotency-Key on POSTs so retries are safe. |
Getting support
- Email:
info@batteryhealthcheck.co.uk - Response SLA: 1 business day (Standard)
When reporting an issue include: one or more request_ids from failed calls, your client_id (not your secret), timestamps in UTC, and what you expected vs what happened.