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.
Source
Meaning
AVILOO result
Measured or reported by AVILOO for the completed test.
AVILOO diagnostics
Drawn from AVILOO’s extended detail record.
Vehicle BMS
Reported by the vehicle’s own battery management system and read by AVILOO. Not an independent measurement.
Battery Health Check
Produced by BHC: identifiers, derived status fields and administrative timestamps.
Dealer supplied
Entered by the dealer, or by a partner acting on their behalf.
DVLA / DVSA record
The 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.
Provider
Reported 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 valuation
Battery 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.
Field
Unit
vehicle.mileage_km
miles, despite the name (legacy; use vehicle.odometer)
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.
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_reasonDEALER_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_reasonDEALER_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_reasonDEALER_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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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 vocabularyaviloo_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.
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”.
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.
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.
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.