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

Data dictionary

Every field the Partner API returns: its type, unit, whether it can be null, the values it may take, and which system produced it. Generated from the same definitions as the OpenAPI specification.

The OpenAPI specification and this page define the supported API contract. The sample response pack is illustrative.

Sources

Several systems contribute to a single response. The Source column on every table below identifies which.

SourceMeaning
AVILOO resultMeasured or reported by AVILOO for the completed test.
AVILOO diagnosticsDrawn from AVILOO’s extended detail record.
Vehicle BMSReported by the vehicle’s own battery management system and read by AVILOO. Not an independent measurement.
Battery Health CheckProduced by BHC: identifiers, derived status fields and administrative timestamps.
Dealer suppliedEntered by the dealer, or by a partner acting on their behalf.

Units

Units are not uniform across the payload. Each field name carries its unit, with two exceptions: vehicle.mileage_km carries miles, and diagnostics.measurements.mileage_km is the reading as AVILOO reports it (kilometres for most models). Use vehicle.odometer, which states its own unit and always gives km. This table lists them together.

FieldUnit
vehicle.mileage_kmmiles, despite the name (legacy; use vehicle.odometer)
vehicle.odometer.valueas given in vehicle.odometer.unit: km or mi
vehicle.odometer.kmkilometres
vehicle.odometer.milesmiles
battery.capacity_kwh, battery.nominal_kwhkWh, gross
battery.usable_capacity_kwh, battery.usable_nominal_kwhkWh, usable
battery.soh_percentpercent
battery.estimated_range_milesmiles
diagnostics.range.*_milesmiles (whole), converted from AVILOO's km
diagnostics.range.*_kmkilometres, as AVILOO reported them
diagnostics.range.wltp_*kilometres, as {from, to}
diagnostics.energy_kwh.*kWh
diagnostics.measurements.cell_temperature_c°C, as {min, max, delta, status}
diagnostics.measurements.cell_voltage_v, pack_voltage_vvolts
diagnostics.measurements.average_current_aamps
All *_at fieldsISO 8601, UTC, Z suffix

Test

A single battery test. Returned by GET /tests and GET /tests/{id}, and embedded in the bhc.test.completed webhook.

Field Type Unit Null Source Values Description
id integer no Battery Health Check BHC identifier for the test.
internal_reference string yes Dealer supplied Partner-defined identifier. Stored against the test and returned unchanged, so a partner can correlate BHC records with records in its own platform. Maximum 100 characters. Not validated for uniqueness, and not currently editable once set.
dealer_id integer yes Battery Health Check The dealer the test belongs to.
unit_id integer yes Battery Health Check The AVILOO unit that performed the test.
status string yes Battery Health Check pending, in_progress, completed, failed, cancelled, null Lifecycle state of the test record.
vehicle object yes AVILOO result The vehicle tested.
battery object yes AVILOO result Headline battery figures.
tested_at string yes AVILOO result When the test was performed.
results_received_at string yes AVILOO result When AVILOO completed the test: its completion time, not the time Battery Health Check received the result.
diagnostics object yes AVILOO diagnostics AVILOO's extended detail record, normalised. Null on tests recorded before detail capture, and on tests that have not completed.
warnings array yes AVILOO result AVILOO warning codes raised on this test, for example SOH_GREATER_THAN_100 or UNCLEAR_MODEL. An empty array means no warnings were raised. Null means no AVILOO payload is stored for this test, which is not the same statement.
warning_details array yes AVILOO result The same warnings with AVILOO's own sentence for each: one item per entry of warnings, in the same order, each {code, text, public_display}. code is the entry of warnings; text is AVILOO's explanation and advice, in English, or null when AVILOO sent none we can pair with the code. public_display is always false: the sentences are AVILOO's advice to whoever ran the test (for example to visit a workshop), not copy for an advert. Null exactly when warnings is null; an empty array when there are no warnings.
vehicle_supported boolean yes AVILOO result False while the vehicle model is still in AVILOO validation. Describes the model, not this result — see result_status for the result.
result_status string yes Battery Health Check final, provisional, inconclusive, null How the measured State of Health should be treated. final: a complete result. provisional: a value was produced but AVILOO reference data for the model is not final, and the value is above 100. inconclusive: AVILOO completed the test without reaching a result, and no value will follow. Null: the test is still running, stopped before it finished (failed or cancelled), or completed without a result recorded. Describes this result; vehicle_supported describes the model.
error_reason string yes AVILOO result AVILOO's code for why the test stopped, passed through unchanged, for example DONGLE_NO_VEHICLE_EXCEPTION, DONGLE_UNKNOWN_VIN_EXCEPTION, DONGLE_SIDE_TIMEOUT or INCOMPLETE. Null for a test that did not stop. Treat an unrecognised code as unknown rather than as an error.
result_type string yes AVILOO result OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's overall result for the test: OK, WARNING (a finding about the vehicle), SAFETY_ISSUE (a safety-level finding) or NOT_CONCLUSIVE (no verdict). Null until AVILOO has evaluated the test, and on tests that did not complete.
provider_state string yes AVILOO result AVILOO's own state for the test, passed through unchanged: NEW, WAITING_FOR_VEHICLE, DATA_ACQUISITION, EXECUTION_DONE, EXECUTION_ERROR, EVALUATING, VERIFYING, EVALUATION_DONE or EVALUATION_ERROR. Finer than status, which is our reading of it; branch on status and use this for detail. Null when no AVILOO record is stored for the test. Treat an unrecognised value as unknown rather than as an error.
certificate_number string yes Battery Health Check Battery Health Check's own reference for the test's certificate, not AVILOO's certificate number (the AVILOO certificate is checked through its QR code). For example BHC-7K2M-Q9XD-4HTA: BHC- and twelve characters chosen at random from the digits and the capital letters except I, L, O and U, in three groups of four. It carries no meaning (no date, no count), so never parse it or infer order from it. Given once the test's certificate is available and never changed afterwards, so it is safe to store. Null when the test has no certificate (certificate_available false). It can also be null for a while after certificate_available becomes true, until the number is given; read the test again later. It is not the number printed on the certificate documents: those carry AVILOO's own certificate number (masked on the anonymised copy and the image), a different value the API does not return.
certificate_available boolean no Battery Health Check Whether this test has a certificate: true once its full certificate PDF is stored. A dealer credential can then retrieve the full PDF. A platform, marketplace or sandbox credential receives the anonymised copy only, which it can then request; the first request for a copy not stored yet answers 409 certificate_not_ready and fetches it, so retry (see certificate_documents).
preview_available boolean no Battery Health Check Whether the public-facing certificate image can be retrieved.
certificate_documents array no Battery Health Check Both certificate PDFs, full first, each {variant, available, path, content_type, public_display, withheld_reason}, as the warranty block's documents lists the warranty PDFs. full shows the VIN and is never for a public page (public_display false); its path is GET /v1/tests/{id}/certificate. anonymised hides the VIN (public_display true); its path is GET /v1/tests/{id}/certificate?variant=anonymised. Which copies a public page may use is set by the Platform Terms. available is certificate_available for both: it says the copy can be requested, not that it is stored. A copy not stored yet answers 409 certificate_not_ready and is fetched, so retry. An anonymised copy AVILOO declined to produce answers 404 not_found at its path for a day while available stays true: fall back to the preview image. The battery-readings documents list says instead whether each copy is stored right now, so there certificate_pdf_anonymised can be available: false while it is true here. path and content_type are null when available is false. Additive (7 Oct 2026). The full copy goes to dealer credentials only: to a platform, marketplace or sandbox credential the full item has available false, path and content_type null and withheld_reason DEALER_CREDENTIALS_ONLY, so the list keeps its shape. withheld_reason is null on every other item. Platforms: each copy with public_display true is one that clause 5 of the Platform Terms names for public pages. The preview image and the anonymised certificate carry the test's result, so they go on a public page only when the test's publish decision has image.publishable true, whatever public_display says.
warranty_available boolean no Battery Health Check Whether an AVILOO battery warranty document can be retrieved for this vehicle. Fetching it needs the read:warranties scope.
warranty_state string yes AVILOO result AVILOO's own battery-warranty state, passed through unchanged. Null means we have not established a state for this test, which is NOT the same as NONE — that means AVILOO assessed the vehicle and issued no warranty. Treat an unrecognised value as unknown rather than as an error: AVILOO may add states, and their published list is not exhaustive.
warranty_reasons array yes AVILOO result Why AVILOO did not issue a warranty, as AVILOO's own codes, for example VEHICLE_NOT_SUPPORTED, FLASH_TEST_RESULT_NOT_OK, WARRANTY_LIMIT_MISSING, ACTIVE_DTC_CODES (active fault codes at the time of the test) or SOH_BELOW_CUTOFF. A test can carry more than one. Null exactly when warranty_state is null. An empty array means there is nothing to explain, and it can be empty even when warranty_state is INELIGIBLE: codes that concern the account rather than the vehicle are not published. Treat an unrecognised code as unknown rather than as an error.
created_at string yes Battery Health Check When the record was created.
updated_at string yes Battery Health Check When the record was last updated.
warranty object yes Battery Health Check The battery warranty on this test, as the warranty block: its state, dates and limits as the provider sent them, the document, and a link to the provider's own conditions. The flat warranty_available, warranty_state and warranty_reasons keys are unchanged and carry the same values. Null exactly when warranty_state is null.
dealer object no Battery Health Check The dealer that ran the test, {id, name}. Present on GET /tests/{test_id}, on GET /tests results and in webhook payloads.

Test.vehicle

The vehicle the test was performed on.

Field Type Unit Null Source Values Description
registration string yes Dealer supplied Vehicle registration as recorded against the test. Not present on every test. Registrations can be transferred between vehicles, so match on vin where one is available.
vin string yes AVILOO result Vehicle Identification Number, 17 characters. The stable identifier for matching a result to a vehicle record.
make string yes AVILOO result Manufacturer as reported by AVILOO.
model string yes AVILOO result Model as reported by AVILOO. The value often includes the pack size, for example MG4 Electric - 77,0 kWh, and uses a decimal comma. Treat it as a display string rather than a normalised model code.
year integer yes Battery Health Check The year the vehicle was first registered, read from its registration record, which Battery Health Check looks up for the VIN. It is not the model year, and AVILOO does not report it. Null when no registration record is held for the vehicle.
mileage_km number miles yes AVILOO result Legacy field: despite its name, this carries the odometer in miles, not kilometres. It is AVILOO's reading converted on the assumption that the reading was in kilometres, which is wrong for the few models that report miles themselves. Kept unchanged for existing integrations; use odometer instead.
odometer object yes AVILOO result The odometer reading at the time of test, as AVILOO reported it. value is the reading; unit is the unit it is in, km for almost every model and mi for the few models that report miles themselves; km is the same reading in kilometres. Use km to compare tests, and value with unit to show the reading as recorded. Null when no reading is held for the test.
powertrain string yes AVILOO result BEV, PHEV, HEV, null AVILOO's category for the vehicle, passed through unchanged: BEV (battery electric), PHEV (plug-in hybrid) or HEV (hybrid). Null on tests recorded before AVILOO published the category. Treat an unrecognised value as unknown rather than as an error: the list is AVILOO's and also names non-car categories.
model_group_id string yes AVILOO result AVILOO's identifier for the model group it tested the vehicle as, for example VMD-0638. Stable for every test of the same model group, so use it to group results by model: model is a display string, and GET /tests?model_group_id= filters on it. Null when AVILOO did not identify the model, as on most tests that did not complete.

Test.battery

Headline battery figures. Interpret alongside result_status before displaying publicly.

Field Type Unit Null Source Values Description
soh_percent number percent yes AVILOO result State of Health measured by AVILOO. Interpret together with result_status before displaying this value. Values above 100 occur on models still in AVILOO validation.
capacity_kwh number kWh yes AVILOO result Gross energy the pack holds at the measured state of health: the whole pack, part of which the car keeps in reserve. For the energy a driver can use, read usable_capacity_kwh.
nominal_kwh number kWh yes AVILOO result Gross energy the pack held when new. For the usable figure, read usable_nominal_kwh.
estimated_range_miles number miles yes AVILOO result AVILOO's typical real-world range at the measured state of health, in whole miles (AVILOO reports it in kilometres; the figure is converted). The same figure as diagnostics.range.typical_current_miles. Null where AVILOO did not derive one, or where AVILOO's range is inconsistent with the car's own official (WLTP) figure: such a range is withheld, not guessed (see diagnostics.range).
cell_count integer yes AVILOO result Reserved, and null on every test today: AVILOO's result does not report a cell count. Kept so the key never disappears.
cell_variance number volts yes AVILOO result Spread across cell voltages. Lower values indicate a more balanced pack.
usable_capacity_kwh number kWh yes AVILOO diagnostics Usable energy at the measured state of health: what a driver can draw, from AVILOO's detail record. Null when no detail record is held for the test.
usable_nominal_kwh number kWh yes AVILOO diagnostics Usable energy when new, from AVILOO's detail record. Null when no detail record is held for the test.

Test.diagnostics

AVILOO's extended detail record, normalised. Null where no detail record is held.

Field Type Unit Null Source Values Description
overall_battery_status string yes AVILOO diagnostics OK, WARNING, NOT_CONCLUSIVE, SAFETY_ISSUE, null AVILOO's overall assessment of the pack.
soh_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for its own state-of-health reading (battery.soh_percent): OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
battery_checks object yes AVILOO diagnostics Per-check results: battery_management_system, battery_sensors, battery_pack_parameters, battery_cell_voltages, vehicle_communication. Each value is a status string.
sensor_checks object yes AVILOO diagnostics Per-sensor results: voltage_sensor, current_sensor, temperature_sensors, cell_voltage_sensors. Each value is a status string.
energy_kwh object kWh yes AVILOO diagnostics Gross, net and usable energy, each given when new and at the measured state.
range object yes AVILOO diagnostics AVILOO's range figures. AVILOO reports its ranges in kilometres: the *_km keys carry its figure unchanged, and the *_miles keys the same figure converted to whole 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 it is withheld, not guessed: the typical and personal keys, *_miles and *_km alike, are null, as is battery.estimated_range_miles. Typical and personal range are as AVILOO models them; personal range is null on most tests. WLTP figures are kilometres, as {from, to} objects. Any of these may be null.
measurements object yes AVILOO diagnostics Cell temperature (°C) and cell voltage (V) as {min, max, delta, status}, each of min, max and delta with its own status (min_status, max_status, delta_status); pack voltage (V), average current (A) and mileage (km) as scalars, the first two with their statuses (pack_voltage_status, average_current_status).
bms object yes Vehicle BMS Values reported by the vehicle's own battery management system, and AVILOO's assessment of how accurate each is, with AVILOO's status for each (soc_status, soh_status, soc_accuracy_status, soh_accuracy_status). These are the vehicle's self-reported figures. battery.soh_percent is AVILOO's independent measurement; the two are separate fields and may differ.
vehicle_supported boolean yes AVILOO diagnostics Model-level support flag as recorded in the detail record. Mirrored at the top level of the test object.

Test.diagnostics.measurements

The measurements object of diagnostics: AVILOO’s readings during the test, each with its own status.

Field Type Unit Null Source Values Description
cell_temperature_c object yes AVILOO diagnostics Cell temperatures. Null when the detail record holds none.
cell_voltage_v object yes AVILOO diagnostics Cell voltages. Null when the detail record holds none.
pack_voltage_v number volts yes AVILOO diagnostics Pack voltage.
average_current_a number amps yes AVILOO diagnostics Average current during the test.
mileage_km number km yes AVILOO diagnostics AVILOO's odometer reading exactly as sent: kilometres for almost every model, miles for the few that report miles themselves. vehicle.odometer gives the reading with its unit; prefer it.
pack_voltage_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for pack_voltage_v: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
average_current_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for average_current_a: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.

Test.diagnostics.measurements.cell_temperature_c

cell_temperature_c and cell_voltage_v have the same fields, in °C and in volts.

Field Type Unit Null Source Values Description
min number °C yes AVILOO diagnostics The lowest cell temperature.
max number °C yes AVILOO diagnostics The highest cell temperature.
delta number °C yes AVILOO diagnostics The spread between the highest and lowest cell temperature.
status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for the cell temperatures as a whole: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
min_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for min: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
max_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for max: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
delta_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for delta: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.

Test.diagnostics.bms

The bms object of diagnostics: what the vehicle’s own battery management system reported, and AVILOO’s assessment of it.

Field Type Unit Null Source Values Description
soc_percent number percent yes Vehicle BMS State of charge as the vehicle's BMS reported it.
soh_percent number percent yes Vehicle BMS State of health as the vehicle's BMS reported it: the vehicle's self-assessment, not AVILOO's measurement (battery.soh_percent).
soc_calculation_accuracy number yes AVILOO diagnostics AVILOO's figure for how accurate the BMS state of charge is.
soh_calculation_accuracy number yes AVILOO diagnostics AVILOO's figure for how accurate the BMS state of health is.
soc_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for soc_percent: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
soh_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for soh_percent: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
soc_accuracy_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for soc_calculation_accuracy: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.
soh_accuracy_status string yes AVILOO diagnostics OK, WARNING, SAFETY_ISSUE, NOT_CONCLUSIVE, null AVILOO's status for soh_calculation_accuracy: OK, WARNING, SAFETY_ISSUE or NOT_CONCLUSIVE. Null when the detail record does not carry it.

Test.warranty

The battery warranty on a test, in one normalised shape: the warranty key of the test object. Null exactly when warranty_state is null.

Field Type Unit Null Source Values Description
provider string no Battery Health Check Who provides the warranty, as a provider key: aviloo.
product string no Battery Health Check The provider's warranty product.
issuer object no Battery Health Check The legal entity that gives the warranty: name, and country as an ISO 3166-1 alpha-2 code.
state string no AVILOO result The warranty state, exactly as warranty_state. Treat an unrecognised value as unknown rather than as an error.
state_changed_at string yes Battery Health Check When this state was first recorded.
as_of string yes Battery Health Check When the state was last confirmed with the provider. Show it beside the state.
created_at string yes AVILOO result When the provider created the warranty, as it sent it. Null until the provider has sent it: it arrives with the provider's warranty notices, so a warranty issued before we received those has none.
issued_at string yes AVILOO result Start of the warranty period, as the provider sent it. Null until the provider has sent it.
expires_at string yes AVILOO result End of the warranty period, as the provider sent it. Null until the provider has sent it.
mileage_limit object yes AVILOO result The distance limit of the warranty: value and its unit (km or mi). Null until the provider has sent both: a limit sent without its unit is not published, because we never assume a unit. The limit is stated on the warranty document itself.
soh_threshold_percent number percent yes AVILOO result The state-of-health threshold the warranty is measured against, as the provider sent it. Null until the provider has sent it.
compensation object yes AVILOO result Reserved: {amount, currency}. Always null in production; the sandbox shows an invented value so an integration meets the shape.
reasons array no AVILOO result Exactly warranty_reasons: why no warranty was issued, as the provider's own codes.
document object no Battery Health Check The document GET /v1/tests/{id}/warranty serves your credential without a variant: for a dealer credential the full warranty document, which shows the VIN and is never for a public page; for a platform or sandbox credential, which receives the anonymised copies only, the anonymised one. available is exactly warranty_available; path is GET /v1/tests/{id}/warranty (scope read:warranties) and content_type is application/pdf, both null when no document is available. documents names both versions. A marketplace credential cannot download warranty documents (read:warranties is not issued to a marketplace): show an active warranty with warranty_status on the publish decision.
documents array no Battery Health Check Both warranty documents, full first, each {variant, available, path, content_type, public_display, withheld_reason}. full shows the VIN, and public_display is false; for a dealer credential it is the document document describes (for a platform or sandbox credential document describes the anonymised one). anonymised hides the VIN and may be shown on a public page such as an advert (public_display true); its path is GET /v1/tests/{id}/warranty?variant=anonymised. available is warranty_available for both; path and content_type are null when no document is available. The preview images are in images. The full copy goes to dealer credentials only: to a platform, marketplace or sandbox credential the full item has available false, path and content_type null and withheld_reason DEALER_CREDENTIALS_ONLY, so the list keeps its shape. withheld_reason is null on every other item.
images array no Battery Health Check The warranty preview images (JPEG), full first, each with the keys of a documents item. anonymised hides the VIN and may be shown on a public page such as an advert (public_display true); its path is GET /v1/tests/{id}/warranty?format=image&variant=anonymised, and available is warranty_available, except while the provider is not supplying the image, when it is false for a day (the path answers 404). full shows the VIN (public_display false) and is not served: it is listed, always with available false, so that the list keeps its shape. path and content_type are null when available is false. withheld_reason is null on both items today: the full image is served to no credential, dealers included, so it is not withheld from yours in particular. If it is ever served, it goes to dealer credentials only, and a platform, marketplace or sandbox credential's full item will read withheld_reason DEALER_CREDENTIALS_ONLY, as in documents. Platforms: each copy with public_display true is one that clause 5 of the Platform Terms names for public pages. The preview image and the anonymised certificate carry the test's result, so they go on a public page only when the test's publish decision has image.publishable true, whatever public_display says.
terms_url string yes Battery Health Check The provider's own page for the warranty's conditions. The conditions are the provider's to state: link to them rather than restating them.
source string no Battery Health Check provider_record, sandbox_illustrative provider_record: the provider's own record, relayed unchanged. sandbox_illustrative: invented sandbox data.

PublishBlock

Battery Health Check's decision on what may be published about one test. Returned by GET /tests/{id}/publish and embedded in each batch lookup result. Contains no VIN.

Field Type Unit Null Source Values Description
object string no Battery Health Check publish Always publish.
version string no Battery Health Check statements-v4 The wording and rules version. A change to any sentence or rule ships under a new version.
test_id integer no Battery Health Check The test this decision is about.
publishable boolean no Battery Health Check Battery Health Check's decision: true when the figure, its grade and the copy may be published beside this car. Read this rather than deciding from the test fields yourself.
reason string no Battery Health Check OK, AMBIGUOUS_REGISTRATION, NO_RESULT_YET, TEST_DID_NOT_COMPLETE, INCONCLUSIVE, PROVISIONAL_OVER_100, DISPUTED, SUPERSEDED, SAFETY_FINDING, AVILOO_FINDING, RESULT_NOT_RECORDED, CHECKS_NOT_ALL_OK, MODEL_IN_VALIDATION, MODEL_SUPPORT_UNKNOWN, TEST_OLDER_THAN_90_DAYS, ADVERT_MILEAGE_PAST_TEST, ADVERT_MILEAGE_BELOW_TEST OK when publishable; otherwise the first entry in reasons.
reasons array no Battery Health Check AMBIGUOUS_REGISTRATION, NO_RESULT_YET, TEST_DID_NOT_COMPLETE, INCONCLUSIVE, PROVISIONAL_OVER_100, DISPUTED, SUPERSEDED, SAFETY_FINDING, AVILOO_FINDING, RESULT_NOT_RECORDED, CHECKS_NOT_ALL_OK, MODEL_IN_VALIDATION, MODEL_SUPPORT_UNKNOWN, TEST_OLDER_THAN_90_DAYS, ADVERT_MILEAGE_PAST_TEST, ADVERT_MILEAGE_BELOW_TEST Every reason the test cannot be published, most important first. Empty when publishable. Treat an unrecognised code as a reason not to publish.
result_status string yes Battery Health Check final, provisional, inconclusive, null The same value as result_status on the test.
vehicle_supported boolean yes AVILOO result The same value as vehicle_supported on the test.
soh_display string yes Battery Health Check The state of health exactly as it may be quoted, floored to one decimal place and never rounded up, for example 96.4%. Null when not publishable.
band object yes AVILOO result AVILOO's own grade for the test, read off its certificate: the one grade to show, named as AVILOO's (for example AVILOO: Good health). Null when not publishable, and while AVILOO's grade has not been read (must_not_say then holds NO_GRADE).
tested_on string yes Battery Health Check The date of the test, as a UK date (Europe/London). Null when the test has no date.
valid_until string yes Battery Health Check When the decision lapses: 90 days after the test. Null when not publishable. Fetch it again on bhc.test.completed or bhc.test.warranty_changed for the same car.
current_test_id integer yes Battery Health Check The test that speaks for this car: its most recent completed test with a battery-health figure or, when no completed test has one, its most recent test. Only tests of the same VIN that this credential can read are compared; a platform's are compared only within the dealer that owns this test.
superseded_by integer yes Battery Health Check The newer completed test with a battery-health figure that replaces this one, when reasons includes SUPERSEDED; otherwise null.
image object no Battery Health Check The preview image and whether it may be shown.
copy object yes Battery Health Check Ready-made advert text. Null when not publishable, and when copy_withheld_reason is set.
copy_withheld_reason string yes Battery Health Check REGION_NOT_REVIEWED, COPY_VALIDATION_FAILED, null Why copy and statements are empty for a reason other than publishable. REGION_NOT_REVIEWED: the dealer trades outside the UK and the wording has not been reviewed for that market; the figure itself is still publishable. COPY_VALIDATION_FAILED: the wording failed its own checks and was withheld.
statements array no Battery Health Check Plain sentences for a person or an assistant to repeat as given. When publishable: the result, AVILOO's grade (when known), the checks (when every one was OK) and that the figure is dated. When not: one sentence explaining reason. Empty when copy_withheld_reason is set.
must_not_say array no Battery Health Check What never to write about this result, as stable codes with plain words.
warnings array no Battery Health Check Notices about this response, separate from the test's own warnings. Empty for live data.

PublishBlock.band

The grade, when the result is publishable.

Field Type Unit Null Source Values Description
scheme string no AVILOO result aviloo Always aviloo: the grade is AVILOO's own, printed on its certificate and judged against similar vehicles (since 11 Nov 2026; Battery Health Check's own 90/80/70 scale is retired).
code string no AVILOO result outstanding, excellent, good, fair, poor AVILOO's grade, as a stable code.
label string no AVILOO result Outstanding health, Excellent health, Good health, Fair health, Poor health AVILOO's grade in its own words, for example Good health. Show it named as AVILOO's.
range string no Battery Health Check Judged by AVILOO against similar vehicles What the grade covers: always Judged by AVILOO against similar vehicles (it held the figures of Battery Health Check's own scale until 11 Nov 2026).
short string no AVILOO result Outstanding, Excellent, Good, Fair, Poor The grade's first word, for a badge: AVILOO: Good.
headline string no AVILOO result The verdict exactly as AVILOO prints it, for example GOOD HEALTH - NO ABNORMALITIES DETECTED.
source string no Battery Health Check aviloo_certificate Where the grade was read: always aviloo_certificate.

PublishBlock.image

The preview image and whether it may be shown.

Field Type Unit Null Source Values Description
publishable boolean no Battery Health Check Whether the VIN-free preview image may be shown for this test. It can be true when publishable is false: a provisional figure, a model still in validation or an older test can still show the image, which carries its own date. It is false when any failing reason rules the image out, for example a safety finding or a newer test.
reason string no Battery Health Check OK, AMBIGUOUS_REGISTRATION, NO_RESULT_YET, TEST_DID_NOT_COMPLETE, INCONCLUSIVE, PROVISIONAL_OVER_100, DISPUTED, SUPERSEDED, SAFETY_FINDING, AVILOO_FINDING, RESULT_NOT_RECORDED, CHECKS_NOT_ALL_OK, MODEL_IN_VALIDATION, MODEL_SUPPORT_UNKNOWN, TEST_OLDER_THAN_90_DAYS, ADVERT_MILEAGE_PAST_TEST, ADVERT_MILEAGE_BELOW_TEST OK when the image may be shown; otherwise the first reason in reasons that rules it out.
available boolean no Battery Health Check Whether the preview image is ready to fetch now. The same fact as preview_available on the test.
path string yes Battery Health Check Where to fetch the image: /v1/tests/{id}/preview, which returns a short-lived signed link. Null when the image may not be shown. The path already starts /v1/: it is relative to the host, https://api.batteryhealthcheck.co.uk, not to the /v1 base URL.

PublishBlock.copy

Ready-made advert text, when the result is publishable.

Field Type Unit Null Source Values Description
seller_highlight string no Battery Health Check A Seller Highlight for Auto Trader and similar slots, at most 55 characters, for example Battery health 96.4% (AVILOO: Excellent), Sep 2026.
attention_grabber string no Battery Health Check An Attention Grabber, at most 30 characters, for example Battery health 96.4% (Sep '26). The test month is written with an apostrophed year (Sep '26), so it never reads as a day of the month.
description string no Battery Health Check One to three sentences for the advert description. Use it as given.

PublishBlock.statements[]

One entry of statements.

Field Type Unit Null Source Values Description
id string no Battery Health Check result, grade, checks, dated, reason What the sentence says: result, grade (AVILOO's grade, when known), checks and dated when the test is publishable; reason (one sentence explaining reason) when it is not.
text string no Battery Health Check The sentence. Use it exactly as given.

PublishBlock.must_not_say[]

One entry of must_not_say.

Field Type Unit Null Source Values Description
code string no Battery Health Check NO_ROUNDING, DATE_REQUIRED, NO_AVILOO_MARKS, NO_UNATTRIBUTED_GRADE, NO_TEXT_ON_IMAGES, NO_CERTIFIED_CLAIM, NO_WARRANTY_CLAIM, NO_AS_NEW, NO_RANGE_PROMISE, NO_COMPARISON, NO_PREDICTION, NO_VIN, NO_FIGURE, SHOW_CERTIFICATE_ONLY, NO_GRADE, NO_UNTESTED_FIGURE A stable code. Branch on this, not on text.
text string no Battery Health Check The rule in plain words, for a person or an assistant. It may be reworded; the code will not change.

LookupResult

One vehicle’s result from POST /tests/lookup, in the order the vehicles were sent.

Field Type Unit Null Source Values Description
object string no Battery Health Check lookup_result Always present, so a stream of items can be told apart.
index integer no Battery Health Check The position of this vehicle in the vehicles array you sent, from 0. Results are returned in the same order.
ref string yes Dealer supplied Your own identifier for the vehicle, echoed unchanged: up to 64 characters of letters, digits, dot, underscore, colon and hyphen. Null when you sent none, or when it failed validation.
query object no Battery Health Check What was looked up.
matched_on string yes Battery Health Check vin, registration, null Which key found the tests: vin, or registration when no VIN was sent. When both are sent the VIN is used and the registration ignored. Null when nothing was found.
found boolean yes Battery Health Check Whether any test of this vehicle is within your reach. Null when the item has an error: it was not looked up.
tests_found integer yes Battery Health Check How many tests matched. Null with an error.
distinct_vins integer yes Battery Health Check How many different VINs the matched tests carry. Null with an error.
ambiguous boolean yes Battery Health Check True when a registration matched tests of more than one VIN: the plate has been transferred between vehicles. Do not merge them; look up latest_test.vehicle.vin, or resend with a VIN. Both publish decisions are then never publishable and give AMBIGUOUS_REGISTRATION as their first reason, because the tests may be another car's. latest_test and current_test are still served, so you can compare their vehicle.vin with your own. Null with an error.
latest_test object yes Battery Health Check The newest matched test, exactly as GET /tests/{id} returns it (with the slim dealer object). Null when nothing was found.
current_test object yes Battery Health Check The test that speaks for the vehicle, exactly as GET /tests/{id} returns it (with the slim dealer object): the one publish.current_test_id names, that is its most recent completed test with a battery-health figure or, when no completed test has one, its most recent test, compared exactly as that field compares them. Usually the same test as latest_test; it differs when the newest test is a failed or inconclusive retest of a car with an earlier result. Show this test, not latest_test. Null when publish names no current test, as when nothing was found. On a marketplace credential that is not narrowed to named dealer groups, it is also null when you could not read the test by id after this lookup: a VIN lookup covers every test of the VIN, a registration lookup only the tests that carry that registration. publish.current_test_id still gives its id; look the vehicle up by latest_test.vehicle.vin to get it.
publish object yes Battery Health Check The publish decision for latest_test, exactly as GET /tests/{id}/publish returns it, judged within that test's own dealer, except that it is never publishable when ambiguous is true (reason AMBIGUOUS_REGISTRATION). Null when nothing was found.
current_publish object yes Battery Health Check The publish decision for current_test, made exactly as publish is: the same mileage_miles, judged within the test's own dealer, and never publishable when ambiguous is true. The same object as publish when the current test is the latest one. Read this one to decide what to show beside current_test; no second GET /tests/{id}/publish call is needed. Null exactly when current_test is null. Additive (7 Oct 2026).
error object yes Battery Health Check Why this vehicle could not be looked up, or null. One bad vehicle never fails the batch.
warnings array no Battery Health Check Notes about this item, as stable codes. Not the same field as a test's own warnings, which carries AVILOO's codes. Ignore codes you do not recognise.

LookupResult.query

What was looked up for that vehicle.

Field Type Unit Null Source Values Description
vin string yes Dealer supplied The VIN you sent. Each value is shown as it was matched: the VIN upper-cased, the registration with spaces and hyphens removed. Null when not supplied, or when it failed validation.
registration string yes Dealer supplied The registration you sent. Each value is shown as it was matched: the VIN upper-cased, the registration with spaces and hyphens removed. Null when not supplied, or when it failed validation.

LookupResult.error

Why one vehicle in a batch was not looked up. One bad vehicle never fails the batch.

Field Type Unit Null Source Values Description
code string no Battery Health Check invalid_field Why this vehicle was not looked up. Always invalid_field today; branch on it, not on message.
field string no Battery Health Check The offending field of this vehicle: vin, registration, ref, mileage_miles, make, model, year, fuel, or vehicles when the entry is not an object.
message string no Battery Health Check A readable explanation.

WebhookEndpoint

A registered webhook endpoint.

Field Type Unit Null Source Values Description
id integer no Battery Health Check BHC identifier for the endpoint.
url string no Dealer supplied Destination URL. HTTPS only.
events array yes Dealer supplied bhc.dealer.activated, bhc.test.completed, bhc.test.failed, bhc.test.warranty_changed, null Event types delivered to this endpoint.
disabled_at string yes Battery Health Check Set when the endpoint was disabled after repeated delivery failures.
consecutive_failures integer no Battery Health Check Consecutive failed deliveries. Resets on a successful delivery.
last_success_at string yes Battery Health Check Last successful delivery.
last_attempt_at string yes Battery Health Check Last delivery attempt.
last_failure object yes Battery Health Check The most recent failed delivery attempt and why, or null when none has been recorded. It stays after a later success, so compare at with last_success_at; consecutive_failures says whether the endpoint is failing now. Additive (7 Oct 2026); failures before that date were not recorded.
created_at string yes Battery Health Check When the endpoint was registered.
secret string yes Battery Health Check Signing secret. Returned once, when the endpoint is created, and not retrievable afterwards.