Integrating as a dealer group
Discovery, build, validation and production rollout. Most of it is self-service: the documentation, specification and sample data are public, a dealer’s administrators issue keys for that dealer themselves, and a platform serving many dealers is connected by each dealer with one click. 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 for one dealer or one dealer group | Nothing. Anyone with an owner or admin login in that dealer’s portal creates one, picks the access level, and passes it to you. Under a minute, no involvement from us. |
| Serve many dealers from one piece of software | A platform credential, by invitation. Email info@batteryhealthcheck.co.uk. After that, each dealer connects you itself; see below. |
| Read the documentation, spec and field reference | Nothing. All public, no login, linked in the header. The Postman collection has a request for every endpoint. |
| Get realistic data to build against | A sandbox credential, on request: fixture tests on the production base URL for every case (see Sandbox). Without one, the sample response pack shows real responses, anonymised, for the common cases. |
| Look up tests, download certificates, receive webhooks | Nothing. A dealer-issued key or a connected platform credential covers all of it. |
| Create dealer accounts or order AVILOO units over the API | This one you do need us for. It is for a dealer group’s own sites, on a dealer-group credential: the write:dealers scope is not self-serve, and a platform credential cannot hold it. 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
For one dealer or one dealer group. A platform serving many dealers follows the same steps on its own credential: see Building software for many dealers?
-
Get a key from the dealer
The dealer administrator issues the credential from the BHC portal and provides it to you. For a website or vehicle-listing integration 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; to try calls by hand, import the Postman collection. If they want the field-by-field detail with units and vocabularies, take the data dictionary.
-
Build against the sandbox
Ask us for a sandbox credential: it calls the production base URL, behaves as a platform credential connected to fixture dealers, and answers from fixture tests, the awkward cases included (a provisional reading, an inconclusive test, a failed one, a retest), with simulated webhook events. See Sandbox, and try each endpoint in your browser in the API explorer. The sample response pack shows real responses, anonymised. Build against the full set of cases rather than the successful one alone.
-
Go live
Point it at that dealer’s real tests. If you then find yourself serving a second and a third dealer, move to a platform credential rather than collecting a key from each.
Building software for many dealers?
If you are a DMS, website or stock-publishing platform serving several Battery Health Check dealers, hold one platform credential for your whole platform. Each dealer connects it to you; you never collect, store or rotate a key per dealer.
- One platform credential. We send your technical contact an invitation; you accept the Platform Terms and create the credential yourself, and its secret is shown once, in your browser. It sees nothing until a dealer connects you.
- A Connect link in your software. Put a “Connect Battery Health Check” button behind your Connect link. A dealer’s owner or admin clicks it, reads what you will and will not see in its own portal, and presses Connect.
GET /v1/connect-settingsreturns the link whenever you need it. GET /v1/connectionslists every dealer that has connected you and every site each connection covers, with the dealer reference your link carried.- Connection events. Subscribe your webhook endpoint to
bhc.connection.created,bhc.connection.updatedandbhc.connection.revokedand you are told the moment a dealer connects, changes its reference or disconnects. - A return link. Register your return URLs with
PUT /v1/connect-settings, addreturn_toto the Connect link, and the dealer comes back to your software after it connects, cancels or is refused, carryingbhc_status. - Never ask a dealer for its BHC portal password or API keys, and never put a credential in browser code. Credentials belong on your servers.
Software for many dealers is the step-by-step guide, with a worked example.
Building for a single dealer group, or as an agency for one? A key the group issues from its own portal is enough: follow the four steps. That key sees the group’s own sites only.
Before you go live
- The token is read from
data.access_token, inside the response envelope, and cached rather than requested per call. The token endpoint allows ten requests a minute. - Nothing publishes a figure it should not. A State of Health reaches a public page only when the publish decision for that test says it is publishable. A
provisionalorinconclusiveresult_status, or afinalresult the decision refuses (a finding on the test, a test more than 90 days old), shows the image or nothing, as itsimage.publishablesays. - 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.
- Only copies that hide the VIN go on a public page, from your own storage: the preview image, the anonymised certificate PDF and the anonymised warranty PDF and image. The anonymised certificate and warranty copies are marked
public_display: true, which says the VIN is hidden and nothing more. The preview image and the anonymised certificate carry the test’s result, so they go on a page only when the publish decision for that test saysimage.publishable: true. The full certificate and the full warranty show the VIN and stay with the dealer. - 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. - Rate limits are respected. They are counted per credential, so a credential serving many dealers shares one allowance across all of them. 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 | On a platform credential, nothing needed from us or from you: each new dealer connects you from your button, and appears in GET /v1/connections and in a bhc.connection.created event. A dealer group’s own key already covers branches the group adds. |
| Rotating a key | A dealer revokes and reissues its own keys from its portal. Credentials we issued are rotated through us; a platform credential’s connections stay with it, so read Key rotation first. |