Battery Health Check Partner API

A REST API + outbound webhook system for dealer groups who want to provision new branches programmatically, retrieve battery test certificates, and embed test results on their own websites. This single document is everything your dev team needs to integrate — quickstart, full endpoint reference, three worked examples, webhooks, and error handling.

# 1. Get a token (cache for ~55 min)
curl -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

# 2. Latest test for a VIN you already have on the listing
curl "https://api.batteryhealthcheck.co.uk/v1/tests?vin=WVWZZZ1KZAW000000&per_page=1" \
  -H "Authorization: Bearer ACCESS_TOKEN"

# 2b. ...or by number plate, if that's what your feed carries.
#     Prefer the VIN where you have one — see "Look up by VIN or plate".
curl -G "https://api.batteryhealthcheck.co.uk/v1/tests" \
  --data-urlencode "registration=WP72 FKH" --data-urlencode "per_page=1" \
  -H "Authorization: Bearer ACCESS_TOKEN"

# 3. Downloadable certificate (secure, expiring PDF link)
curl https://api.batteryhealthcheck.co.uk/v1/tests/TEST_ID/certificate \
  -H "Authorization: Bearer ACCESS_TOKEN"

Base URLs

Conventions

• Transport: HTTPS only (TLS 1.2+). All responses are application/json; charset=utf-8.
• Auth: Authorization: Bearer <jwt> on every request except /oauth/token.
• Content-Type: application/json for request bodies (except /oauth/token, which is form-encoded).
• Dates: ISO 8601 with UTC timezone (e.g. 2026-05-27T14:22:08Z).
• Pagination: page-based. Pass ?page=1&per_page=25. per_page is capped at 100. The response meta object carries page, per_page, total, and has_more.
• Idempotency: on POST, send Idempotency-Key: <your-key> to make retries safe. It is required on POST /dealers — a request without one is rejected with invalid_request. Allowed characters: ASCII alphanumeric, hyphen (-), underscore (_), and dot (.). Max 80 characters. Keys are retained for the lifetime of the resource they idempotently created — there is no purge.
• Nulls: we never drop a key. Anything we don't hold is serialised as null, so the response shape is stable and safe to deserialise into a fixed schema — but you must null-check before rendering. See Nulls & beta vehicles.
• Additive changes: we may add new fields to existing responses without notice. Ignore keys you don't recognise rather than failing on them. Breaking changes ship on a new version path, never in place.
• Correlation: every response includes request_id in meta + X-Request-Id header.
• Scoping: a dealer-group credential is locked to your group's parent company; a marketplace credential is not tied to a dealer group at all: it looks up one vehicle at a time, by VIN or registration. Either way, you can never see or touch data outside that set.

Getting access

Every request is authenticated with a client_id + client_secret pair (a “key”). There are two ways to get one:

Give each key the least access it needs. A website that only shows certificates should use a read-only key, so a leaked key can't be used to change your data or order hardware.

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│                │
│  Partner       │                                  │  BHC API       │
│                │  2. 200 OK                       │                │
│                │  ◄─────────────────────────────  │                │
│                │     { access_token, expires_in } │                │
│                │                                  │                │
│                │  3. GET /dealers                 │                │
│                │  ─────────────────────────────►  │                │
│                │     Authorization: Bearer <jwt>  │                │
│                │                                  │                │
│                │  4. 200 OK + JSON                │                │
│                │  ◄─────────────────────────────  │                │
└────────────────┘                                  └────────────────┘

Machine-to-machine. No user consent screen, no refresh token. Request a fresh token when the current one is about to expire.

Token endpoint

Request

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

curl -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 write:dealers"

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 write:dealers",
    },
    timeout=10,
)
token = resp.json()["access_token"]

const params = new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "part_a1b2c3d4e5f6",
    client_secret: process.env.BHC_SECRET,
    scope: "read:tests read:certificates write:dealers",
});

const resp = await fetch(
    "https://api.batteryhealthcheck.co.uk/v1/oauth/token",
    { method: "POST", body: params }
);
const { access_token } = await resp.json();

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:tests read:certificates write:dealers"
}

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",
  "scope": "read:tests read:certificates write:dealers",
  "parent_company_id": 198,
  "exp": 1748357821,
  "iat": 1748354221,
  "jti": "tok_8a3f4e2b1c5d"
}

Scope catalog

write:dealers is the only scope that can create dealers or order boxes; it is never granted to self-serve keys (see Getting access). A key is granted a fixed set of scopes at creation; requesting a scope at the token endpoint can only narrow that set, never widen it.

Marketplace access

A marketplace credential is issued to a platform that aggregates listings from several unrelated dealer groups (a classifieds site, for example). It has no parent company of its own and is not tied to a list of them. It is a vehicle lookup: you bring a VIN or a registration from a listing, and we tell you what we know about that car — across every Battery Health Check dealer, because a marketplace cannot know in advance which dealer holds which car.

• Lookup, not listing. GET /v1/tests requires vin or registration on a marketplace credential; without one it returns 400 invalid_request. dealer_id and since/until narrow a lookup but cannot stand in for one, so there is no call that walks any dealer's test history. That restriction is what makes the wide reach reasonable, and it is enforced server-side. Dealer-group credentials are unaffected: listing your own tests works exactly as documented.
• Same endpoints. VIN and registration lookup and certificate/preview downloads work as documented above; a single credential searches every dealer at once, so you never need to know which one holds the car.
• Token shape: your access token carries "parent_company_id": null and "kind": "marketplace". As always, treat the token as opaque — reach is resolved server-side on every request.
• Scopes: marketplace credentials can hold read:tests, read:certificates and manage:webhooks only. Dealer records (read:dealers/write:dealers) are not available; tests identify their dealer via dealer_id and an embedded dealer: {id, name} object.
• Webhooks are the exception, and always scoped. Event delivery is matched by explicit dealer-group grant, so a credential with global lookup reach receives no events at all. A push feed means naming the groups it covers, and needs manage:webhooks in your agreement — it is not granted by default.
• Narrowing and revocation. A marketplace credential can instead be issued restricted to named dealer groups, and either form can be revoked outright. Both take effect from the next request, without waiting for token expiry.
• Getting one: marketplace credentials are issued by BHC only, never self-serve. Talk to your account manager.

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 is rate-limited at 10 req/min/credential.

import time, threading, requests
_cache = {"token": None, "expires_at": 0}
_lock = threading.Lock()

def get_access_token():
    now = time.time()
    if _cache["token"] and now < _cache["expires_at"] - 300:
        return _cache["token"]
    with _lock:
        if _cache["token"] and now < _cache["expires_at"] - 300:
            return _cache["token"]
        body = requests.post(TOKEN_URL, data={...}, timeout=10).json()
        _cache["token"] = body["access_token"]
        _cache["expires_at"] = now + body["expires_in"]
        return _cache["token"]

IP allow-listing

A credential can be locked to a set of source addresses. Once an allow-list is set, a request presenting a perfectly valid token from any other address is rejected with 403 ip_not_allowed — so a leaked client_secret is worthless to anyone who cannot also call from your infrastructure.

This is a second, independent factor on top of OAuth and we recommend it for any server-to-server integration. Ask your account manager to set it, and give us the egress addresses your integration calls from. Two things to keep in mind:

• Tell us before your egress addresses change. A NAT gateway replacement or a new region will lock you out at the moment of cutover. We can hold both old and new ranges over a migration.
• It is per credential. If your staging and production environments call from different addresses, use separate credentials rather than one broad allow-list.

If your security team requires certificate-based client authentication specifically, rather than network-level restriction, raise it with your account manager — it is a scoped piece of work rather than something we run today.

Credential rotation and revocation

Credentials do not expire automatically. We recommend rotating annually as routine practice, and immediately on suspected compromise.

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.

Revocation. Revocation takes effect immediately for new token requests. An access token already issued remains valid until it expires, so allow up to one hour for existing tokens to lapse. Where a credential is known to be compromised, contact us so the outstanding tokens can be invalidated.

Who performs it. Credentials created by a dealer administrator are revoked and reissued by that administrator in the BHC portal. Credentials issued by BHC — those carrying provisioning scopes — are rotated by contacting us. 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.

Create a dealer

Provision a new dealer branch under your parent company. Creates the dealer record, places an order for Aviloo box(es), and emails the owner a password-setup link.

Required scope: write:dealers

Request body

Example

curl -X POST https://api.batteryhealthcheck.co.uk/v1/dealers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stl-mcr-04-create-1" \
  -d '{
    "name": "Stellantis Manchester (Salford Quays)",
    "primary_contact_name": "Jane Smith",
    "primary_contact_email": "jane@stellantis-mcr.example.com",
    "shipping_address": {
      "line1": "12 Salford Quays",
      "city": "Manchester",
      "postcode": "M50 3AG",
      "country": "GB"
    },
    "num_boxes": 1
  }'

Response 201 Created

{
  "data": {
    "id": 247,
    "name": "Stellantis Manchester (Salford Quays)",
    "status": "active",
    "primary_contact": {
      "name": "Jane Smith",
      "email": "jane@stellantis-mcr.example.com",
      "phone": null
    },
    "shipping_address": {
      "line1": "12 Salford Quays",
      "city": "Manchester",
      "postcode": "M50 3AG",
      "country": "GB"
    },
    "units": [
      { "id": 412, "internal_reference": "BHC-UNIT-000412", "status": "ordered" }
    ],
    "activated_at": "2026-05-27T11:47:21Z",
    "created_at": "2026-05-27T11:47:21Z"
  },
  "meta": { "request_id": "req_a9f2e1c4b7d8" }
}

Request additional Aviloo boxes

Order additional Aviloo unit(s) for an existing dealer that needs more capacity. New units ship to the dealer's existing shipping address unless overridden.

Required scope: write:dealers

Request body

Example

curl -X POST https://api.batteryhealthcheck.co.uk/v1/dealers/247/units \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stl-mcr-04-box2" \
  -d '{
    "quantity": 1,
    "location_label": "Service Bay 2"
  }'

Response 201 Created

{
  "data": {
    "units": [
      {
        "id": 502,
        "internal_reference": "BHC-UNIT-000502",
        "status": "ordered",
        "serial_number": null,
        "location_label": "Service Bay 2",
        "shipping_address": {
          "line1": "12 Salford Quays",
          "line2": null,
          "city": "Manchester",
          "postcode": "M50 3AG"
        },
        "dispatched_at": null,
        "delivered_at": null,
        "activated_at": null
      }
    ]
  },
  "meta": { "request_id": "req_e1f3g5h7i9k1" }
}

List dealers

List all dealers under your parent company.

Required scope: read:dealers

Query parameters

curl -G https://api.batteryhealthcheck.co.uk/v1/dealers \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=50"

Response 200 OK

{
  "data": [
    {
      "id": 247,
      "name": "Stellantis Manchester (Salford Quays)",
      "status": "active",
      "primary_contact": { "name": "Jane Smith", "email": "jane@stellantis-mcr.example.com", "phone": "+44 161 555 0123" },
      "shipping_address": { "line1": "12 Salford Quays", "city": "Manchester", "postcode": "M50 3AG", "country": "GB" },
      "units": [
        { "id": 412, "internal_reference": "BHC-UNIT-000412", "status": "active" }
      ],
      "activated_at": "2026-05-28T09:14:00Z",
      "created_at": "2026-05-27T11:47:21Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "has_more": false,
    "request_id": "req_d2e4f6a8b0c1"
  }
}

Get a dealer

Full dealer details including units.

Required scope: read:dealers

{
  "data": {
    "id": 247,
    "name": "Stellantis Manchester (Salford Quays)",
    "legal_name": "Stellantis Manchester Ltd",
    "status": "active",
    "billing_mode": "manual",
    "parent_company_id": 198,
    "company_number": "12345678",
    "vat_number": "GB123456789",
    "primary_contact": {
      "name": "Jane Smith",
      "email": "jane@stellantis-mcr.example.com",
      "phone": "+44 161 555 0123"
    },
    "registered_address": {
      "line1": "12 Salford Quays",
      "line2": null,
      "city": "Manchester",
      "postcode": "M50 3AG",
      "country": "GB"
    },
    "shipping_address": {
      "line1": "12 Salford Quays",
      "line2": null,
      "city": "Manchester",
      "postcode": "M50 3AG",
      "country": "GB"
    },
    "units": [
      {
        "id": 412,
        "internal_reference": "BHC-UNIT-000412",
        "status": "active",
        "serial_number": "AV-2026-0412",
        "location_label": "Workshop",
        "shipping_address": { "line1": "12 Salford Quays", "line2": null, "city": "Manchester", "postcode": "M50 3AG" },
        "dispatched_at": "2026-05-28T08:00:00Z",
        "delivered_at": "2026-06-02T10:30:00Z",
        "activated_at": "2026-06-04T10:00:00Z"
      }
    ],
    "activated_at": "2026-05-28T09:14:00Z",
    "created_at": "2026-05-27T11:47:21Z",
    "updated_at": "2026-06-04T10:00:00Z"
  },
  "meta": { "request_id": "req_d2e4f6a8b0c1" }
}

Update a dealer

Update contact details and shipping address. Status changes are managed by BHC ops.

Required scope: write:dealers

curl -X PATCH https://api.batteryhealthcheck.co.uk/v1/dealers/247 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "primary_contact_phone": "+44 161 555 9999" }'

List tests for a dealer

List battery tests performed by a specific dealer. Use since for incremental polling. To list tests across all of your dealers, omit dealer_id.

Required scope: read:tests

Dealer-group credentials only. On a marketplace credential this endpoint is a lookup: vin or registration is required and a request without one returns 400 invalid_request. See Look up tests by VIN or registration.

Query parameters

Look up tests by VIN or registration

Find tests for a specific vehicle across all your dealers. 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

Example — by VIN

curl -G https://api.batteryhealthcheck.co.uk/v1/tests \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "vin=VR3UHZKXZNT123456" \
  --data-urlencode "per_page=1"

Example — by registration

curl -G https://api.batteryhealthcheck.co.uk/v1/tests \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "registration=WP72 FKH" \
  --data-urlencode "per_page=1"

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:

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.

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
      },
      "battery": {
        "soh_percent": 91.4,
        "capacity_kwh": 45.7,
        "nominal_kwh": 50.0,
        "estimated_range_miles": 195,
        "cell_count": 96,
        "cell_variance": 0.012
      },
      "tested_at": "2026-05-26T14:22:08Z",
      "results_received_at": "2026-05-26T14:25:09Z",
      "result_status": "final",
      "certificate_number": "BHC-CERT-2026-000183",
      "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": 1,
    "total": 1,
    "has_more": false,
    "request_id": "req_91c2d4e6f8a0"
  }
}

Empty data array means no tests exist for that vehicle — either it hasn't been tested, or it was tested at a dealer outside your group.

Get a test

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

Required scope: read:tests

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.

Fields

Example

{
  "data": {
    "id": 9182,
    "status": "completed",
    "vehicle": { "vin": "VR3UHZKXZNT123456", "make": "Peugeot", "model": "e-208" },
    "battery": { "soh_percent": 91.4, "capacity_kwh": 45.7 },
    "vehicle_supported": true,
    "warnings": [],
    "diagnostics": {
      "vehicle_supported": true,
      "overall_battery_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": 214.0,   "typical_current_miles": 195.4,
        "personal_new_miles": null,   "personal_current_miles": 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" },
        "cell_voltage_v":     { "min": 4.146, "max": 4.159, "delta": 0.013, "status": "OK" },
        "pack_voltage_v": 398.7,
        "average_current_a": 1.2,
        "mileage_km": 29644
      },
      "bms": {
        "soc_percent": 96.0,
        "soh_percent": 92.1,
        "soc_calculation_accuracy": 1.94,
        "soh_calculation_accuracy": 0.95
      }
    }
  }
}

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

Warning types

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? If you publish battery data on a public website, this is the first field to branch on — it is cheaper to read than reasoning across status, soh_percent, vehicle_supported and warnings yourself.

The one branch that covers all four

test = get_test(test_id)

match test.get("result_status"):
    case "final":
        # Safe to publish. Still check vehicle_supported — a beta
        # model's derived figures (range, cell count) may be missing.
        render_soh(test["battery"]["soh_percent"])
    case "provisional":
        # Number exists but isn't quotable. Certificate image only.
        render_certificate_image(test)
    case "inconclusive":
        # Finished, no verdict. Never coming. Don't show a spinner.
        render_note("Battery health could not be determined")
    case _:
        # null — still processing, or an old record. Poll or omit.
        render_nothing()

{
  "data": {
    "id": 9184,
    "status": "completed",
    "battery": { "soh_percent": null },
    "result_status": "inconclusive",
    "vehicle_supported": true,
    "warnings": []
  }
}

Nulls & beta vehicles

We never omit keys — a value we don’t have is serialised as null rather than dropped, so the schema is stable. That means every consumer must null-check before rendering. These are the fields that are null often enough to matter in production:

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; what you should not do is publish “102.9% battery health, range unknown” on a listing page without a second thought. Branch on the flag:

test = get_test(test_id)
warnings = test.get("warnings") or []

if test.get("vehicle_supported") is False or "SOH_GREATER_THAN_100" in warnings:
    # Beta model, or an implausible reading. The certificate is valid;
    # the derived figures may not be. Show the image, not your own numbers.
    render_certificate_only(test)
elif test["battery"]["soh_percent"] is not None:
    render_full_summary(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 certificate image rather than your own numeric rendering.

Get the full certificate (PDF) — contains VIN, for records

Returns a 1-hour signed URL for the full multi-page Aviloo PDF certificate.

The PDF prints the full VIN on it. Use it for sales-quality printable copies, customer hand-off, attaching to a vehicle's permanent record, or anywhere only authorised users will see the file. Don't surface this URL on a public web page — use /preview below for that.

Required scope: read:certificates

Response 200 OK — cached

{
  "data": {
    "url": "https://files.batteryhealthcheck.co.uk/certificates/.../X-Amz-Signature=...",
    "expires_at": "2026-05-27T12:47:00Z",
    "content_type": "application/pdf",
    "certificate_number": "BHC-CERT-2026-000183"
  },
  "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
  }
}

Get the public-facing certificate image (JPEG)

Returns a 1-hour signed URL for a JPEG image — the Aviloo-branded “Battery Certificate Preview”.

Single-page summary showing State of Health %, range, vehicle make/model, mileage, test date, and the testing dealer. The VIN is not on the image, and the certificate number is masked (e.g. DD783123-96F3-4F0B-****-************). A QR code on the image links back to Aviloo's hosted validation page.

Designed for public display: embed it directly on car listing pages as an <img>. No personally-identifying vehicle data leaks to the public.

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" }
}

Manage webhook subscriptions

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

Required scope: manage:webhooks

curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks/42/test \
  -H "Authorization: Bearer $TOKEN"

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"
  }
}

curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.stellantis.example.com/bhc/v1",
    "events": ["bhc.test.completed", "bhc.dealer.activated"]
  }'

The response includes a secret — store it immediately. We can rotate it but never re-display it.

Worked Examples

Three end-to-end scenarios covering the most common integrations. Every step is runnable; the responses match what you'd see in production.

A. Adding a new dealer branch

Scenario: Stellantis is opening a new branch in Manchester (Salford Quays). HQ wants to spin up the dealer record from their own dealer-management system instead of emailing BHC ops.

Step 1. Get a token

TOKEN=$(curl -s -X POST https://api.batteryhealthcheck.co.uk/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=part_a1b2c3d4e5f6" \
  -d "client_secret=$BHC_SECRET" \
  -d "scope=write:dealers manage:webhooks" \
  | jq -r '.access_token')

Step 2. Create the dealer

curl -X POST https://api.batteryhealthcheck.co.uk/v1/dealers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stl-mcr-04-create-1" \
  -d '{
    "name": "Stellantis Manchester (Salford Quays)",
    "primary_contact_name": "Jane Smith",
    "primary_contact_email": "jane@stellantis-mcr.example.com",
    "primary_contact_phone": "+44 161 555 0123",
    "shipping_address": {
      "line1": "12 Salford Quays",
      "city": "Manchester",
      "postcode": "M50 3AG",
      "country": "GB"
    },
    "num_boxes": 1
  }'

Response (truncated):

{
  "data": {
    "id": 247,
    "status": "active",
    "units": [{ "id": 412, "status": "ordered" }],
    "activated_at": "2026-05-27T11:47:21Z"
  },
  "meta": { "request_id": "req_a9f2e1c4b7d8" }
}

Step 3. Register a webhook for test results

Instead of polling, subscribe to bhc.test.completed so your CRM knows the moment a new certificate is ready:

curl -X POST https://api.batteryhealthcheck.co.uk/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://crm.stellantis.example.com/bhc/test-completed",
    "events": ["bhc.dealer.activated", "bhc.test.completed", "bhc.test.failed"]
  }'

Step 4. What happens next

1. The dealer owner gets the password-setup email within minutes.
2. The Aviloo box ships in ~5 working days.
3. The new dealer is created in the active state immediately — we fire bhc.dealer.activated on creation so your downstream systems can sync.
4. When the box arrives, the dealer activates it in the BHC portal. The unit moves ordered → shipped → active. Re-fetch the dealer with GET /v1/dealers/{id} to inspect the latest unit state.
5. The dealer can start running tests. Every completed test fires bhc.test.completed; if a test couldn't complete, we fire bhc.test.failed.

B. Requesting additional Aviloo boxes

Scenario: The Manchester branch is doing more volume than expected. They need a second Aviloo box for their second service bay.

Step 1. Find the dealer ID

List your dealers and pick the one you want (cache the ID alongside your own DMS site code so you don't need this lookup repeatedly):

curl -G https://api.batteryhealthcheck.co.uk/v1/dealers \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=100"

Step 2. Request the additional box

curl -X POST https://api.batteryhealthcheck.co.uk/v1/dealers/247/units \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stl-mcr-04-box2" \
  -d '{
    "quantity": 1,
    "location_label": "Service Bay 2"
  }'

Response:

{
  "data": {
    "units": [
      {
        "id": 502,
        "internal_reference": "BHC-UNIT-000502",
        "status": "ordered",
        "location_label": "Service Bay 2",
        "shipping_address": { "line1": "12 Salford Quays", "city": "Manchester", "postcode": "M50 3AG" },
        "dispatched_at": null,
        "delivered_at": null,
        "activated_at": null
      }
    ]
  },
  "meta": { "request_id": "req_e1f3g5h7i9k1" }
}

Step 3. Poll the dealer to track unit state

There is no dedicated unit-activation webhook. Re-fetch the dealer (the response embeds the full units array including each unit's status and activated_at) when you want to inspect lifecycle changes:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.batteryhealthcheck.co.uk/v1/dealers/247

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 a downloadable certificate 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 Manchester, could be any of your branches. The lookup endpoint solves that.

Step 1. Look up the most recent test by VIN

On your listing page's server-side render (or via your inventory backend):

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, "page": 1, "per_page": 1},
        timeout=5,
    )
    data = resp.json()["data"]
    return data[0] if data else None  # 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("page", "1");
    url.searchParams.set("per_page", "1");
    const resp = await fetch(url, {
        headers: { Authorization: `Bearer ${token}` }
    });
    const { data } = await resp.json();
    return data[0] || null;
}

<?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, "page" => 1, "per_page" => 1]),
        CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $body["data"][0] ?? null;
}

Step 2. Choose how to display it

You now have a test record. Three useful ways to surface it on the listing:

Option A — Show key values as text

Best for clean, brand-consistent listings. Pull the values out of the JSON and write your own HTML — guarding each field, since any of them can legitimately be null (see Nulls & beta vehicles):

<div class="battery-summary">
  <h3>Battery Health Check</h3>
  <dl>
    {% if test.battery.soh_percent %}
    <dt>State of Health</dt>
      <dd>{{ test.battery.soh_percent }}%</dd>
    {% endif %}
    {% if test.battery.estimated_range_miles %}
    <dt>Estimated range</dt>
      <dd>{{ test.battery.estimated_range_miles }} miles</dd>
    {% endif %}
    <dt>Tested</dt>
      <dd>{{ test.tested_at | date }}</dd>
  </dl>
  {% if test.certificate_number %}
  <p class="ref">Certificate: {{ test.certificate_number }}</p>
  {% endif %}
</div>

Option B — Embed the abbreviated certificate (JPEG)

Best when you want the official BHC-branded image on the listing. One additional call:

def get_preview_url(test_id, token):
    resp = requests.get(
        f"https://api.batteryhealthcheck.co.uk/v1/tests/{test_id}/preview",
        headers={"Authorization": f"Bearer {token}"},
        timeout=5,
    )
    return resp.json()["data"]["url"]

Then in the listing template:

<img src="{{ preview_url }}"
     alt="Battery Health Check certificate {{ test.certificate_number }}"
     loading="lazy"
     style="max-width: 400px;">

Option C — Offer the full PDF as a download

Best for “Download full report” buttons. Generate the signed URL on demand when the user clicks:

<!-- Button calls your backend, which then calls BHC -->
<a href="/api/internal/battery-cert/{{ test.id }}">
  Download full battery certificate (PDF)
</a>

Your backend:

@app.route("/api/internal/battery-cert/<int:test_id>")
def proxy_certificate(test_id):
    token = get_access_token()
    resp = requests.get(
        f"https://api.batteryhealthcheck.co.uk/v1/tests/{test_id}/certificate",
        headers={"Authorization": f"Bearer {token}"},
        timeout=5,
    )
    pdf_url = resp.json()["data"]["url"]
    return redirect(pdf_url, code=302)  # short-lived signed URL

Step 3. Handle the “no test exists” case

Not every car on your forecourt has been tested yet. Decide upfront what your listing shows when get_battery_data_for_vin() returns None:

• Hide the battery section entirely
• Show “Battery test scheduled” with the dealer's next available appointment
• Show a generic “Pre-owned EV — Battery Health Check available on request” CTA

Putting it together

A typical render-time flow on a car listing page:

def render_listing(vehicle):
    test = get_battery_data_for_vin(vehicle.vin)

    context = {"vehicle": vehicle, "battery_section": None}

    if test:
        token = get_access_token()
        preview_url = get_preview_url(test["id"], token)
        # Only a "final" result is quotable. "provisional" has a number
        # that isn't safe to headline, "inconclusive" has none at all,
        # null means not answerable yet — all three fall back to the
        # certificate image. Beta models also get image-only treatment.
        quotable = (test.get("result_status") == "final"
                    and test.get("vehicle_supported") is not False
                    and "SOH_GREATER_THAN_100" not in (test.get("warnings") or []))
        context["battery_section"] = {
            "soh_percent": test["battery"]["soh_percent"] if quotable else None,
            "range_miles": test["battery"]["estimated_range_miles"] if quotable else None,
            "tested_at": test["tested_at"],
            "certificate_number": test["certificate_number"],  # may be null
            "preview_url": preview_url,
            "full_cert_link": f"/api/internal/battery-cert/{test['id']}",
        }

    return render("listing.html", **context)

Webhooks

Subscribe to events and we'll push them to your endpoint within seconds. Signed using the Standard Webhooks scheme (HMAC-SHA256, base64-encoded). Failed deliveries are retried with exponential backoff, then auto-disabled if a single endpoint accumulates 50 consecutive failures.

Event catalog (v1)

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
      },
      "battery": {
        "soh_percent": 91.4,
        "capacity_kwh": 45.7,
        "nominal_kwh": 50.0,
        "estimated_range_miles": 195,
        "cell_count": 96,
        "cell_variance": 0.012
      },
      "tested_at": "2026-05-26T14:22:08Z",
      "results_received_at": "2026-05-26T14:25:09Z",
      "certificate_number": "BHC-CERT-2026-000183",
      "certificate_available": true,
      "preview_available": true,
      "dealer": { "id": 247, "name": "Stellantis Manchester (Salford Quays)" },
      "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 Stripe/AVILOO/Svix-style verifier, you can reuse it — the on-the-wire format is identical, only the secret needs to change.

Headers we send

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>. During secret rotation we send two signatures separated by a space; accept the delivery if any one of them verifies.

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()

    # Header may contain multiple space-separated signatures during rotation
    if not any(hmac.compare_digest(expected, part)
               for part in sig_hdr.split(" ")):
        abort(400, "invalid signature")

    event = request.get_json()
    handle_event(msg_id, event)  # idempotent on webhook-id
    return "", 200

const crypto = require("crypto");

const SECRET = "whsec_8f9a3b2c...";
const TOLERANCE = 300;

function keyBytes(secret) {
    if (!secret.startsWith("whsec_")) {
        throw new Error("secret must start with whsec_");
    }
    return Buffer.from(secret.slice("whsec_".length), "base64");
}

app.post("/webhooks/bhc",
    express.raw({ type: "application/json" }),
    (req, res) => {
        const msgId  = req.headers["webhook-id"]        || "";
        const tsStr  = req.headers["webhook-timestamp"] || "0";
        const sigHdr = req.headers["webhook-signature"] || "";
        const body   = req.body;  # Buffer of RAW bytes

        const ts = parseInt(tsStr, 10);
        if (!Number.isFinite(ts) ||
            Math.abs(Date.now()/1000 - ts) > TOLERANCE) {
            return res.status(400).send("stale timestamp");
        }

        const signed = Buffer.concat([
            Buffer.from(`${msgId}.${ts}.`),
            body,
        ]);
        const expected = "v1," + crypto
            .createHmac("sha256", keyBytes(SECRET))
            .update(signed).digest("base64");

        const ok = sigHdr.split(" ").some(part => {
            const a = Buffer.from(expected);
            const b = Buffer.from(part);
            return a.length === b.length && crypto.timingSafeEqual(a, b);
        });
        if (!ok) return res.status(400).send("invalid signature");

        handleEvent(msgId, JSON.parse(body));  # idempotent on webhook-id
        res.status(200).send();
    }
);

<?php
$secret = "whsec_8f9a3b2c...";
$tolerance = 300;

$msgId  = $_SERVER["HTTP_WEBHOOK_ID"]        ?? "";
$tsStr  = $_SERVER["HTTP_WEBHOOK_TIMESTAMP"] ?? "0";
$sigHdr = $_SERVER["HTTP_WEBHOOK_SIGNATURE"] ?? "";
$body   = file_get_contents("php://input");   # RAW bytes

$ts = (int)$tsStr;
if (abs(time() - $ts) > $tolerance) {
    http_response_code(400); exit("stale");
}

if (strpos($secret, "whsec_") !== 0) {
    http_response_code(500); exit("bad secret");
}
$key = base64_decode(substr($secret, strlen("whsec_")));

$signed   = $msgId . "." . $ts . "." . $body;
$expected = "v1," . base64_encode(hash_hmac("sha256", $signed, $key, true));

$ok = false;
foreach (explode(" ", $sigHdr) as $part) {
    if (hash_equals($expected, $part)) { $ok = true; break; }
}
if (!$ok) { http_response_code(400); exit("invalid"); }

handleEvent($msgId, json_decode($body, true));
http_response_code(200);

Retry policy

A single delivery is attempted up to 4 times in total (initial + 3 retries). Backoffs are 60s, 120s, 240s, 480s — only the first three are used by the max-attempts cap. After the final failed attempt the delivery stops retrying. An individual endpoint is auto-disabled after 50 consecutive failures across deliveries. Use POST /v1/webhooks/{id}/replay to retry manually, or contact your account manager.

What counts as success vs failure

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

Common error codes

Rate limits

Limits are applied per endpoint group, per credential.

On 429:

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "too_many_requests",
    "message": "Rate limit exceeded. Retry in 23 seconds.",
    "request_id": "req_e9d8c7b6a5f4"
  }
}

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

Getting support

• Email: info@batteryhealthcheck.co.uk
• Response SLA: 1 business day (Standard)

When reporting an issue include: one or more request_ids from failed calls, your client_id (not your secret), timestamps in UTC, and what you expected vs what happened.