Battery Health CheckMarketplaces
OpenAPI Samples

Marketplace API. For public car-listing sites that show a battery result on any listing, whichever dealer tested the car. A dealer group, or software many dealers use? Dealer group and platform API

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.

⚡ Quickstart

Goal: show the battery certificate on a used-EV listing.

Three calls. Your credential holds read:tests and read:certificates; keep it server-side.

  1. Swap the key for a 1-hour token (cache it). The token is inside data.
  2. Look the vehicle up by VIN or registration.
  3. 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.

Audience. A developer at a classifieds site, aggregator or listing platform that carries stock from several unrelated dealer groups. If you are a dealer group, a DMS, or building one dealer's website, you want the dealer API instead — it can also provision branches and order test units, which this one cannot. Machine-readable spec: openapi.json. Field-by-field reference: data dictionary.
One rule to know up front. 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

EnvironmentBase URL
Productionhttps://api.batteryhealthcheck.co.uk/v1
Sandbox and test data. Sandbox credentials are by invitation: ask us. One calls this same base URL and answers from invented fixture data, as a platform connected to fixture dealers rather than with a marketplace credential’s reach. Without one, the sample response pack provides a representative set of responses covering successful, provisional and other result states. When an integration is ready for validation, we recommend a pilot using real tests with a participating dealer, which allows both parties to validate the complete workflow before production rollout. See also Result status and Null values and models in validation.

Conventions


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.

StepWho does itWhat 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.
The secret is never sent to you, because we never have it. It is generated when you open the invitation and rendered in your browser only; we keep a one-way hash. That means there is no copy in an inbox or a ticket, and no channel for you to secure — but it also means nobody can read it back to you. Save it before you leave the page. If it is lost we revoke the credential and send a fresh invitation.
Open the invitation only when you are ready to save the secret. The link works once and expires after 14 days. Opening it out of curiosity uses it up.

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

POST /v1/oauth/token

Request

Content-Type: application/x-www-form-urlencoded

ParameterRequiredDescription
grant_typeyesMust be client_credentials
client_idyes*Your credential ID
client_secretyes*Your credential secret
scopeoptionalSpace-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:

Statuserror.codeWhen
400invalid_requestThe 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.
400invalid_grant_typegrant_type is not client_credentials. (The standard calls this unsupported_grant_type.)
400invalid_scopeNone 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.
401invalid_clientThe client_id or the client_secret is wrong.
403credential_disabledThe credential has been disabled.
429too_many_requestsMore 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.

ScopeGrantsGranted
read:testsLook up tests by VIN or registration; read a single testAlways
read:certificatesGet the anonymised PDF certificate (VIN hidden) and the publishable JPEG previewAlways
manage:webhooksRegister and manage push subscriptions for new testsBy 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.

What you get back is the publishable artefact. The preview image has the VIN removed and AVILOO’s certificate number masked, and carries a QR code to AVILOO’s own validation page — it is built to go on a public listing. /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:

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:

ParameterOn its ownWith a VIN or plate
dealer_id400 invalid_requestRestricts the lookup to that one dealer
since / until400 invalid_requestRestricts the lookup to a date range
updated_since400 invalid_requestRestricts the lookup to tests new or changed since that instant
page / per_page400 invalid_requestPages the results for that vehicle
This is the shape of the product, not a rate limit. Your credential reaches every dealer precisely because it can only ever answer about a car you can already name. A call that worked with an empty filter would be a readable copy of every dealer’s stock — a different product, and not one we sell. So there is no “list everything” endpoint to find and nothing to negotiate up.

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

GET /v1/tests?vin={vin}
GET /v1/tests?registration={plate}

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

ParamTypeDescription
vinstringVehicle 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.
registrationstringVehicle 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_idintegerRestrict to one dealer you have access to. Cannot be used on its own — see the lookup rule. Combines with the filters above.
currentbooleantrue: 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.
statusstringComma-separated. Only tests in one of these states: pending, in_progress, completed, failed, cancelled.
warranty_statestringComma-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_sinceISO 8601Only tests with results_received_at >= completed_since. A test with no completion time never matches.
completed_untilISO 8601Only tests with results_received_at <= completed_until.
unit_idintegerOnly tests run on this unit (the test’s unit_id).
powertrainstringComma-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_idstringOnly 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.
pageinteger1-based page number. Default 1.
per_pageinteger1–100. Default 25. Results are ordered newest-first by tested_at.
Allowed characters. 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.
Search by plate for convenience — but key your data on VIN. Both filters are supported and both are exact. The difference is that a VIN is permanent and a plate is not: registrations transfer between vehicles (cherished/private plates), and a car can be re-plated on import or re-registration. A VIN identifies one physical vehicle for its whole life.

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:

WhyWhat you seeWhat 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.
Always check the VIN on a plate lookup. If 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.

Plate coverage is not universal. Battery tests arrive from the AVILOO box identified by VIN only — the plate is added afterwards, either by the dealer entering it in their portal or by our VIN → registration lookup. Most tests carry one, but a test with no plate on record has 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.

Abbreviated above. Each test object also carries a 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

POST /v1/tests/lookup

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

FieldTypeDescription
vehiclesrequiredarray1–50 vehicle objects (fields below).
dealer_idintegerRestrict every lookup to one dealer and its branches. An id outside your reach returns 404 not_found.

Each vehicle

FieldTypeDescription
vinstringThe full 17 characters; there is no prefix search here. Digits and A–Z except O and Q.
registrationstringExact match. Spaces, hyphens and case are ignored, as on GET /v1/tests.
refstringYour own identifier for the vehicle, echoed back on its result: up to 64 letters, digits, ., _, : and -.
mileage_milesintegerThe 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:

StatusCodeWhen
400invalid_requestThe body is not a JSON object, or vehicles is missing, not a list, empty, or longer than 50.
400invalid_fielddealer_id is not a positive integer.
404not_founddealer_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

GET /v1/tests/{id}

Full JSON for a single test, including all vehicle and battery details.

Required scope: read:tests

Odometer: read 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.

FieldWhat it holds
result_typeAVILOO’s overall result: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null until the test is evaluated, and on tests that did not complete.
error_reasonWhy a test stopped, for example DONGLE_NO_VEHICLE_EXCEPTION (no vehicle detected) or INCOMPLETE. Null for a test that did not stop.
provider_stateAVILOO’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_detailsThe 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_idAVILOO’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.

Looking for the “beta / not yet supported” marker? Use the top-level 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).
If you publish battery data on a public website, this is the field to branch on.

Fields

FieldTypeDescription
vehicle_supportedboolean | nullfalse = 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_statusstring | nullAVILOO’s headline verdict: OK, WARNING, NOT_CONCLUSIVE or SAFETY_ISSUE.
soh_statusstring | nullAVILOO’s status for its own state-of-health reading (battery.soh_percent), in the same four values.
battery_checksobjectPer-subsystem results, each OK / WARNING / NOT_CONCLUSIVE / SAFETY_ISSUE: battery_management_system, battery_sensors, battery_pack_parameters, battery_cell_voltages, vehicle_communication.
sensor_checksobjectSensor-level results: voltage_sensor, current_sensor, temperature_sensors, cell_voltage_sensors.
energy_kwhobjectGross / 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.
rangeobjectAVILOO 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.
measurementsobjectcell_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.
bmsobjectWhat 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

ValueMeaning
SOH_GREATER_THAN_100Battery evaluated as having more than 100% of its specified capacity. Usually seen on models still in validation — check vehicle_supported.
UNCLEAR_MODELVehicle data was ambiguous about the exact model. Verify the model shown on the certificate.
MISSING_SIGNALAt least one required signal could not be read from the vehicle.
IMPLAUSIBLE_SIGNALThe vehicle reported a value outside the plausible range (e.g. voltage > 2000 V).
NOT_ENOUGH_DATAThe vehicle did not deliver enough data for at least one required signal type.
NO_RELAXED_PHASESNo phase without load on the battery could be detected during the test.
NO_GOOD_RELAXED_PHASESA relaxed phase was detected but its quality was too low to use.
BATTERY_TEMP_TOO_LOWBattery was below the recommended operating window during the test.
BATTERY_TEMP_TOO_HIGHBattery was above the recommended operating window during the test.
BATTERY_TEMP_DELTA_TOO_LARGEDiscrepancy in battery temperature across the pack — potential cooling-system defect.
BATTERY_TEMP_CRITICALLY_HIGHTemperature outside the maximum operating window. A safety concern.
BMS_SOC_IMPLAUSIBLEThe car's own state-of-charge reading is implausible — the BMS may need recalibrating.
SOH_TOO_LOWThe state of health is below the recommended limit for normal operation.
SOH_CRITICALLY_LOWThe state of health is below the recommended limit for safe operation. A safety concern.
CELL_VOLTAGE_SPREAD_TOO_HIGHA 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_HIGHThe difference between the highest and lowest charged cells points to a battery balancing fault. A safety concern.
CURRENT_OUTSIDE_ACCEPTABLE_RANGEThe 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.

Treat this list as open-ended. AVILOO adds warning types as their evaluation improves, and we pass them straight through — so you will eventually see values that aren't in the table above. Match on the specific values you care about and fall through to a generic “see certificate for details” for anything unrecognised. Do not map this to a closed enum that throws on an unknown value.

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.

ValueMeaningWhat 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.
Why this field exists. An inconclusive test previously serialised as 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.
It is orthogonal to 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

The sample response pack, built from real tests, shows most of the cases below; it holds no real inconclusive result yet, so that case is described here rather than invented. Samples are illustrative; the OpenAPI specification and the data dictionary define the supported API contract.

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:

FieldNull when
battery.estimated_range_milesAVILOO 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_countAlways, 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_varianceSourced from the detailed measurement record — null on the same older tests where diagnostics is null.
certificate_numberThe 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.powertrainThe test was recorded before AVILOO began publishing the vehicle category. Otherwise BEV, PHEV or HEV; treat any other value as unknown.
vehicle.registrationThe 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.
diagnosticsSee the callout above.
vehicle_supportedNeither 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.
warrantyExactly 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_reasonsExactly 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.
warningsNo 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.


Two certificate artifacts — pick the right one:
  • /certificate (PDF) — your credential receives the anonymised copy, with the VIN hidden. Put it on a page only where the publish decision’s image.publishable is 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

GET /v1/tests/{id}/publish

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

ParameterTypeDescription
advert_mileage_milesintegerOptional. 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.
includestringOptional. 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.

CodeMeaningImage
AMBIGUOUS_REGISTRATIONBatch 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_YETThe test is still running.No
TEST_DID_NOT_COMPLETEThe test stopped before it finished.No
INCONCLUSIVEThe test finished without a figure. None will follow.No
PROVISIONAL_OVER_100The figure is above 100%: the model’s reference data is not final.Yes
DISPUTEDThe result is being reviewed.No
SUPERSEDEDA newer completed test of the same car has a figure; superseded_by names it.No
SAFETY_FINDINGThe test reported a possible safety issue with the battery.No
AVILOO_FINDINGThe test reported a warning about the battery. The certificate gives the detail.Yes
RESULT_NOT_RECORDEDThe full result was not recorded for this test.Yes
CHECKS_NOT_ALL_OKNot every battery check was OK.Yes
MODEL_IN_VALIDATIONThe model is still being validated: show the image, not your own rendering of the figure.Yes
MODEL_SUPPORT_UNKNOWNWhether the model is validated was not recorded for this test.Yes
TEST_OLDER_THAN_90_DAYSThe test is more than 90 days old, or has no date.Yes, when dated
ADVERT_MILEAGE_PAST_TESTThe advert’s mileage is more than 1,000 miles past the reading at the test.Yes
ADVERT_MILEAGE_BELOW_TESTThe 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. copy fits the Auto Trader slots (seller_highlight at most 55 characters, attention_grabber at most 30) and description. statements are for a person or an assistant to repeat. Every number in them comes from the test.
  • Quote the figure exactly as soh_display gives 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.publishable is true (NO_AVILOO_MARKS).
  • Respect must_not_say. Branch on its codes; the text is the rule in plain words.
  • The grade is AVILOO’s, named as AVILOO’s. band is 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, band is null and must_not_say holds NO_GRADE: show the figure and its date alone.
  • Refresh it. The decision lapses at valid_until, 90 days after the test. Fetch it again when bhc.test.completed or bhc.test.warranty_changed arrives for the same car, because a newer test can replace this one.
  • Outside the UK, copy is null, statements is empty, whether or not the test is publishable, and copy_withheld_reason is REGION_NOT_REVIEWED: our English wording has not been reviewed for that market. The figure itself is still publishable, and must_not_say is 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

StatusCodeWhen
400invalid_fieldadvert_mileage_miles is not a whole number from 0 to 1,000,000, or include names something other than dated_result and warranty_status.
403insufficient_scopeThe token does not carry read:tests.
404not_foundNo such test, or, with global reach, a test of a vehicle you have not looked up by vin or registration.
429too_many_requestsRate limited. Wait the seconds in the Retry-After header (never more than 60).

Get the certificate (PDF) — anonymised version, VIN hidden

Your credential receives the anonymised version only. Without 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.
GET /v1/tests/{id}/certificate

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

ParameterTypeDescription
variantstringOptional. 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)

GET /v1/tests/{id}/preview

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" }
}
Rule of thumb
  • 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 says image.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

Webhooks for the cars you have looked up. The endpoints below need 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.failed and bhc.test.warranty_changed for 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 on vehicle.vin.

Manage webhook subscriptions

See Webhooks below for event payloads and signing. The endpoints to manage them:

POST /v1/webhooks Register a webhook
GET /v1/webhooks List your webhooks
GET /v1/webhooks/{id} Get one webhook and its delivery health
DELETE /v1/webhooks/{id} Delete a webhook
POST /v1/webhooks/{id}/test Send a test event
POST /v1/webhooks/{id}/replay Re-send failed deliveries

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:

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:

error_codeMeaning
http_errorYour endpoint answered with a status other than 2xx or 3xx (see http_status).
redirect_not_followedIt answered 3xx. We never follow redirects.
timeoutNo answer within 10 seconds.
tls_errorThe TLS handshake failed, for example an expired or untrusted certificate.
connection_failedThe 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_errorAny other failure to send the request.
internal_errorOn 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.

Prove your endpoint the day you register it. Registering returns 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"
  }
}
Handling it. Return 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"] }'
FieldDescription
sinceRequired. 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_typesOptional. 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.

Feed carries plates, not VINs? Swap 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.
Your credential already fits. This whole flow needs only 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).

The publish decision decides, not your own reading of the fields.

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;">
Never hot-link the signed URL. It expires after an hour, so a page that embeds it shows a broken image an hour later, and every view would cost you an API call. Fetch the JPEG once and serve it from your own storage.

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:

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"],
    }
Caching. Don’t call us on every page view: store the section and the image with the listing, and refresh them when the test changes. A test is not fixed once it completes — its registration can be added later, its warranty can change state, and a newer test of the same car can arrive — so key your copy on the test 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)

EventFires whenTypical 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.

No box-activation event today. v1 does not emit a separate event when a physical AVILOO box is activated — only the dealer-level bhc.dealer.activated event exists.
Marketplace credentials (see Marketplace access) can subscribe to the test events only — 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

HeaderDescription
webhook-idUnique identifier for this delivery (URL-safe base64, ~22 chars). Use this for idempotency.
webhook-timestampUnix epoch seconds (string).
webhook-signatureA 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-typeapplication/json
User-AgentBatteryHealthCheck-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:

  1. Build the signed message: <webhook-id> + "." + <webhook-timestamp> + "." + <raw body bytes>.
  2. Compute HMAC-SHA256(decoded_secret, signed_message).
  3. Base64-encode the digest (standard alphabet, with padding).
  4. 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);
Use the raw request body, not a re-serialised one. If your framework parses JSON before you grab the bytes, your HMAC won't match. Most frameworks expose a raw-body hook or middleware.

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.

AttemptSent
1As 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 responseTreated as
200–299Success. We stop.
4xx / 5xxFailure. 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 connectionFailure. We retry.
Respond fast, process async. Return 2xx as soon as you've verified the signature and queued the event. Don't do heavy lifting inside the webhook handler — we time out at 10s.

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

StatusClassWhen
200 / 201 / 202 / 204SuccessRequest succeeded
400ClientMalformed request, missing parameters
401ClientMissing or invalid Bearer token
403ClientToken valid but lacks required scope, or asks for a copy its credential does not receive
404ClientResource doesn't exist or isn't yours
409ClientResource state prevents the action
422ClientValidation failure
429ClientRate-limit exceeded. Back off and retry.
500 / 502 / 503 / 504ServerOur side. Retry; contact support if persistent.

Common error codes

StatusCodeWhen
Authentication
401missing_authorizationNo Authorization: Bearer header
401invalid_tokenToken signature, issuer or audience invalid
401invalid_audienceToken audience does not match this API
401token_expiredRequest a fresh token, then retry once
401invalid_clientclient_id / client_secret not recognised (token endpoint)
403insufficient_scopeYour credential does not have that scope
403credential_disabledCredential has been revoked
403credential_not_foundCredential no longer exists
403ip_not_allowedSource address is not on the credential’s allow-list
Token endpoint
400invalid_grant_typeOnly client_credentials is supported
400invalid_scopeRequested scope is not granted to this credential
Requests
400invalid_requestMalformed request; a missing / unusable Idempotency-Key; or a marketplace credential calling GET /v1/tests without vin or registration
400 or 422invalid_fieldA field value was rejected. The response carries field naming which one
422validationValidation failure
403variant_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
404not_foundResource does not exist, or is not yours
409certificate_not_readyNo certificate has been rendered for this test yet. Body carries retry_after_seconds
409preview_not_readyNo preview image has been rendered for this test yet. Body carries retry_after_seconds
422invalid_webhook_urlWebhook URL rejected — see Manage webhook subscriptions
422webhook_limit_reachedThe credential already has five enabled webhooks. The body carries limit
Limits and server
429too_many_requestsRate limit exceeded. Wait the seconds in the Retry-After header, also in the body as retry_after_seconds
500internal_errorOur side. Retry; quote the request_id if it persists
502bad_gatewayOur side
503service_unavailableA 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.

EndpointRequests a minute
POST /v1/oauth/token — cache your token10
GET /v1/tests60
GET /v1/tests/{id}, /certificate, /preview120
GET /v1/tests/{id}/publish120
POST /v1/tests/lookup, and 60 vehicles a minute across all your batches10
POST /v1/webhooks, DELETE /v1/webhooks/{id}30
GET /v1/webhooks, GET /v1/webhooks/{id}60
POST /v1/webhooks/{id}/test10
POST /v1/webhooks/{id}/replay5
Counted per credential. Each credential has its own allowance on each endpoint, whichever address it calls from. Two credentials calling from the same server do not share one, and one credential calling from several servers is still one allowance.

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

StatusRetry?How
2xxn/aSuccess
400 / 422NoFix the request
401 + token_expiredYes (once)Refresh token, retry once
403 / 404NoRetrying won't help
409 + certificate_not_ready / preview_not_readyYes (later)The response body carries retry_after_seconds. Wait that long, then retry
429YesWait 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 errorYesExponential 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

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.