This is the API for dealers. One credential scoped to your own dealer group — provision branches, order AVILOO boxes, list your own tests and look up a car by VIN or registration.

Building for a marketplace? A platform that aggregates listings from several unrelated dealer groups has its own API and its own docs. Marketplace API docs →

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.

Units

Units are not uniform across the payload. Each field name carries its unit; this table lists them together.

Field	Unit
`vehicle.mileage_km`	kilometres
`battery.capacity_kwh, battery.nominal_kwh`	kWh
`battery.soh_percent`	percent
`battery.estimated_range_miles`	miles
`diagnostics.range.typical_, diagnostics.range.personal_`	miles
`diagnostics.range.wltp_*`	kilometres, as {from, to}
`diagnostics.energy_kwh.*`	kWh
`diagnostics.measurements.cell_temperature_c`	°C, as {min, max, delta, status}
`diagnostics.measurements.cell_voltage_v, pack_voltage_v`	volts
`diagnostics.measurements.average_current_a`	amps
`All *_at fields`	ISO 8601, UTC, Z suffix

Test

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

Field	Type	Null	Source	Values	Description
`id`	integer	no	Battery Health Check		BHC identifier for the test.
`internal_reference`	string	yes	Dealer supplied		Partner-defined identifier. Stored against the test and returned unchanged, so a partner can correlate BHC records with records in its own platform. Maximum 100 characters. Not validated for uniqueness, and not currently editable once set.
`dealer_id`	integer	yes	Battery Health Check		The dealer the test belongs to.
`unit_id`	integer	yes	Battery Health Check		The AVILOO unit that performed the test.
`status`	string	yes	Battery Health Check	`pending`, `in_progress`, `completed`, `failed`, `cancelled`, `null`	Lifecycle state of the test record.
`vehicle`	object	yes	AVILOO result		The vehicle tested.
`battery`	object	yes	AVILOO result		Headline battery figures.
`tested_at`	string	yes	AVILOO result		When the test was performed.
`results_received_at`	string	yes	Battery Health Check		When BHC received the result from AVILOO.
`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.
`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 may exceed 100. `inconclusive`: AVILOO completed the test without reaching a result, and no value will follow. Null: the result is not yet available, or the record predates this field. Describes this result; `vehicle_supported` describes the model.
`certificate_number`	string	yes	AVILOO result		AVILOO certificate number.
`certificate_available`	boolean	no	Battery Health Check		Whether the full certificate PDF can be retrieved.
`preview_available`	boolean	no	Battery Health Check		Whether the public-facing certificate image can be retrieved.
`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.

Test.vehicle

The vehicle the test was performed on.

Field	Type	Unit	Null	Source	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	AVILOO result	Model year.
`mileage_km`	number	kilometres	yes	AVILOO result	Odometer reading at the time of test.

Test.battery

Headline battery figures. Interpret alongside result_status before displaying publicly.

Field	Type	Unit	Null	Source	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	Measured usable capacity.
`nominal_kwh`	number	kWh	yes	AVILOO result	Nominal capacity when new.
`estimated_range_miles`	number	miles	yes	AVILOO result	Estimated range at the measured capacity. Null where AVILOO did not derive one.
`cell_count`	integer		yes	AVILOO result	Number of cells in the pack.
`cell_variance`	number	volts	yes	AVILOO result	Spread across cell voltages. Lower values indicate a more balanced pack.

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.
`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		Typical and personal range in miles; WLTP figures in kilometres as `{from, to}` objects. Units differ between the two — see the units table.
`measurements`	object		yes	AVILOO diagnostics		Cell temperature (°C) and cell voltage (V) as `{min, max, delta, status}`; pack voltage (V), average current (A) and mileage (km) as scalars.
`bms`	object		yes	Vehicle BMS		Values reported by the vehicle's own battery management system, and AVILOO's assessment of how accurate each is. 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.

Dealer

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

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

WebhookEndpoint

A registered webhook endpoint.

Field	Type	Null	Source	Values	Description
`id`	integer	no	Battery Health Check		BHC identifier for the endpoint.
`url`	string	no	Dealer supplied		Destination URL. HTTPS only.
`events`	array	yes	Dealer supplied	`bhc.dealer.activated`, `bhc.test.completed`, `bhc.test.failed`, `null`	Event types delivered to this endpoint.
`disabled_at`	string	yes	Battery Health Check		Set when the endpoint was disabled after repeated delivery failures.
`consecutive_failures`	integer	no	Battery Health Check		Consecutive failed deliveries. Resets on a successful delivery.
`last_success_at`	string	yes	Battery Health Check		Last successful delivery.
`last_attempt_at`	string	yes	Battery Health Check		Last delivery attempt.
`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.