Battery Health CheckDevelopers
OpenAPI Samples Postman

Dealer group and platform API. For dealer groups using their own tests, and for software that many dealers use. Running a car-listing site? Marketplace 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.
DVLA / DVSA recordThe registered vehicle details Battery Health Check already holds for a VIN (for an Irish vehicle, its Irish registration details), and the car’s DVSA MOT history (DVSA’s own, synced nightly, or the copy held with the vehicle record). Test passport only; the source field on each block says exactly where it came from. Never for a public page.
ProviderReported by the provider that a battery reading or a provenance check names in its own provider field, in that provider’s own terms. That is AVILOO for every battery reading and, in production, DVSA or the vehicle record provider for every provenance check. Battery readings and provenance only.
Battery Health Check valuationBattery Health Check’s own value for a car, in the valuation’s value grid. Beta: invented figures in the sandbox now; production figures follow, and production serves none today. Valuation only.

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} and in webhook payloads, and on GET /tests results for platform, sandbox and marketplace credentials; absent from a dealer-group credential's GET /tests results.

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. MULTIPLE_DEALERS (platform credentials only): no dealer_id was sent and the vehicle matched tests at more than one of the dealers you are connected to. This answer comes from the dealer whose test is newest and can still be publishable, so do not put it on a dealer's page: send dealer_id, so that the answer is the advertising dealer's own. Never given when ambiguous is true: those tests are of different vehicles, so send the VIN first.

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.

Dealer

A dealer or branch. Returned by GET /dealers and GET /dealers/{id}.

Field Type Unit Null Source Values Description
id integer no Battery Health Check BHC identifier for the dealer.
name string yes Dealer supplied Trading name.
legal_name string yes Dealer supplied Registered legal name.
status string yes Battery Health Check pending, active, suspended, closed, null Account state.
billing_mode string yes Battery Health Check How the dealer is billed.
parent_company_id integer yes Battery Health Check Head office, where this dealer is a branch.
company_number string yes Dealer supplied Companies House or CRO registration number.
vat_number string yes Dealer supplied VAT registration number.
primary_contact object yes Dealer supplied Primary contact for the account.
registered_address object yes Dealer supplied Registered address.
shipping_address object yes Dealer supplied Default shipping address.
units array yes Battery Health Check AVILOO units held by this dealer.
activated_at string yes Battery Health Check When the account was activated.
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.

Unit

An AVILOO test unit held by a dealer. Nested within Dealer.

Field Type Unit Null Source Values Description
id integer no Battery Health Check BHC identifier for the unit.
internal_reference string yes Dealer supplied Partner-defined identifier for the unit. Returned unchanged.
status string yes Battery Health Check ordered, shipped, active, returned, retired, null Lifecycle state of the unit.
serial_number string yes AVILOO result AVILOO device serial number. Results are attributed to a dealer by this value.
location_label string yes Dealer supplied Free-text label for where the unit is kept.
shipping_address object yes Dealer supplied Where the unit was sent.
dispatched_at string yes Battery Health Check When the unit was dispatched.
delivered_at string yes Battery Health Check When the unit was delivered.
activated_at string yes Battery Health Check When the unit was first activated.

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.

Connection

A dealer that has connected a platform credential. Returned by GET /connections, which only platform credentials can call.

Field Type Unit Null Source Values Description
dealer_id integer no Battery Health Check BHC identifier for the dealer that connected you. For a group, its head office.
name string yes Dealer supplied Trading name of that dealer.
sites array yes Battery Health Check Every site this connection covers: the dealer itself first, then each of its branches. Branches added later appear here and are covered automatically.
connected_at string no Battery Health Check When the dealer connected you.
platform_reference string yes Dealer supplied Your own identifier for this dealer, exactly as your Connect link carried it in ref. Null when the dealer connected without one.

Connection.sites

One site a connection covers: the connected dealer itself, or one of its branches.

Field Type Unit Null Source Values Description
dealer_id integer no Battery Health Check BHC identifier for the site. The same value as dealer_id on its tests and in webhook payloads.
name string yes Dealer supplied Trading name of the site.
city string yes Dealer supplied Town of the site's operational address, or of its registered address where no operational address is held.
postcode string yes Dealer supplied Postcode from the same address as city.

Passport

GET /v1/tests/{id}/passport. For your own systems: it contains the VIN, so never publish it as it stands. Only publish is written for public display.

Field Type Unit Null Source Values Description
object string no Battery Health Check passport Always passport.
version string no Battery Health Check passport-v1 The passport format. A breaking change would ship as a new value on a new version path.
test object no Battery Health Check The test, exactly as GET /v1/tests/{id} returns it, including the VIN and the dealer.
aviloo object no AVILOO diagnostics What AVILOO's detail record holds that the test object does not: start and completion times, the model group and the execution protocol.
outcome object no Battery Health Check Battery Health Check's reading of what happened on the test.
odometer object yes AVILOO result The odometer at the test in both units. Null when no reading is held.
history object no Battery Health Check The other tests of this vehicle that you can read.
vehicle_record object no DVLA / DVSA record The registered vehicle details held for this VIN, from the DVLA register (via the DVSA MOT history service) or, for an Irish vehicle, the Irish register. Never looked up for this call. Always an object; read status first.
mot object no DVLA / DVSA record The DVSA MOT history of this vehicle: DVSA's own, synced nightly for every car Battery Health Check has tested, or, where none is held for its registration, the copy held with the vehicle record. Never looked up for this call. Always an object; read status first.
verified array no Battery Health Check The checks that were actually made, each naming what it relied on. None is a statement of approval.
publish object no Battery Health Check Battery Health Check's publish decision for this test, exactly as GET /v1/tests/{id}/publish returns it. It is the only part of the passport written for public display.
warnings array no Battery Health Check Notes about the passport as a whole. Empty for a live response.
links object no Battery Health Check Where the vehicle's public passport page and its QR code will be. Both URLs are null until that page is public.

Passport: AVILOO record

Field Type Unit Null Source Values Description
test_started_at string yes AVILOO diagnostics When the test started, from AVILOO's detail record.
test_completed_at string yes AVILOO diagnostics When the test completed, from AVILOO's detail record.
manufacturer string yes AVILOO diagnostics Manufacturer as AVILOO identified it.
model_group object no AVILOO diagnostics The model group AVILOO tested the vehicle as, from AVILOO's records of the test. Always an object; a field AVILOO did not send is null, as all three are on most tests that did not complete.
protocol array yes AVILOO diagnostics AVILOO's execution protocol for the test, in AVILOO's order: each step with its time. Entries about the emails AVILOO sends us are left out; they describe our account, not the vehicle. Null when no detail record is stored; an empty array when the record holds no steps.
error_reason string yes AVILOO result AVILOO's reason code when the test did not complete. Null for a completed test.
result_type string yes AVILOO result AVILOO's overall result type for the test, for example OK or NOT_CONCLUSIVE. Null on older tests that did not record it.
data_acquisition_ended_at string yes AVILOO result When the box stopped reading data from the vehicle, from AVILOO's record of the test: after test_started_at and before AVILOO evaluated the data (test_completed_at). Null when AVILOO did not send it.

Passport: protocol step

Field Type Unit Null Source Values Description
at string yes AVILOO diagnostics When AVILOO logged the event.
event string no AVILOO diagnostics AVILOO's event type, passed through, for example BOOT, START, VMD_HINT, DATA_ACQUISITION, DONE, INVOKING_FASTCHECK_ANALYZER or FASTCHECK_ANALYZER_RESULT. Treat an unrecognised value as informational.

Passport: outcome

Field Type Unit Null Source Values Description
kind string no Battery Health Check certified, certified_with_finding, no_result, didnt_complete, in_progress, stalled What happened on the test, in one word. certified: a battery health figure. certified_with_finding: a figure, plus an AVILOO warning about the vehicle. no_result: the test finished without a figure. didnt_complete: the test stopped. in_progress and stalled: no result yet, recently or for longer than expected.
label string no Battery Health Check A short label for the outcome, for your own screens.
cause string yes AVILOO result The AVILOO code behind the outcome: the reason a test did not complete, or the warning behind a finding or a missing figure. Null when there is nothing to explain.
retry string yes Battery Health Check yes, once, wait, no, null Whether to test again. yes: test again following the usual routine. once: one more try. wait: not yet. no: Battery Health Check follows up. Null when no retry applies.

Passport: odometer

Field Type Unit Null Source Values Description
value number as given in `unit` yes AVILOO result The reading AVILOO sent, in unit. Null on older tests recorded before the unit was stored.
unit string yes AVILOO result km, mi, null The unit value is in: km for almost every model, mi for the few that report miles themselves.
km number km yes AVILOO result The reading in kilometres.
miles number miles yes Battery Health Check The reading in miles: km converted, rounded to a whole mile: the same figure as the test's vehicle.odometer.miles.
read_in_vehicle boolean no AVILOO result True when AVILOO read the odometer from the vehicle's own systems during the test, rather than anyone typing it in.
legacy_mileage_km_field number miles yes AVILOO result The value of the test's vehicle.mileage_km, echoed so the two can be reconciled. Despite that field's name it carries miles. Use km or miles instead.

Passport: history

Field Type Unit Null Source Values Description
scope string no Battery Health Check within_your_access Always within_your_access: the history covers only the tests your credential can read. For a platform credential, only the tests of the dealer that connected you for this test (with its branches): a test of the same vehicle at another dealer is never listed, even when that dealer has connected you too.
count integer no Battery Health Check How many tests of this vehicle are in that history. Can exceed the length of tests, which is capped at 50. 1 when the test has no VIN.
current_test_id integer yes Battery Health Check The test that speaks for the vehicle (see tests[].current).
tests array no Battery Health Check The tests of this vehicle, oldest first, matched by exact VIN: the newest 50, always including this test.

Passport: history test

Field Type Unit Null Source Values Description
id integer no Battery Health Check BHC identifier for the test.
tested_at string yes AVILOO result When the test was performed.
status string yes Battery Health Check pending, in_progress, completed, failed, cancelled, null Lifecycle state of the test record.
result_status string yes Battery Health Check final, provisional, inconclusive, null How that test's State of Health should be treated, exactly as result_status on a test.
soh_percent number percent yes AVILOO result State of Health from that test. Read it with result_status.
odometer_km number km yes AVILOO result The odometer at that test, in kilometres.
dealer object yes Battery Health Check The dealer that ran that test.
current boolean no Battery Health Check True for the test that speaks for the vehicle: the newest completed test with a figure, or the newest test when no completed test has one. The same test as current_test_id.

Passport: vehicle record

Never for a public page.

Field Type Unit Null Source Values Description
source string yes DVLA / DVSA record Where the record came from, in words. Null unless status is found.
status string no Battery Health Check found, not_found, not_offered found: a record is held for this VIN. not_found: none is held (Battery Health Check never looks one up for this call). not_offered: the record is not being supplied; every other field is then null.
registration string yes DVLA / DVSA record The registration the record holds for this VIN.
make string yes DVLA / DVSA record Make, as registered.
model string yes DVLA / DVSA record Model, as registered.
colour string yes DVLA / DVSA record Colour, as registered.
fuel string yes DVLA / DVSA record Fuel type, as registered.
first_registered string yes DVLA / DVSA record Date of first registration (or first use).
retrieved_at string yes Battery Health Check When Battery Health Check retrieved the record.
public_display boolean no Battery Health Check Always false: this data is for your own systems and must not be shown on a public page.

Passport: MOT history

Never for a public page.

Field Type Unit Null Source Values Description
source string yes DVLA / DVSA record Where the MOT history came from, in words. Null unless status is found.
status string no Battery Health Check found, not_found, not_offered found: an MOT history is held for this VIN. not_found: none is held (including for an Irish record, and for a vehicle too new for an MOT). not_offered: the MOT history is not being supplied; every other field is then null.
retrieved_at string yes Battery Health Check When Battery Health Check retrieved the record.
due string yes DVLA / DVSA record When the next MOT is due: for DVSA's MOT history, the expiry of the newest passed test.
first_used string yes DVLA / DVSA record Date of first use.
tests array yes DVLA / DVSA record MOT tests, oldest first. Null unless status is found.
public_display boolean no Battery Health Check Always false: this data is for your own systems and must not be shown on a public page.
attribution string yes Battery Health Check The attribution to show beside the MOT history: for DVSA's MOT history, the Open Government Licence v3.0 statement. Null unless status is found.
as_at string yes DVLA / DVSA record When the provider generated the MOT history it returned (for DVSA's, when its data was loaded or looked up). Null when the record does not say.

Passport: MOT test

Field Type Unit Null Source Values Description
date string yes DVLA / DVSA record Date of the MOT test.
result string no DVLA / DVSA record passed, failed Outcome of the MOT test.
retest boolean no DVLA / DVSA record True for a retest. DVSA's MOT history carries no retest flag, so a test from it reads false.
odometer integer as given in `odometer_unit` yes DVLA / DVSA record Odometer recorded by the MOT tester, in odometer_unit.
odometer_unit string yes DVLA / DVSA record Unit of odometer, as recorded (mi or km). Null when the record does not give one: it is never assumed.
expiry string yes DVLA / DVSA record MOT expiry date, for a pass.
advisories array no DVLA / DVSA record The texts of the ADVISORY items, as recorded.
failures array no DVLA / DVSA record The texts of the items that failed the test: MAJOR, DANGEROUS and FAIL only. MINOR and PRS (put right at the test station) items do not fail a test; they are in defects only.
dangerous boolean no DVLA / DVSA record True when any defect was marked dangerous.
defects array no DVLA / DVSA record Every defect note on the test, advisories included, in record order: text, type (as recorded: ADVISORY, MINOR, PRS, MAJOR, DANGEROUS or FAIL) and dangerous (the record's own flag, null when it gives none).
odometer_result_type string yes DVLA / DVSA record How the odometer was recorded, as given, for example READ, UNREADABLE or NO_ODOMETER. Null when the record does not say. Treat a value you have not seen as unknown.
mot_test_number string yes DVLA / DVSA record The MOT test number. Null when the record does not hold one.
completed_at string yes DVLA / DVSA record When the test was completed, with its time (UTC). Null when the record holds only the date.
data_source string yes DVLA / DVSA record The record's own data source, as given, for example DVSA. Null when the record does not say, as the copies held with the vehicle record do not.
provider string no Battery Health Check The key of the provider the record came from, as GET /v1/providers lists it.
retrieved_at string yes Battery Health Check When Battery Health Check retrieved the record: for DVSA, when the nightly sync last wrote it.

Passport: check

Field Type Unit Null Source Values Description
key string no Battery Health Check vin_read_in_vehicle, odometer_read_in_vehicle, registration_matches_vin, mileage_consistency, battery_checks Which check. One entry each, in this order: vin_read_in_vehicle (the VIN AVILOO read from the vehicle is this test's VIN), odometer_read_in_vehicle (the odometer was read from the vehicle), registration_matches_vin (the test's registration is the one the UK register holds for the VIN), mileage_consistency (the odometer at the test against the last MOT reading before it) and battery_checks (AVILOO's battery checks).
result string no Battery Health Check verified, consistent, discrepancy, all_ok, not_all_ok, not_checked, not_offered What the check found. verified, consistent and all_ok are positive; discrepancy and not_all_ok say the sources disagree or a check was not OK, and draw no further conclusion; not_checked: the check could not be made from what is held; not_offered: the data it needs is not being supplied.
source string yes Battery Health Check Who or what the check relied on, in words. Null when the check was not made.
as_of string yes Battery Health Check The date the check speaks for: the test date (London) for the checks made at the test, the retrieval date for the registration. Null when the check was not made.
detail object yes Battery Health Check Present on mileage_consistency and battery_checks only; null when the check was not made. For mileage_consistency: test_miles, mot_miles, mot_date, difference_miles (test minus MOT) and days between them. For battery_checks: reported (checks AVILOO reported) and ok (how many were OK).

StockCheckResult

One car’s result from POST /stock/check, in the order the cars were sent. Its query and error objects are the same as on a lookup result.

Field Type Unit Null Source Values Description
object string no Battery Health Check stock_check_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.
tested boolean yes Battery Health Check Whether this dealer holds any test of the vehicle. Null with an error.
state string yes Battery Health Check certified, tried_not_certified, in_flight, stalled, untested, null Where the car stands. certified: a test gave a battery figure. tried_not_certified: tests ran, none gave one. in_flight: the newest test is running. stalled: the newest test stopped reporting. untested: no test. Null when a registration matched several vehicles, or with an error.
latest_test_id integer yes Battery Health Check The vehicle's newest test, or null.
certified_test_id integer yes Battery Health Check The vehicle's newest certified test, or null.
certificate object yes Battery Health Check The certified test in brief, or null when there is none.
support object yes Battery Health Check Whether the model can be tested, from the published supported-vehicle list, using the make, model, year and fuel you sent (else the test's). Null when there was no make to assess.
test_recommended boolean no Battery Health Check True exactly when next_step is test_this_car, retest or retest_once.
next_step string yes Battery Health Check test_this_car, retest, retest_once, confirm_support, wait, check_box, contact_us, resubmit_with_vin, none, null The one thing to do next for this car. Null with an error.
reason string yes Battery Health Check NOT_ELECTRIFIED, REGISTRATION_MATCHES_SEVERAL_VEHICLES, CERTIFIED_CURRENT, CERTIFIED_STALE, CERTIFIED_PROVISIONAL, CERTIFIED_CERTIFICATE_ONLY, CERTIFIED_SAFETY_FINDING, CERTIFIED_WITH_FINDING, CERTIFIED_NOT_PUBLISHABLE, TEST_IN_PROGRESS, TEST_STALLED, LAST_TEST_UNSUCCESSFUL, NO_TEST, CHECK_SUPPORT_FIRST, null Why: a stable code. Null with an error. Treat an unrecognised code as contact_us.
error object yes Battery Health Check Why this vehicle could not be checked, or null.
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.

StockCheckResult.certificate

The newest certified test of the car, in brief.

Field Type Unit Null Source Values Description
tested_on string yes Battery Health Check The London date of the certified test.
result_status string yes Battery Health Check final, provisional, inconclusive, null The certified test's result_status.
band string yes Battery Health Check outstanding, excellent, good, fair, poor, null AVILOO's grade for the result, as on its certificate (the publish decision's band.code); null while not known.
publishable boolean no Battery Health Check Whether the certified result may be shown on an advert now (the publish decision).
valid_until string yes Battery Health Check Until when the result may be shown, while it is publishable.

StockCheckResult.support

Whether the model can be tested, from the published supported-vehicle list.

Field Type Unit Null Source Values Description
verdict string no Battery Health Check covered, confirm covered: the model is on the supported-vehicle list, so a test can go ahead. confirm: we'll confirm the vehicle is supported before it is tested. Never a refusal.
as_of string yes Battery Health Check The date of the supported-vehicle list the verdict was read from.

StockCheckSummary

meta.summary on a POST /stock/check response.

Field Type Unit Null Source Values Description
vehicles integer no Battery Health Check Vehicles in the request.
certified_current integer no Battery Health Check Cars whose certified result may be shown now.
untested integer no Battery Health Check Cars with no test.
recommended integer no Battery Health Check Cars for which a battery test is recommended (test_recommended).
confirm_support integer no Battery Health Check Cars whose model we will confirm before testing.
contact_us integer no Battery Health Check Cars where a person should look.

Provider

One entry of GET /providers.

Field Type Unit Null Source Values Description
object string no Battery Health Check provider Always present, so a stream of items can be told apart. Always provider.
key string no Battery Health Check The provider's key: what ?provider= takes on the vehicle routes. Unique within its category, not across categories: one provider can appear in two categories.
name string no Battery Health Check The provider's name, in plain text.
category string no Battery Health Check battery, history, valuation_base, valuation_method What the provider supplies: battery (battery-health readings) or history (vehicle history checks). valuation_base and valuation_method belong to a Battery Health Check feature in preview.
status string no Battery Health Check live, preview, subject_to_agreement live: answered in production today. preview: a Battery Health Check feature shown in the sandbox, with production use subject to confirmation. subject_to_agreement: described here, but nothing from it is served in production; available subject to agreement with the provider.
stage string no Battery Health Check live, beta, planned The maturity label to show beside the name: live (answers in production today), beta (a Battery Health Check feature in preview) or planned (subject to agreement with the provider). Follows status, which is unchanged.
note string no Battery Health Check The status in one plain sentence, ready to show beside the name.
products array no Battery Health Check The provider's products this API presents, each {key, name}. Empty when it has none.
method object yes Battery Health Check The battery provider only: how it arrives at its figure. key is the method, label says it in plain words and category is the kind of method: for AVILOO, independent_model (its own calculation). Treat a value you have not seen as unknown. Null for any other category.
measurement_basis string yes Battery Health Check The battery provider only: what the figure is measured against. For AVILOO, declared_nominal (the capacity declared for the car when new). Treat a value you have not seen as unknown.
headline_kind string yes Battery Health Check The battery provider only: the kind of headline it gives. For AVILOO, percent. Treat a value you have not seen as unknown.
sections array yes Battery Health Check identity, finance, write_off, stolen_police, keepers, plate_changes, mileage_readings, mileage_anomaly, mot_tests, recalls, previous_use, status, null History providers only: the vehicle-history sections this provider can answer. New sections may be added (previous_use and status were, on 7 October 2026): ignore a section you do not recognise.
jurisdictions array yes Battery Health Check History providers only: the registers it covers, GB or IE.
returns string no Battery Health Check What the provider's own service returns, in one plain sentence.

BatteryReadings

The data object of GET /vehicles/battery-readings: one vehicle, every reading of it, and every battery provider with its status.

Field Type Unit Null Source Values Description
object string no Battery Health Check battery_readings Always present, so a stream of items can be told apart. Always battery_readings.
query object no Dealer supplied What you asked for: vin (upper-cased) or registration (spaces and hyphens removed), provider and dealer_id, each null when not sent.
matched_on string yes Battery Health Check vin, registration, null Which key found the vehicle. Null when found is false.
found boolean no Battery Health Check Whether any test of the vehicle is within your reach, finished or not. A vehicle can be found with no readings: a test that has not completed is not a reading.
distinct_vins integer no Battery Health Check How many different VINs the matched tests carry.
ambiguous boolean no Battery Health Check True when a registration matched tests of more than one VIN (plates transfer between cars). Ask again by VIN.
vehicle object yes Battery Health Check The vehicle, from the newest matched test. Null when found is false.
readings array no Battery Health Check Every reading, newest first: one per completed AVILOO test within your reach.
providers array no Battery Health Check The battery provider, AVILOO, with its status and how many readings it returned.
warnings array no Battery Health Check SANDBOX_DATA on a sandbox response, else empty.

BatteryReadings.providers[]

One entry of providers on a battery readings response.

Field Type Unit Null Source Values Description
key string no Battery Health Check The battery provider's key, as GET /v1/providers lists it: aviloo.
name string no Battery Health Check Its name, in plain text.
status string no Battery Health Check live, preview, subject_to_agreement live: answered in production today. preview: a Battery Health Check feature shown in the sandbox, with production use subject to confirmation. subject_to_agreement: described here, but nothing from it is served in production; available subject to agreement with the provider.
note string no Battery Health Check The status in one plain sentence.
readings_returned integer no Battery Health Check How many readings in this response come from this provider.

BatteryReading

One measurement of one car’s battery by one provider on one occasion, in that provider’s own method, scale and wording. Only readings with the same comparability_key are on one scale.

Field Type Unit Null Source Values Description
object string no Battery Health Check battery_reading Always present, so a stream of items can be told apart. Always battery_reading.
reading_id string no Battery Health Check Identifies this reading. For an AVILOO reading, aviloo- followed by the test id.
provider object no Battery Health Check Who measured it: {key, name}.
product object yes Battery Health Check The provider's product: {key, name}.
method object no Battery Health Check How the provider arrives at its figure: {key, label, category}, as GET /v1/providers lists it.
measurement_basis string no Battery Health Check What the figure is measured against, as GET /v1/providers lists it. Treat a value you have not seen as unknown.
comparability_key string no Battery Health Check provider:method: for AVILOO, aviloo:aviloo_flash. Only readings with equal keys are on the same scale. Never compare, average, band, rank or chart together readings whose keys differ.
tested_at string yes Provider When the provider tested the car.
tested_at_precision string yes Battery Health Check utc, null utc: tested_at is an instant in UTC. Null when tested_at is null.
test_id integer yes Battery Health Check The Battery Health Check test id: the GET /v1/tests/{id} object the reading was built from.
vin string yes Provider The VIN as the provider recorded it. Null when its record carries none.
vin_source string yes Battery Health Check read_in_vehicle, provider_record, unknown, null How the VIN was obtained: read_in_vehicle (read from the car during the test), provider_record (as the provider's record holds it) or unknown. Null when vin is null.
vrm string yes Provider The registration the provider recorded with the reading. Null for AVILOO, whose test records none: the response's vehicle.registration carries the one we hold.
odometer object yes Provider The odometer reading the provider gives: raw_value in raw_unit (km, mi or null when the unit is not known), unit_stated_by_provider (false when the provider states no unit and the unit is ours), km (the same reading in kilometres, null when the unit is not known) and read_method: vehicle_read, unknown, or request_echo (the provider echoed back a mileage it was sent, which is not a reading). Null when there is none.
status string yes Battery Health Check final, provisional, inconclusive, null The test's result_status, exactly.
vehicle_supported boolean yes Provider The test's vehicle_supported, exactly.
headline object no Provider The headline result: kind (percent for a percentage, grade for a value on a named scale, or none when the reading carries no figure), value (a number for percent, a string for grade, null for none) and native_label (the provider's own name for it). For AVILOO, kind is percent and value is the test's battery.soh_percent, or kind is none when the test gave no figure.
native_grade object yes Provider A grade on the provider's own scale, unchanged: value, scale_id and scale_definition (the scale's bands, each {label, from, to}, where the scale is published; otherwise null). Always null for AVILOO: AVILOO prints its own grade on the certificate rather than returning it as data; the publish decision's band gives it, read off the certificate.
native_status object yes Provider The provider's own overall status and the vocabulary it comes from: for AVILOO, its overall battery status (OK, WARNING, NOT_CONCLUSIVE, SAFETY_ISSUE) with vocabulary aviloo_overall_battery_status. Null when none.
checks array yes Provider The provider's own checks, each {native_key, native_label, native_status} in its own terms: for AVILOO, its five battery checks. Null when none were captured; an empty array when the provider reported none.
provider_warnings array yes Provider The provider's own warning codes: for AVILOO, exactly the test's warnings. Null when none were captured.
energy_kwh array kWh no Provider Energy figures, each {quantity, when, value, basis}. Empty when there are none.
range array no Provider Range figures, each {kind, from, to, unit, basis} in the provider's own kinds. Each states its unit. Empty when there are none. For AVILOO, the typical and personal entries are left out where the test's range is withheld (see the test's diagnostics.range); the WLTP entries remain.
warranty_indicative object yes Provider A battery warranty position as the provider states it, indicative only: in_warranty, remaining_months, remaining_miles and the provider's own caveat_text. It is not a warranty Battery Health Check gives. Always null for AVILOO, whose warranty is warranty_product.
warranty_product object yes Battery Health Check A warranty the provider issued on this test, as the warranty block: its state, dates and limits as the provider sent them, and a link to the provider's own conditions. Null when no warranty state is on record.
documents array no Battery Health Check The reading's documents, each {kind, path, url, content_type, public_display, available}. An AVILOO reading lists the certificate PDF (public_display false: it shows the VIN) and its anonymised version (certificate_pdf_anonymised, public_display true: the VIN is hidden) where the test has one; where a warranty document is held, the full warranty PDF (warranty_pdf, public_display false: it shows the VIN), the anonymised one (warranty_pdf_anonymised, public_display true: the VIN is hidden) and the anonymised warranty preview image (warranty_image_anonymised, public_display true), all with scope read:warranties; and the preview image (listing_image), whose public_display is the publish decision's image.publishable. Each kind appears at most once. Empty when there are none. The full kinds (certificate_pdf, warranty_pdf) are listed to a dealer credential only: a platform or sandbox credential receives the anonymised copies only, so its reading leaves them out. 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.
attribution_text string no Battery Health Check Who carried out the test, in plain words. Show it with the reading.
display_conditions array no Battery Health Check Conditions for showing the reading, as plain sentences. Every reading says to show it with its provider, method and date, and to compare it only with readings that share its comparability_key.
availability string no Battery Health Check live, sandbox_illustrative live: built from a test, as production serves it (in the sandbox, from a fixture test). Every reading is live; sandbox_illustrative (an invented sandbox reading) is not sent.
warnings array no Battery Health Check Notes about this reading, as stable codes: SANDBOX_DATA on every sandbox reading. Ignore codes you do not recognise.

VehicleHistory

The data object of GET /vehicles/history: one vehicle, a check from each provider that answered, and every history provider with its status.

Field Type Unit Null Source Values Description
found boolean no Battery Health Check Whether any test of the vehicle is within your reach. When false, no provider is consulted.
matched_on string yes Battery Health Check vin, registration, null Which key found the vehicle. Null when found is false.
ambiguous boolean no Battery Health Check True when a registration matched tests of more than one VIN. The answer is for the newest matched test's car: ask again by VIN.
vehicle object yes Battery Health Check The vehicle, from the newest matched test. Null when found is false.
checks array no Battery Health Check One check per provider that answered. Each stands alone: never merge two providers' answers into one verdict.
providers array no Battery Health Check Every history provider, or the one named in ?provider=, with its status and why it returned no check.
warnings array no Battery Health Check SANDBOX_DATA on a sandbox response, else empty.

VehicleHistory.providers[]

One entry of providers on a vehicle history response.

Field Type Unit Null Source Values Description
key string no Battery Health Check The history provider's key, as GET /v1/providers lists it.
name string no Battery Health Check Its name, in plain text.
status string no Battery Health Check live, preview, subject_to_agreement live: answered in production today. preview: a Battery Health Check feature shown in the sandbox, with production use subject to confirmation. subject_to_agreement: described here, but nothing from it is served in production; available subject to agreement with the provider.
note string no Battery Health Check The status in one plain sentence.
checks_returned integer no Battery Health Check How many checks in this response come from this provider.
served boolean no Battery Health Check Whether the provider was consulted for this car.
reason string yes Battery Health Check subject_to_agreement, not_offered, vehicle_not_found, no_record, null Why no check came back, or null when one did. subject_to_agreement: not served in production. not_offered: Battery Health Check is not supplying it at present. vehicle_not_found: no test of the car is within your reach. no_record: consulted, and it holds nothing for this car.

VehicleHistoryCheck

One provider’s answer about one car. It always carries all twelve sections.

Field Type Unit Null Source Values Description
check_id string yes Battery Health Check Identifies this check. Stable for the same record; reveals nothing about the VIN.
provider object no Battery Health Check Who answered: {key, name, status}.
product object no Battery Health Check The provider's product: {key, name}.
jurisdiction string yes Provider GB, IE, null The register the check speaks for.
matched_on string yes Provider vin, registration, null Which key the provider matched the car on.
requested_at string yes Battery Health Check When the provider was asked. For a live check, when the data was retrieved: the vehicle record for the vehicle record provider (vdg), the nightly sync of the MOT history for DVSA.
provider_reference string yes Provider The provider's own reference for its answer. Null when it gives none.
sections object no Battery Health Check All twelve sections, always: identity, finance, write_off, stolen_police, keepers, plate_changes, mileage_readings, mileage_anomaly, mot_tests, recalls, previous_use and status, each a VehicleHistorySection.
attribution_text string yes Battery Health Check Where the data comes from, in plain words. Show it with the data.
availability string no Battery Health Check live, sandbox_illustrative live: built from data Battery Health Check holds. sandbox_illustrative: a sandbox check.
warnings array no Battery Health Check SANDBOX_DATA on every sandbox check, else empty.

VehicleHistorySection

One section of a check. Read status first: only none_found may be shown as “none recorded”.

Field Type Unit Null Source Values Description
status string no Battery Health Check found, none_found, not_checked, not_licensed, not_available, not_applicable, unknown, pending found: records are below. none_found: the provider was asked and holds none, the only state that may be shown as "none recorded". not_checked: this check does not cover the section. not_licensed: not part of what the provider supplies. not_available: the data does not exist for this car or register. not_applicable: the section does not apply (an Irish car has no MOT). unknown: the answer could not be read as one of the others. pending: the provider has started and not finished.
fact_kind string no Battery Health Check durable_event, live_status durable_event: a record that keeps its truth over time (a write-off, a keeper change, a previous use, an export marker). live_status: true only at checked_at (outstanding finance, a stolen marker).
checked_at string yes Provider When the provider answered. Null when it was not asked (not_checked, not_available, not_applicable).
upstream object no Provider Where the provider says the fact comes from: source, for example dvla or dvsa, and as_at, the date that source speaks for where the provider gives one. Both null when the provider was not asked.
records array no Provider The records, when status is found; otherwise empty. The fields depend on the section (see VehicleHistoryRecord). A finance record never carries an agreement number or a lender's telephone number.
native object yes Provider The provider's own answer for the section, in its own field names, with agreement numbers, telephone numbers, other searchers' details, guarantees and scores removed. A mileage anomaly is the provider's own flag, carried here, never Battery Health Check's judgement. Null when none.

VehicleHistoryRecord

The fields of one record in a section’s records, as section.field. Every record of a section carries every field of that section, null when the provider does not give it. mileage_anomaly has no records: the provider’s flag is in its native. previous_use and status are durable events: how the car was used before, and its import, export and scrapped markers.

Field Type Unit Null Source Values Description
identity.registration string yes Provider The registration.
identity.make string yes Provider Make.
identity.model string yes Provider Model.
identity.colour string yes Provider Colour.
identity.fuel string yes Provider Fuel, as the register gives it.
identity.body string yes Provider Body type.
identity.year integer yes Provider Year of manufacture.
identity.first_registered string yes Provider First registration.
identity.first_registered_uk string yes Provider First registration in the UK.
identity.first_registered_ie string yes Provider First registration in Ireland.
finance.agreement_type string yes Provider The kind of agreement, in the provider's words.
finance.start_date string yes Provider When it started.
finance.term_months integer months yes Provider Its term.
finance.lender_name string yes Provider The lender.
write_off.recorded_at string yes Provider When it was recorded.
write_off.loss_date string yes Provider Date of the loss.
write_off.cause string yes Provider The cause, for example damage.
write_off.category string yes Provider The category, for example S. Null when the provider gives none.
write_off.category_scheme string yes Provider Which category scheme, for example uk_abi_2017.
write_off.category_source string yes Battery Health Check Where the category came from: field (a field of its own) or none. Treat a value you have not seen as unknown.
write_off.removed_at string yes Provider When the marker was removed, if it was.
stolen_police.reported_at string yes Provider When reported.
stolen_police.status_text string yes Provider The status, in the provider's words.
stolen_police.force string yes Provider The police force.
keepers.count integer yes Provider How many.
keepers.counting_basis string yes Battery Health Check What was counted: uk_registered_keepers, or ie_owners_incl_garages (Irish owners, garages included). Counts on different bases do not compare. Treat a value you have not seen as unknown.
keepers.change_dates array yes Provider Dates of keeper changes.
plate_changes.previous_vrm string yes Provider The earlier registration.
plate_changes.date string yes Provider When it changed.
plate_changes.transfer_type string yes Provider The kind of change, in the provider's words.
mileage_readings.date string yes Provider Date of the reading.
mileage_readings.value integer yes Provider The reading.
mileage_readings.unit string yes Provider mi, km, null Its unit.
mileage_readings.source string yes Provider Where the reading came from, for example MOT.
mileage_readings.subsource string yes Provider A finer source, where given.
mileage_readings.in_sequence boolean yes Provider The provider's own view of whether the reading follows the ones before it.
mot_tests.date string yes Provider Date of the test.
mot_tests.result string yes Provider passed, failed, null The result.
mot_tests.retest boolean yes Provider Whether it was a retest. Null when the record does not say: DVSA's MOT history carries no retest flag.
mot_tests.expiry string yes Provider Expiry of the certificate.
mot_tests.odometer object yes Provider The odometer as recorded: value, unit (mi or km; null when the record does not give one, never assumed) and result_type (for example READ, UNREADABLE or NO_ODOMETER).
mot_tests.defects array no Provider Every defect on the test, advisories included, in record order: text, type (ADVISORY, MINOR, PRS, MAJOR, DANGEROUS or FAIL) and dangerous (the record's own flag, null when it gives none). Only MAJOR, DANGEROUS and FAIL items fail a test.
mot_tests.mot_test_number string yes Provider The MOT test number. Null when the record does not hold one.
mot_tests.completed_at string yes Provider When the test was completed, with its time (UTC). Null when the record holds only the date.
mot_tests.data_source string yes Provider The record's own data source, as given, for example DVSA. Null when the record does not say, as the copies held with the vehicle record do not.
mot_tests.provider string yes Battery Health Check The key of the provider the record came from, as GET /v1/providers lists it.
mot_tests.retrieved_at string yes Battery Health Check When the record was retrieved: for DVSA, when the nightly sync last wrote it.
recalls.outstanding boolean yes Provider Whether the recall is outstanding.
recalls.description string yes Provider What the recall is.
recalls.date string yes Provider Its date.
previous_use.use_type string yes Provider taxi, private_hire, police, hire, fleet, driving_school, emergency_services, other, null How the car was used: taxi, private_hire, police, hire (rental), fleet, driving_school, emergency_services, or other for a use with no entry of its own. The provider's own term is in native. Null when the provider names no use.
previous_use.from_date string yes Provider When that use began.
previous_use.to_date string yes Provider When it ended. Null when the provider gives no end.
previous_use.source string yes Provider Where the provider says the use is recorded, in its own words.
status.status_type string yes Provider scrapped, exported, imported, null The marker: scrapped, exported or imported. Null only when a provider names a marker that is none of these, its own term then in native; never any other value. A record from the vehicle record provider (vdg) always has one.
status.date string yes Provider When the car was scrapped, exported or imported. Null when the record gives no date.
status.country string yes Provider The country the car was exported to or imported from, as an ISO 3166 alpha-2 code: two capital letters, for example IE. Null when it is not known: the DVLA markers name no country, and a provider that gives a marker as a flag alone gives none.
status.source string yes Provider Where the marker comes from. For the vehicle record provider (vdg), the vehicle record it is held in, in the words of the test passport's vehicle_record.source; for other providers, the register in their own words, for example DVLA.

Valuation (Beta)

The data object of GET /v1/valuations and GET /v1/tests/{id}/valuation. Beta: figures in the sandbox now; production figures follow. Never for public display.

Field Type Unit Null Source Values Description
object string no Battery Health Check valuation Always valuation.
mode string no Battery Health Check contract, live The production mode that produced the answer. contract today: no figure is served in production. The sandbox reports the production mode too, so read illustrative.
status string no Battery Health Check available, refer, not_available The pounds-per-kWh battery adjustment (battery_adjustment): available, refer or not_available. Read adjustment.status and value_grid.status for those blocks.
reason string yes Battery Health Check Why, for refer and not_available; NO_BASE or null for available. In production today VALUATIONS_NOT_LIVE (or, for a registration that matches several vehicles, REGISTRATION_MATCHES_SEVERAL_VEHICLES). CURRENCY_NOT_SUPPORTED on a euro request, whose figures are in adjustment and value_grid.
reasons array no Battery Health Check Every reason that applied, the first being reason.
vehicle object yes Battery Health Check The car, as identified by its test or as you asked for it.
base object yes Dealer supplied Your own base value, echoed. Null when you sent none.
battery object yes AVILOO result The car's own battery facts from the test used. Null when no test is within your access.
battery_adjustment object yes Battery Health Check The pounds-per-kWh adjustment to a base (threshold-v1). Null for valuation=bhc_valuation.
values object yes Battery Health Check Your base plus the adjustment, or for valuation=bhc_valuation Battery Health Check's own value. Null without either.
if_tested object yes Battery Health Check Only for a car with no test within your access: fixed scenario readings. Null otherwise.
superseded_by integer yes Battery Health Check A newer test of this car that replaces the one used.
confidence object no Battery Health Check Reserved: level is null and reasons empty in this version.
method object no Battery Health Check The rule and parameter set used.
as_of string no Battery Health Check When the answer was made.
valid_until string no Battery Health Check Cache the answer until then at most: the earlier of seven days from as_of and 90 days from the test. A time before as_of means do not cache.
publishable boolean no Battery Health Check Always false: never for public display.
audience string no Battery Health Check trade Always trade.
statement string no Battery Health Check What the answer is, in one or two sentences. Not for public display.
warnings array no Battery Health Check SANDBOX_DATA on every sandbox answer; ILLUSTRATIVE_PARAMETERS when sandbox figures come from illustrative parameters.
valuation_method object yes Battery Health Check The method used, {key, name, status}, as GET /v1/providers lists it (category valuation_method). Present only on a request that sends valuation, base_provider, adjustment_mode or currency.
illustrative boolean yes Battery Health Check True on a sandbox answer, whose figures are invented. Read this, not mode, to tell an illustration from a production answer. Present on the same requests as valuation_method.
adjustment object yes Battery Health Check The valuation adjuster: how far the measured battery moves a value, as a percentage or an amount, for you to apply to your own valuation. Present only on a request that sends adjustment_mode or currency, and on every valuation=bhc_valuation request (in percent mode and GBP unless either is sent).
value_grid object yes Battery Health Check Battery Health Check's own value for the car: four value types by three conditions, each before and after the battery. Present on the same requests as adjustment.

Valuation.adjustment

The valuation adjuster.

Field Type Unit Null Source Values Description
status string no Battery Health Check available, refer, not_tested, not_available available: the adjustment is below. refer: no figure; the battery must be looked at (see reason). not_tested: no test of the car is within your access. not_available: no figure (VALUATIONS_NOT_LIVE in production today; NO_REFERENCE, NO_VALUE or NO_PARAMETER when an input is missing).
reason string yes Battery Health Check The first of reasons. Null when status is available.
reasons array no Battery Health Check Every reason that applied. For a refer from the publish decision, its full list.
mode string no Dealer supplied percent, absolute Your adjustment_mode.
percent number percent yes Battery Health Check The adjustment as a percentage of value, to one decimal place: zero or negative, never below -15. Given in both modes once the reference is known; null before.
amount integer yes Battery Health Check Absolute mode: the adjustment in whole units of currency. Null in percent mode, and when there is no value to take it from (NO_VALUE).
currency string yes Dealer supplied GBP, EUR, null Absolute mode: your currency. Null in percent mode.
base_source string yes Battery Health Check caller, bhc_valuation, null Absolute mode: what amount was taken from. caller: your own base_amount. bhc_valuation: Battery Health Check's own value for the car before the battery. Null otherwise.
illustrative boolean no Battery Health Check True on a sandbox answer, whose figures are invented. Read this, not mode, to tell an illustration from a production answer.
reference object no Battery Health Check What the battery was measured against.
apply object no Battery Health Check How to apply the adjustment to your own valuation. operation: add_percent (add percent percent of your value) or add_amount (add amount), null when there is nothing to apply. max_reduction_percent: the most it ever takes off, 15.

Valuation.adjustment.reference

What the measured battery was compared with.

Field Type Unit Null Source Values Description
reference_type string no Battery Health Check expected_for_age_and_mileage What the measured state of health is compared with: expected_for_age_and_mileage.
rule string no Battery Health Check deviation-v1 Always deviation-v1.
parameters_version string yes Battery Health Check The parameter set the reference came from. Null when the rule did not run.
measured_soh_percent number percent yes AVILOO result The state of health measured at the test, floored to one decimal place.
expected_soh_percent number percent yes Battery Health Check The state of health expected for the car's age and mileage at the test.
deviation_points number points yes Battery Health Check measured_soh_percent minus expected_soh_percent. Negative means below the reference.
age_years number years yes Battery Health Check The car's age at the test, counted from 1 July of the year it was first registered (vehicle.year).
mileage_miles integer miles yes AVILOO result The odometer at the test.

Valuation.value_grid

The Battery Health Check valuation, as a grid.

Field Type Unit Null Source Values Description
status string no Battery Health Check available, refer, not_tested, not_available available, refer, not_tested or not_available, as adjustment.status.
reason string yes Battery Health Check Why there is no figure. Null when available.
condition_scheme string no Battery Health Check bhc-condition-v1 Battery Health Check's own condition scheme: bhc-condition-v1.
currency string no Dealer supplied GBP, EUR Your currency: GBP (the default) or EUR.
valuation_date string no Battery Health Check The date of the answer.
mileage_miles integer miles yes Battery Health Check The mileage the car is valued at.
vat_basis string yes Battery Health Check including_vat, excluding_vat, margin_scheme, null Whether the figures include VAT. Null without a figure.
battery_basis string no Battery Health Check measured, refer, not_tested What the grid knows about the battery: measured, refer or not_tested.
includes_battery_adjustment boolean no Battery Health Check True when every cell has the battery taken into account.
adjusted_by string yes Battery Health Check deviation-v1, null The rule that took the battery into account, deviation-v1. Null when no cell includes it.
range object yes Battery Health Check valuation A low and high either side of the retail, average cell: {type, condition, low, high}. Null without a figure.
sample_size integer yes Battery Health Check valuation How many comparable cars the value draws on. Null without a figure.
illustrative boolean no Battery Health Check True on a sandbox answer, whose figures are invented. Read this, not mode, to tell an illustration from a production answer.
cells array no Battery Health Check Twelve cells, always: every type (retail, trade, part_exchange, private) with every condition (clean, average, below_average), in that order.

Valuation.value_grid.cells[]

One cell of the grid.

Field Type Unit Null Source Values Description
type string no Battery Health Check retail, trade, part_exchange, private The value type.
condition string no Battery Health Check clean, average, below_average The condition, in bhc-condition-v1.
amount integer yes Battery Health Check valuation The value with the battery taken into account, in whole units of the grid's currency. Null unless the cell has a figure.
amount_before_battery integer yes Battery Health Check valuation The same value before the battery adjustment.
battery_adjustment integer yes Battery Health Check What the battery changed: amount minus amount_before_battery. Zero or negative.
includes_battery_adjustment boolean no Battery Health Check True when amount has the battery taken into account.
basis string yes Battery Health Check Where the figure comes from: illustrative in the sandbox. Null without a figure.
status string no Battery Health Check available, refer, not_tested, not_available As the grid's status.
reason string yes Battery Health Check As the grid's reason.

Valuation.vehicle

Field Type Unit Null Source Values Description
vin string yes AVILOO result The VIN: the tested car's, or the one you asked for. Never publish it.
registration string yes Dealer supplied The registration recorded against the test, or the one you asked for.
make string yes AVILOO result Make, from the test. Null for an untested car.
model string yes AVILOO result Model, from the test. Null for an untested car.
nominal_kwh number kWh yes AVILOO result Nominal battery capacity when new, from the test.
mileage_miles integer miles yes Battery Health Check The mileage the answer uses: your mileage_miles when you sent one, else the odometer at the test.
mileage_basis string yes Battery Health Check test, caller, null caller: your mileage_miles. test: the odometer at the test. Null when there is no mileage.

Valuation.base

Your own figure, echoed.

Field Type Unit Null Source Values Description
source string no Battery Health Check caller caller: your own figure, as you sent it.
source_label string yes Dealer supplied Your base_source label.
type string yes Dealer supplied retail, trade, part_exchange, null Your base_type.
amount integer yes Dealer supplied Your base_amount, in whole units of currency.
currency string no Dealer supplied GBP, EUR Your base_currency: GBP, or EUR on a request that sends currency=EUR.
provider object yes Battery Health Check Whose figure the base is, {key, name, status}: platform, your own. Present only on a request that sends valuation, base_provider, adjustment_mode or currency.

Valuation.battery

Field Type Unit Null Source Values Description
test_id integer no Battery Health Check The test the answer used.
soh_percent number percent yes AVILOO result State of health, exactly as GET /v1/tests/{id} serves it.
soh_display string yes Battery Health Check The figure as quoted (floored to one decimal place, with %), for a final result only.
grade string yes AVILOO result outstanding, excellent, good, fair, poor, null AVILOO's own grade, as on its certificate, for a final result only; null while not known.
result_status string yes Battery Health Check final, provisional, inconclusive, null As GET /v1/tests/{id}.
vehicle_supported boolean yes AVILOO result As GET /v1/tests/{id}.
tested_at string yes AVILOO result When the car was tested.
mileage_at_test_miles integer miles yes AVILOO result The odometer at the test.
test_age_days integer yes Battery Health Check Whole days since the test.
miles_since_test integer miles yes Battery Health Check Your mileage_miles minus the odometer at the test. Null without mileage_miles.
current boolean no Battery Health Check Whether this is the current test of the car: its newest certified test, else its newest test.

Valuation.battery_adjustment

The pounds-per-kWh adjustment to a base.

Field Type Unit Null Source Values Description
status string no Battery Health Check applied, no_deduction, refer, not_tested, not_available The pounds-per-kWh adjustment (threshold-v1): applied, no_deduction, refer, not_tested or not_available.
reason string yes Battery Health Check Why, as the top-level reason codes.
rule string no Battery Health Check threshold-v1 Always threshold-v1.
threshold_soh_percent number percent no Battery Health Check No deduction at or above this state of health: 90.
points_below_threshold number points yes Battery Health Check The threshold minus the floored state of health.
kwh_shortfall number kWh yes Battery Health Check points_below_threshold / 100 x the nominal capacity.
gbp_per_kwh integer GBP per kWh yes Battery Health Check Pounds per kWh for the model family.
gbp_per_kwh_basis string yes Battery Health Check Where the pounds-per-kWh figure comes from (illustrative in the sandbox).
amount integer GBP yes Battery Health Check The adjustment in whole pounds: zero or negative, never an uplift. Capped against a base; uncapped without one.
percent_of_base number percent yes Battery Health Check amount as a percentage of your base.
cap_percent integer percent no Battery Health Check A deduction never exceeds this share of a base: 15.
cap_applied boolean yes Battery Health Check Whether the cap reduced the deduction. Null without a base.
uplift_policy string no Battery Health Check none Always none: never an uplift.

Valuation.values

Field Type Unit Null Source Values Description
type string no Battery Health Check retail, trade, part_exchange Your base_type, or the type of the Battery Health Check value.
amount integer yes Battery Health Check Your base plus battery_adjustment.amount, or, for valuation=bhc_valuation, Battery Health Check's own value. Null unless there is a figure.
currency string no Battery Health Check GBP, EUR The currency of amount.

Valuation.if_tested

Only for a car with no test within your access.

Field Type Unit Null Source Values Description
status string no Battery Health Check not_available Always not_available in this version.
reason string no Battery Health Check NO_VEHICLE_DATA NO_VEHICLE_DATA: an untested car has no capacity or model family to apply a scenario to.
scenarios array no Battery Health Check Fixed scenario readings (90, 85 and 80 percent), never a figure for this car: each {scenario_soh_percent, adjustment}, every adjustment null in this version.
note string no Battery Health Check A test turns this into one figure.

Valuation.method

Field Type Unit Null Source Values Description
rule string yes Battery Health Check threshold-v1, null threshold-v1. Null for valuation=bhc_valuation.
version string yes Battery Health Check The rule version. Null for valuation=bhc_valuation.
parameters_version string yes Battery Health Check The version of the parameter set. Null when there is none.
parameters_as_of string yes Battery Health Check The date of the parameter set.