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.
Sources
Several systems contribute to a single response. The Source column on every table below identifies which.
| Source | Meaning |
|---|---|
AVILOO result | Measured or reported by AVILOO for the completed test. |
AVILOO diagnostics | Drawn from AVILOO’s extended detail record. |
Vehicle BMS | Reported by the vehicle’s own battery management system and read by AVILOO. Not an independent measurement. |
Battery Health Check | Produced by BHC: identifiers, derived status fields and administrative timestamps. |
Dealer supplied | Entered 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.
| Field | Unit |
|---|---|
vehicle.mileage_km | miles, despite the name (legacy; use vehicle.odometer) |
vehicle.odometer.value | as given in vehicle.odometer.unit: km or mi |
vehicle.odometer.km | kilometres |
vehicle.odometer.miles | miles |
battery.capacity_kwh, battery.nominal_kwh | kWh, gross |
battery.usable_capacity_kwh, battery.usable_nominal_kwh | kWh, usable |
battery.soh_percent | percent |
battery.estimated_range_miles | miles |
diagnostics.range.*_miles | miles (whole), converted from AVILOO's km |
diagnostics.range.*_km | kilometres, 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_v | volts |
diagnostics.measurements.average_current_a | amps |
All *_at fields | ISO 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. |