{ "about": "BHC Partner API v1 — sample response pack", "api_version": "v1", "base_url": "https://api.batteryhealthcheck.co.uk/v1", "documentation": "https://marketplaces.batteryhealthcheck.co.uk", "updated": "2026-08-25", "read_this_first": [ "Every payload here comes from a real AVILOO test. Battery figures, diagnostic readings, warnings and statuses are exactly as recorded — nothing is invented, and any state we hold no real example of is simply absent from this file rather than made up. Identifiers are synthetic: VINs keep the manufacturer prefix and randomise the rest, registrations use a ZZ prefix DVLA never issues, mileage is rounded and dates are shifted. No real vehicle, dealer or customer can be identified from this file.", "Samples are illustrative. The OpenAPI specification at https://developers.batteryhealthcheck.co.uk/openapi.json and the data dictionary define the supported API contract.", "There is no sandbox environment. Build against these cases, then pilot against real tests from a dealer's own AVILOO unit.", "The awkward cases are the point. Any integration can handle 'test_final'. The ones that break in production are 'test_provisional', 'test_inconclusive' and 'test_legacy_no_diagnostics'.", "We never drop a key. Anything we do not hold is serialised as null, so the shape is stable — but you must null-check before rendering.", "Before publishing any number on a public page, branch on result_status. Then check vehicle_supported. They are orthogonal: a beta model can return a usable figure, and a supported model can return an inconclusive test." ], "cases": [ { "id": "test_final", "title": "Usable result — the normal case", "when": "AVILOO completed the test and reached a verdict on a fully supported model.", "what_your_code_should_do": "Publish freely. `result_status` is \"final\" and `vehicle_supported` is true.", "http_status": 200, "response": { "data": { "id": 9896, "internal_reference": "BHC-TEST-009896", "dealer_id": 247, "unit_id": 412, "status": "completed", "vehicle": { "registration": "ZZ25 FVN", "vin": "LSJWDKBTZEDP1GFAC", "make": "MG Automotive", "model": "MG4 Electric - 77,0 kWh", "year": null, "mileage_km": 13000 }, "battery": { "soh_percent": 99.1, "capacity_kwh": 76.26, "nominal_kwh": 77.0, "estimated_range_miles": 387, "cell_count": null, "cell_variance": 0.0055 }, "tested_at": "2026-09-14T17:38:01Z", "results_received_at": "2026-09-14T17:47:41Z", "diagnostics": { "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": 77.0, "gross_current": 76.258, "net_nominal_new": 74.4, "net_current": 73.683, "usable_nominal_new": 71.2, "usable_current": 70.514 }, "range": { "typical_new_miles": 390.36014365328435, "typical_current_miles": 386.5975639696448, "personal_new_miles": null, "personal_current_miles": null, "wltp_new_km": { "from": 435.0, "to": 450.0 }, "wltp_current_km": { "from": 430.8071483756883, "to": 445.6625672851948 } }, "measurements": { "cell_temperature_c": { "min": 17.5, "max": 18.5, "delta": 1.0, "status": "OK" }, "cell_voltage_v": { "min": 3.6659999999999977, "max": 3.67145911355888, "delta": 0.0054591135588824, "status": "OK" }, "pack_voltage_v": 396.5501152073733, "average_current_a": -1.0307336457921052, "mileage_km": 21000 }, "bms": { "soc_percent": 42.5, "soh_percent": 100.0, "soc_calculation_accuracy": 0.0, "soh_calculation_accuracy": 0.9638739366233722 }, "vehicle_supported": true }, "warnings": [], "vehicle_supported": true, "result_status": "final", "certificate_number": null, "certificate_available": true, "preview_available": true, "created_at": "2026-09-14T17:47:44Z", "updated_at": "2026-09-14T17:47:49Z" }, "meta": { "request_id": "req_a9f2e1c4b7d8" } } }, { "id": "test_provisional", "title": "Reading above 100% — do NOT publish the number", "when": "AVILOO's reference data for the model is not final, so state of health computes above 100%. The test is genuine and the certificate is valid.", "what_your_code_should_do": "Do not render the percentage. Show the certificate image instead, or a caveat. Branch on `result_status == \"provisional\"` and on the `SOH_GREATER_THAN_100` warning.", "http_status": 200, "response": { "data": { "id": 9354, "internal_reference": "BHC-TEST-009354", "dealer_id": 247, "unit_id": 412, "status": "completed", "vehicle": { "registration": "ZZ75 NZX", "vin": "LVHCR03Z278YCEE3Z", "make": "Honda", "model": "CR-V - 17,7 kWh", "year": null, "mileage_km": 7000 }, "battery": { "soh_percent": 105.8, "capacity_kwh": 18.72, "nominal_kwh": 17.7, "estimated_range_miles": null, "cell_count": null, "cell_variance": 0.0075 }, "tested_at": "2026-09-13T18:52:19Z", "results_received_at": "2026-09-13T18:54:48Z", "diagnostics": { "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": 17.7, "gross_current": 18.722, "net_nominal_new": 15.9, "net_current": 16.818, "usable_nominal_new": 15.9, "usable_current": 16.818 }, "range": { "typical_new_miles": null, "typical_current_miles": null, "personal_new_miles": null, "personal_current_miles": null, "wltp_new_km": { "from": 68.0, "to": 68.0 }, "wltp_current_km": { "from": 71.92673061415827, "to": 71.92673061415827 } }, "measurements": { "cell_temperature_c": { "min": 17.0, "max": 18.0, "delta": 1.0, "status": "OK" }, "cell_voltage_v": { "min": 4.022274999999996, "max": 4.029791666666657, "delta": 0.007516666666661287, "status": "OK" }, "pack_voltage_v": 386.50083333333333, "average_current_a": -1.3617070116861434, "mileage_km": 11000 }, "bms": { "soc_percent": 86.0, "soh_percent": 115.35900000000024, "soc_calculation_accuracy": 2.938975244674026, "soh_calculation_accuracy": 9.584396155649841 }, "vehicle_supported": false }, "warnings": [ "SOH_GREATER_THAN_100" ], "vehicle_supported": false, "result_status": "provisional", "certificate_number": null, "certificate_available": true, "preview_available": true, "created_at": "2026-09-13T18:54:49Z", "updated_at": "2026-09-14T11:45:28Z" }, "meta": { "request_id": "req_b1c2d3e4f5a6" } } }, { "id": "test_in_flight", "title": "Test started, result not landed yet", "when": "The dealer has begun a test. Nothing is known yet.", "what_your_code_should_do": "`result_status` is null — never assume \"final\" from null. Wait for the `bhc.test.completed` webhook rather than polling.", "http_status": 200, "response": { "data": { "id": 1612, "internal_reference": "BHC-TEST-001612", "dealer_id": 247, "unit_id": 412, "status": "in_progress", "vehicle": { "registration": null, "vin": "LSJZY6J9VHZZCFPBY", "make": "MG Automotive", "model": "ZS EV - 51,1 kWh", "year": null, "mileage_km": 50000 }, "battery": { "soh_percent": 90.3, "capacity_kwh": null, "nominal_kwh": null, "estimated_range_miles": null, "cell_count": null, "cell_variance": null }, "tested_at": "2026-09-10T19:13:29Z", "results_received_at": null, "diagnostics": null, "warnings": [ "CELL_VOLTAGE_SPREAD_CRITICALLY_HIGH" ], "vehicle_supported": true, "result_status": null, "certificate_number": null, "certificate_available": false, "preview_available": false, "created_at": "2026-09-11T11:45:21Z", "updated_at": "2026-09-14T17:30:16Z" }, "meta": { "request_id": "req_d3e4f5a6b7c8" } } }, { "id": "test_failed", "title": "Test could not complete", "when": "Interrupted, cancelled, or a hardware fault. Also delivered as the `bhc.test.failed` webhook.", "what_your_code_should_do": "There is no result and no certificate. Prompt a retest; refund if you charged up front.", "http_status": 200, "response": { "data": { "id": 9645, "internal_reference": "BHC-TEST-009645", "dealer_id": 247, "unit_id": 412, "status": "failed", "vehicle": { "registration": null, "vin": null, "make": null, "model": null, "year": null, "mileage_km": null }, "battery": { "soh_percent": null, "capacity_kwh": null, "nominal_kwh": null, "estimated_range_miles": null, "cell_count": null, "cell_variance": null }, "tested_at": "2026-09-14T00:38:07Z", "results_received_at": null, "diagnostics": null, "warnings": [], "vehicle_supported": true, "result_status": null, "certificate_number": null, "certificate_available": false, "preview_available": false, "created_at": "2026-09-14T00:40:26Z", "updated_at": "2026-09-14T00:40:26Z" }, "meta": { "request_id": "req_e5f6a7b8c9d0" } } }, { "id": "test_list", "title": "List response — envelope and pagination", "when": "GET /v1/tests?vin=… or GET /v1/tests?registration=…", "what_your_code_should_do": "Read `meta.has_more`, not the length of `data`. `per_page` is capped at 100.", "http_status": 200, "response": { "data": [ { "id": 9896, "internal_reference": "BHC-TEST-009896", "dealer_id": 247, "unit_id": 412, "status": "completed", "vehicle": { "registration": "ZZ25 FVN", "vin": "LSJWDKBTZEDP1GFAC", "make": "MG Automotive", "model": "MG4 Electric - 77,0 kWh", "year": null, "mileage_km": 13000 }, "battery": { "soh_percent": 99.1, "capacity_kwh": 76.26, "nominal_kwh": 77.0, "estimated_range_miles": 387, "cell_count": null, "cell_variance": 0.0055 }, "tested_at": "2026-09-14T17:38:01Z", "results_received_at": "2026-09-14T17:47:41Z", "diagnostics": { "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": 77.0, "gross_current": 76.258, "net_nominal_new": 74.4, "net_current": 73.683, "usable_nominal_new": 71.2, "usable_current": 70.514 }, "range": { "typical_new_miles": 390.36014365328435, "typical_current_miles": 386.5975639696448, "personal_new_miles": null, "personal_current_miles": null, "wltp_new_km": { "from": 435.0, "to": 450.0 }, "wltp_current_km": { "from": 430.8071483756883, "to": 445.6625672851948 } }, "measurements": { "cell_temperature_c": { "min": 17.5, "max": 18.5, "delta": 1.0, "status": "OK" }, "cell_voltage_v": { "min": 3.6659999999999977, "max": 3.67145911355888, "delta": 0.0054591135588824, "status": "OK" }, "pack_voltage_v": 396.5501152073733, "average_current_a": -1.0307336457921052, "mileage_km": 21000 }, "bms": { "soc_percent": 42.5, "soh_percent": 100.0, "soc_calculation_accuracy": 0.0, "soh_calculation_accuracy": 0.9638739366233722 }, "vehicle_supported": true }, "warnings": [], "vehicle_supported": true, "result_status": "final", "certificate_number": null, "certificate_available": true, "preview_available": true, "created_at": "2026-09-14T17:47:44Z", "updated_at": "2026-09-14T17:47:49Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false, "request_id": "req_0a1b2c3d4e5f" } } }, { "id": "webhook_test_completed", "title": "Webhook — a result has landed", "when": "Delivered to your endpoint when a test completes and the certificate is rendered.", "what_your_code_should_do": "Verify the Standard Webhooks signature, return 2xx immediately, then process asynchronously. We time out at 10 seconds.", "http_status": null, "response": { "event": "bhc.test.completed", "data": { "test": { "id": 9896, "internal_reference": "BHC-TEST-009896", "dealer_id": 247, "unit_id": 412, "status": "completed", "vehicle": { "registration": "ZZ25 FVN", "vin": "LSJWDKBTZEDP1GFAC", "make": "MG Automotive", "model": "MG4 Electric - 77,0 kWh", "year": null, "mileage_km": 13000 }, "battery": { "soh_percent": 99.1, "capacity_kwh": 76.26, "nominal_kwh": 77.0, "estimated_range_miles": 387, "cell_count": null, "cell_variance": 0.0055 }, "tested_at": "2026-09-14T17:38:01Z", "results_received_at": "2026-09-14T17:47:41Z", "diagnostics": { "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": 77.0, "gross_current": 76.258, "net_nominal_new": 74.4, "net_current": 73.683, "usable_nominal_new": 71.2, "usable_current": 70.514 }, "range": { "typical_new_miles": 390.36014365328435, "typical_current_miles": 386.5975639696448, "personal_new_miles": null, "personal_current_miles": null, "wltp_new_km": { "from": 435.0, "to": 450.0 }, "wltp_current_km": { "from": 430.8071483756883, "to": 445.6625672851948 } }, "measurements": { "cell_temperature_c": { "min": 17.5, "max": 18.5, "delta": 1.0, "status": "OK" }, "cell_voltage_v": { "min": 3.6659999999999977, "max": 3.67145911355888, "delta": 0.0054591135588824, "status": "OK" }, "pack_voltage_v": 396.5501152073733, "average_current_a": -1.0307336457921052, "mileage_km": 21000 }, "bms": { "soc_percent": 42.5, "soh_percent": 100.0, "soc_calculation_accuracy": 0.0, "soh_calculation_accuracy": 0.9638739366233722 }, "vehicle_supported": true }, "warnings": [], "vehicle_supported": true, "result_status": "final", "certificate_number": null, "certificate_available": true, "preview_available": true, "created_at": "2026-09-14T17:47:44Z", "updated_at": "2026-09-14T17:47:49Z", "dealer": { "id": 247, "name": "Example Motors (Salford)" } } } } }, { "id": "webhook_ping", "title": "Webhook — test ping. Carries NO vehicle or battery data", "when": "Sent when you or we press 'send test event'. It has its own event type on purpose.", "what_your_code_should_do": "Test events are notifications rather than complete result payloads. Branch on the event type before reading `data`, and retrieve the authoritative result before publishing battery-health information.", "http_status": null, "response": { "event": "bhc.webhook.test", "data": { "message": "This is a test event from Battery Health Check. It confirms your endpoint is reachable and your signature verification works. It does NOT describe a real vehicle or battery test.", "test_event": true, "endpoint_id": 77, "sent_at": "2026-08-25T09:00:00Z", "triggered_by": "partner" } } }, { "id": "error_invalid_field", "title": "Error — a field was rejected", "when": "A value failed validation. The envelope names the field.", "what_your_code_should_do": "Do not retry. Fix the request.", "http_status": 422, "response": { "error": { "code": "invalid_field", "message": "primary_contact_email is required", "request_id": "req_a9f2e1c4b7d8", "field": "primary_contact_email" } } }, { "id": "error_certificate_not_ready", "title": "Error — certificate not rendered yet", "when": "The test is complete but the PDF has not been produced yet. Requesting it kicks off rendering.", "what_your_code_should_do": "Wait `retry_after_seconds`, then retry. This is the one 4xx worth retrying.", "http_status": 409, "response": { "error": { "code": "certificate_not_ready", "message": "Certificate is not ready for this test yet", "request_id": "req_2c3d4e5f6071", "retry_after_seconds": 30 } } }, { "id": "error_insufficient_scope", "title": "Error — credential lacks the scope", "when": "A read-only key attempted a write, or a scope was not granted.", "what_your_code_should_do": "Do not retry. The dealer must issue a key with the right access level.", "http_status": 403, "response": { "error": { "code": "insufficient_scope", "message": "Token lacks the required scope for this operation", "request_id": "req_3d4e5f607182" } } }, { "id": "error_too_many_requests", "title": "Error — rate limited", "when": "A per-credential or per-IP limit was exceeded. No Retry-After header is sent.", "what_your_code_should_do": "Back off at least 60 seconds — limits are per-minute windows. See Rate limits in the docs.", "http_status": 429, "response": { "error": { "code": "too_many_requests", "message": "Rate limit exceeded", "request_id": "req_4e5f60718293" } } } ] }