How to integrate
Discovery, build, validation and production rollout. Most of it is self-service: the documentation, specification and sample data are public, and dealer administrators issue integration credentials themselves. BHC is involved only where a step requires it, and this page states where that is.
What you need from us
| To do this | You need from us |
|---|---|
| Get an API key | Nothing. Any dealer with an owner or admin login creates one in their own portal, picks the access level, and sends it to you. Under a minute, no involvement from us. |
| Read the documentation, spec and field reference | Nothing. All public, no login, linked in the sidebar. |
| Get realistic data to build against | Nothing. The sample response pack provides a representative set of responses covering successful, provisional and other result states. |
| Look up tests, download certificates, receive webhooks | Nothing. A dealer-issued key covers all of it. |
| Create dealer accounts or order AVILOO units over the API | This one you do need us for. The write:dealers scope is not self-serve. Email info@batteryhealthcheck.co.uk. |
| Lock a credential to your egress addresses | Ask us — see IP allow-listing. |
| Help when something is wrong | Email info@batteryhealthcheck.co.uk. |
The four steps
-
Get a key from a dealer
The dealer administrator issues the credential from the BHC portal and provides it to you. For DMS and vehicle-listing integrations we recommend read-only access, which permits retrieval of test results and certificates without provisioning or ordering permissions.
-
Read
The documentation is the whole reference on one page, including three worked examples. If your team generates clients, take the OpenAPI spec. If they want the field-by-field detail with units and vocabularies, take the data dictionary.
-
Build against the sample pack
We do not currently provide a public sandbox. The sample response pack provides a representative set of responses covering successful, provisional and other result states. Build against the full set rather than the successful case alone.
-
Go live
Point it at that dealer’s real tests. Adding more dealers afterwards needs nothing from us — each one issues you their own key.
Before you go live
- Nothing publishes a figure it should not. Branch on
result_statusbefore rendering a State of Health, and handleprovisionalandinconclusivedifferently fromfinal. - Model validation status is respected.
vehicle_supported: falseis not silently ignored. - Nulls are handled. We never drop a key, so absent data arrives as
nullrather than a missing field. - Results are joined on the VIN, not the registration. Plates transfer between vehicles; VINs do not.
- Webhook signatures are verified, and the
bhc.webhook.testevent is never treated as a result — it carries no vehicle or battery fields precisely so it cannot be. - Tokens are cached rather than requested per call. The token endpoint allows ten requests a minute.
- Rate limits are respected, including the per-source-IP ceiling if you call for many dealers from few servers. See Rate limits.
Once you are live
| Getting help | info@batteryhealthcheck.co.uk. Include the request_id from any failed call, your client_id (never your secret), timestamps in UTC, and what you expected versus what happened. |
|---|---|
| Response | One business day for standard issues. Faster where something is broken in production. |
| Changes | We add fields without notice — ignore keys you do not recognise. We do not rename or remove them, change types or units, or repurpose status codes. Breaking changes ship on a new version path, never in place. |
| Adding dealers | Nothing needed from us. Each dealer issues their own key. |
| Rotating a key | The dealer revokes and reissues from their portal. Ours to do only for credentials we issued. |