Battery Health CheckDevelopers
OpenAPI Samples Postman

Dealer group and platform API. For dealer groups using their own tests, and for software that many dealers use. Running a car-listing site? Marketplace API

Sandbox

A credential that answers from fixed fixture tests, for building and testing an integration before a pilot with real cars. By invitation.

The sandbox

A sandbox credential lets you build and test an integration without touching real data. It is a credential, not a separate host: you call the production base URL, https://api.batteryhealthcheck.co.uk/v1, with a token issued exactly as in production, and every response is answered from a fixed catalogue of fixture tests at four fixture dealers.

Production’s shape. Every sandbox answer has the keys and JSON types a production answer has, so code written against one parses the other. Each fixture’s AVILOO result is built in the full shape AVILOO sends and read by the same code that reads a real test, so every field a real test fills, some fixture fills; and between them the fixtures show every state real tests show, though not in production’s proportions. Only the values are invented.

A sandbox credential can never reach a real dealer’s data. A real VIN, registration or test id finds nothing, and no real test event is ever delivered to its webhooks.

It behaves as a platform credential: it lists tests, accepts a VIN prefix of three characters or more, a registration, since, until and updated_since, lists three fixture connections at GET /v1/connections, embeds the slim {id, name} dealer object, accepts the platform’s webhook events including the connection events, and stores its own /v1/connect-settings. Its rate limits are in the sandbox column of the rate-limit table. Endpoints a platform credential cannot call, such as /v1/dealers, are refused with the same 403 insufficient_scope a platform credential receives.

Provider modes. Besides AVILOO results and AVILOO’s battery readings, the API lists vehicle-history providers. DVSA’s MOT history and the vehicle record provider’s record are live in production, and the sandbox serves both from invented fixture data. Production shows every other vehicle-history provider as available subject to agreement with the provider and answers nothing from it; the sandbox shows what their answers look like, as invented history checks attached to some fixture cars, each in its provider’s own shape and marked sandbox_illustrative. See Providers in the sandbox.

What it is not. It is not a pilot and proves nothing about real cars: its battery figures are invented, and its certificates are specimens. To prove an integration on a real vehicle, use a production credential with a dealer you work with.

Getting sandbox access

Sandbox credentials are issued by Battery Health Check, by invitation, to developers we are working with. Ask your contact at Battery Health Check for one.

A sandbox client_id always starts part_test_; a production one never does. Exchange it for a token at POST /v1/oauth/token exactly as you would a production credential (see Getting a token). The token response, like every sandbox response, carries the header BHC-Environment: sandbox.

ScopeWhat it does in the sandbox
read:testsList and read the fixture tests and the three fixture connections.
read:certificatesSigned links to the anonymised specimen certificate PDF and the preview image.
read:warrantiesSigned links to the anonymised specimen warranty PDF and image, for fixtures whose warranty carries a document.
manage:webhooksRegister webhooks on your sandbox credential and simulate events to them; rehearse /v1/connect-settings.

A sandbox credential issued before read:warranties was added to the sandbox does not hold it, and receives 403 insufficient_scope from the warranty document, as a platform credential without the scope does.

Like a platform credential, a sandbox credential receives the anonymised certificate and warranty copies only: without variant each document route returns the anonymised specimen, and ?variant=full answers 403 variant_not_permitted. The full copies are for dealer credentials (see Which version your credential receives).

Postman. The Postman collection has a request for every endpoint and fetches the token for you. Set its client_id and client_secret variables to your sandbox credential and every request answers from the fixtures.

A sandbox credential is never converted into a production one. Production access is a separate credential, with its own secret and its own webhooks.

Fixture tests

Four fixture dealers, reached through three fixture connections at GET /v1/connections. Three are in Great Britain, with the postcode ZZ99 9ZZ, and one is in Ireland, with the Eircode Z99 ZZZZ; neither is ever issued.

Dealer idNameConnection (platform_reference)
990001BHC Sandbox Motors Northsandbox-north
990002BHC Sandbox Motors North – Harrogate (a branch of 990001)sandbox-north
990003BHC Sandbox Motors Southsandbox-south
990004BHC Sandbox Motors Ireland (billing in euros)sandbox-ireland

Fifty fixture tests, each chosen to show a state you must handle; between them they show every state real tests show. Most completed cars are final results between 92% and 99%, as most real ones are, and every completed test carries a warranty state. They are a catalogue of cases, not a sample: how often each state appears here is not how often it appears in production. Dates are relative to today: each fixture is always the same number of days old, and the two unfinished fixtures, 990000010 (pending) and 990000046 (in_progress), always started minutes ago. Read result_status, vehicle_supported and warnings on each before you decide how to display it, exactly as in production.

Test idVINRegistrationDealerWhat it shows
990000001BHCTESTVIN0000001ZZ23MGFNorthFinal result, excellent; warranty ACTIVE, with the anonymised specimen warranty PDF and image, and the only illustrative warranty terms (see How it differs)
990000002BHCTESTVIN0000002ZZ20KNRNorth – HarrogateFinal result, good; MOT mileage reads higher than the test (discrepancy)
990000003BHCTESTVIN0000003ZZ19NLFSouthFinal result, fair; warranty INELIGIBLE (VEHICLE_NOT_SUPPORTED)
990000004BHCTESTVIN0000004ZZ21RZENorthFinal result, poor, with an AVILOO finding (SOH_TOO_LOW, result WARNING)
990000005BHCTESTVIN0000005ZZ21HDENorth – HarrogateProvisional: SoH over 100% on a model in validation
990000006BHCTESTVIN0000006ZZ24BYDSouthFinal result on a model in validation (beta)
990000007BHCTESTVIN0000007ZZ22PGTNorthInconclusive: AVILOO reached no verdict (NO_RELAXED_PHASES)
990000008nonenoneNorth – HarrogateFailed: the box read nothing from the car (DONGLE_NO_VIN_EXCEPTION)
990000009BHCTESTVIN0000009ZZ18UNKSouthFailed: model not yet supported by AVILOO (make and model from the registration record)
990000010BHCTESTVIN0000010ZZ23KEVNorthPending: data acquisition started 10 minutes ago
990000011BHCTESTVIN0000011ZZ22HIQNorth – HarrogateStalled: no result two days after starting
990000012BHCTESTVIN0000012ZZ20VWGSouthFinal result, tested 104 days ago: older than 90 days, so not publishable (TEST_OLDER_THAN_90_DAYS)
990000013BHCTESTVIN0000013ZZ21TSLNorthFinal result, but older than 90 days (stale)
990000014BHCTESTVIN0000014ZZ19PLTNorth – HarrogatePlate transfer A: older test of one car under plate ZZ19PLT
990000015BHCTESTVIN0000015ZZ19PLTSouthPlate transfer B: newer test of a different car under the same plate. A lookup by the plate with no dealer_id is ambiguous, so both its decisions say AMBIGUOUS_REGISTRATION; with a dealer_id, each dealer’s lookup finds its own test
990000016BHCTESTVIN0000016ZZ22SKENorthRetest, first try: inconclusive (MISSING_SIGNAL ten times, as real inconclusive tests carry it)
990000017BHCTESTVIN0000016ZZ22SKENorthRetest, second try: final result (same car as 16, recovered)
990000018BHCTESTVIN0000018ZZ22PSTNorth – HarrogateWarranty withdrawn after the test (UNAVAILABLE)
990000019BHCTESTVIN0000019noneSouthIrish import at a GB dealer, no registration recorded: findable by VIN only
990000020BHCTESTVIN0000020ZZ20MOPSouthPlug-in hybrid (PHEV); MOT history from DVSA
990000021BHCTESTVIN0000021ZZ21VXCNorthCertificate and preview never ready (always 409)
990000022BHCTESTVIN0000022ZZ20NNVSouthSafety finding (CELL_VOLTAGE_SPREAD_CRITICALLY_HIGH); MOT history from DVSA
990000023BHCTESTVIN0000023ZZ15NLENorthFinal result, poor, with no AVILOO warning
990000024BHCTESTVIN0000024ZZ23RMGNorthSold on, first dealer (North): same car as 25, an unrelated connection; tested four months earlier, so older than 90 days
990000025BHCTESTVIN0000024ZZ23RMGSouthSold on, second dealer (South): same car as 24. A lookup of its VIN with no dealer_id carries the warning MULTIPLE_DEALERS
990000026BHCTESTVIN0000026ZZ24PEUNorthRetest burst, first try: failed (DONGLE_SIDE_TIMEOUT), superseded by 28
990000027BHCTESTVIN0000026ZZ24PEUNorthRetest burst, second try: final result, superseded by 28 a few minutes later
990000028BHCTESTVIN0000026ZZ24PEUNorthRetest burst, third try: the car’s current test
990000029BHCTESTVIN0000029ZZ23CPRSouthFailed: AVILOO does not recognise the VIN (make and model from the registration record)
990000030nonenoneNorthFailed: no vehicle detected, box not connected or ignition off (DONGLE_NO_VEHICLE_EXCEPTION); no warranty state established
990000031nonenoneNorth – HarrogateFailed: the test did not finish (INCOMPLETE)
990000032BHCTESTVIN0000032ZZ24XPGSouthFailed: AVILOO has no model group for the car (UNKNOWN_MODEL_GROUP)
990000033BHCTESTVIN0000033ZZ22FMMNorthFailed: AVILOO received the data but could not analyse it (EVALUATION_FAILED); warranty PENDING
990000034BHCTESTVIN0000034ZZ22VWFNorth – HarrogateWarning result: current sensor (CURRENT_OUTSIDE_ACCEPTABLE_RANGE)
990000035BHCTESTVIN0000035ZZ22CTNSouthWarning result: cell voltage spread (CELL_VOLTAGE_SPREAD_TOO_HIGH)
990000036BHCTESTVIN0000036231QX1001IrelandIrish dealer: final result on an Irish plate; English copy withheld (REGION_NOT_REVIEWED)
990000037BHCTESTVIN0000037221QX207IrelandIrish dealer: a second Irish car
990000038BHCTESTVIN0000038201QX4410NorthIrish-registered car tested at a GB dealer
990000039BHCTESTVIN0000039BZZ4410SouthNorthern Ireland style plate; MOT history from DVA NI
990000040BHCTESTVIN0000040R100AZZNorth – HarrogatePrefix-era private plate on a modern car; warranty ACTIVE, the only one whose created_at is filled, with no terms (see How it differs)
990000041BHCTESTVIN0000041ZZ25KEVNorthNew car (2025): vehicle record found, no MOT yet
990000042BHCTESTVIN0000042ZZ26BYDSouthNew car (2026): vehicle record found, no MOT yet
990000043BHCTESTVIN0000043ZZ23VLVSouthPlug-in hybrid, provisional: SoH over 100% on a supported model
990000044BHCTESTVIN0000044ZZ24VWINorthProvisional on a supported model, with an ACTIVE warranty
990000045BHCTESTVIN0000045ZZ22TYHNorth – HarrogateSelf-charging hybrid (HEV)
990000046BHCTESTVIN0000046ZZ23HSXNorthIn progress at AVILOO: awaiting manual verification of a possible safety finding (BATTERY_TEMP_CRITICALLY_HIGH)
990000047BHCTESTVIN0000047ZZ23KNESouthResult under review (DISPUTED)
990000048BHCTESTVIN0000048ZZ22MBQSouthA good result, retested weeks later: this final result stays the car’s current test
990000049BHCTESTVIN0000048ZZ22MBQSouthThe retest of 48: failed (DONGLE_SIDE_TIMEOUT). The car’s latest test, but 48 is still its current test
990000050BHCTESTVIN0000050ZZ23CTBNorth – HarrogateInconclusive as most real ones are: no pack voltage, battery-management state of charge or odometer was read (MISSING_SIGNAL)

One car, several tests. Tests 990000016 and 990000017 are one car tested twice: the inconclusive first try (990000016) answers INCONCLUSIVE at /publish, with SUPERSEDED among its reasons and superseded_by 990000017. Tests 990000026 to 990000028 are one car tested three times in twenty minutes, as dealers often do: the earlier final result (990000027) answers SUPERSEDED; the failed first try (990000026) answers TEST_DID_NOT_COMPLETE, with SUPERSEDED among its reasons; both carry superseded_by 990000028, the car’s current test. reason is only the first of reasons, in the order the publish reference gives, so read superseded_by, not reason, to find a newer test. Tests 990000048 and 990000049 are one car whose retest, weeks after a good result, failed: the retest (990000049) answers TEST_DID_NOT_COMPLETE, with superseded_by null and current_test_id 990000048, because a failed or inconclusive retest never replaces a result. It is the car’s newest test, so a lookup of BHCTESTVIN0000048 answers latest_test 990000049 and current_test 990000048, and current=true lists only 990000048: rehearse step 6 of the Platform quickstart on it. The lookup’s current_publish is the decision for 990000048, while its publish is the failed retest’s. Tests 990000024 and 990000025 are one car tested at two unrelated dealers; each dealer’s answers use its own test only. Tests 990000014 and 990000015 are two different cars that carried the same plate: a registration search returns both, so join on vehicle.vin.

Failures. Fixtures 990000008, 990000009, 990000026, 990000029 to 990000033 and 990000049 show every failure reason real tests carry. A failed test has no diagnostics and, unless AVILOO received its data (990000033), no results_received_at. When the box read nothing from the car, the test has no VIN, registration, make or model; when AVILOO did not recognise the car, the make and model come from the registration record, in its own capitals.

Ireland. Dealer 990004 is Irish: its tests carry Irish registrations and an Irish register record, have no MOT history (the MOT is a UK test), and their /publish answer withholds the advert copy with copy_withheld_reason REGION_NOT_REVIEWED, as for every real Irish dealer. Fixture 990000038 is an Irish-registered car at a GB dealer.

Timing. As in production, tested_at is when the test started and results_received_at when AVILOO finished it, a few minutes later. Several fixtures have an updated_at days or weeks after the test, as a warranty or record change leaves it. Every other fixture with a result was last updated six hours to three days after the result arrived, as production rows are touched again after it; until that moment comes, a recent fixture’s updated_at is the moment its result arrived. A fixture is never updated in the future.

Providers in the sandbox

Battery readings come from AVILOO, in the sandbox as in production. In production, provenance comes from DVSA (the MOT history) and the vehicle record provider only; every other provenance provider is Planned and answers nothing. The sandbox also shows what those Planned providers’ answers look like, so you can build for them now: invented checks attached to some fixture cars, each in that provider’s own shape.

  • Every such check has "availability": "sandbox_illustrative" and SANDBOX_DATA in its warnings, and every value in it is invented. Its provider’s status is still the production one.
  • An AVILOO reading in the sandbox is built from the fixture test itself, exactly as production builds one from a real test, so its availability is live; it carries SANDBOX_DATA too.
  • A sandbox check from the vehicle record provider (vdg) is built from the fixture’s vehicle record and is sandbox_illustrative.
  • Most fixture cars that have had an MOT carry an invented DVSA MOT history, as most real cars do, because the nightly MOT sync holds their plate: from DVSA, except BHCTESTVIN0000039, from DVA NI (Northern Ireland). Their provenance answer carries a dvsa check, marked sandbox_illustrative with SANDBOX_DATA, and their passport’s mot block comes from it, with DVSA’s attribution and every test numbered, as in production. The test numbers start 9999 and are not DVSA’s. The cars with an MOT that keep their vehicle record’s history in the passport, often with blank test numbers, are BHCTESTVIN0000007, BHCTESTVIN0000014 (its plate now belongs to another car, whose make DVSA’s copy carries), BHCTESTVIN0000034 and BHCTESTVIN0000040. They, and every car too new for an MOT, list DVSA with reason no_record.
  • Readings and checks are served only for a fixture car found within the sandbox’s reach, as production serves only a car with a test within yours. A car the sandbox does not hold is found: false, with every provider vehicle_not_found.

Battery readings: GET /v1/vehicles/battery-readings

Every completed fixture test gives an AVILOO reading, built from the fixture test exactly as production builds one from a real test. A fixture that has not completed is found with no readings. providers lists AVILOO, with readings_returned counting its readings for that car.

Provenance: GET /v1/vehicles/provenance

Every fixture check carries all twelve sections, in the provider’s own shape: its own field names in native, and the section’s fields in records. Lender and police-force names are fictional, and every date of a previous use or a register marker is invented. Where a provider covers status and records no marker, it is none_found.

CarChecksWhat they show
BHCTESTVIN0000001
ZZ23MGF
Vehicle record provider, UK and Irish history check providerA clean car: in the UK and Irish history check provider’s check, finance, write-off, stolen, plate changes, mileage anomaly, recalls, previous use (previous_use) and register markers (status) are all none_found, beside its keeper count, mileage readings and MOT history.
BHCTESTVIN0000002
ZZ20KNR
Vehicle record provider, UK history check provider A, UK history check provider BOutstanding finance, from both UK history check providers A and B, each in its own words. Provider B’s own mileage out-of-sequence flag: mileage_anomaly is found, with the flag in native and no records. Provider B’s mot_tests is not_licensed.
BHCTESTVIN0000003
ZZ19NLF
Vehicle record provider, UK and Irish history check provider, UK history check provider AA Category S write-off. The UK and Irish history check provider gives the category (category S, category_scheme uk_abi_2017); UK history check provider A records the write-off with no category field (category null, category_source none). The check that gives the category also records the car’s earlier use as a private hire car: previous_use is found, with use_type private_hire and its from_date and to_date.
BHCTESTVIN0000004
ZZ21RZE
Vehicle record provider, UK history check provider BA stolen marker: stolen_police is found.
BHCTESTVIN0000014
ZZ19PLT
Vehicle record provider, UK history check provider BA plate change: the car moved off ZZ19PLT, the plate fixture 990000015 carries now (plate_changes is found).
BHCTESTVIN0000019
no registration
Irish history check providerAn Irish car (jurisdiction IE): stolen_police is not_available, because no stolen-vehicle data exists in Ireland; keepers counts owners including garages (counting_basis ie_owners_incl_garages); finance is pending, as that provider’s finance check can finish after the rest; mot_tests is not_applicable. The car has since left Ireland for the UK, so status is found with two records: exported to GB, with its date, from the Irish register, and imported, from its UK record, which gives the flag alone, so its date and country are null. Found by VIN only.

In the sandbox every provider is consulted for a fixture car within reach: one with nothing for that car is listed with "served": true and "reason": "no_record". Most fixture cars have a vehicle record, as most real cars do: every fixture car with a VIN has a fixture vehicle record, and so a check from the vehicle record provider, except BHCTESTVIN0000010, BHCTESTVIN0000019, BHCTESTVIN0000022 and BHCTESTVIN0000046. While that data is not being supplied, its reason is not_offered, as in production. The records show every kind production returns: an MOT history with its tests; an MOT history with no test yet, for a car too new for its first MOT (for example BHCTESTVIN0000041 and BHCTESTVIN0000042), where mot_tests is none_found; a DVLA record with no MOT history (BHCTESTVIN0000039); and an Irish register record (BHCTESTVIN0000036 to BHCTESTVIN0000038), where mot_tests is not_applicable. The DVLA record carries the DVLA’s import, export and scrapped markers, as every real DVLA record does: BHCTESTVIN0000039 was imported before its first MOT in Northern Ireland, so its vehicle record provider check’s status is found, with one imported record, its date set and its country null (the DVLA names none), and the markers in native. The MOT-history and Irish records carry no markers, so their status is not_checked. The MOT histories are full records with passes, fails and retests, and between them every defect type: ADVISORY, MINOR and PRS (BHCTESTVIN0000001), FAIL (BHCTESTVIN0000002), MAJOR (BHCTESTVIN0000003) and DANGEROUS (BHCTESTVIN0000015, which also has a test whose odometer was UNREADABLE, with no reading and no unit). As on most real records, the provider’s test number is often blank, and is then null.


Valuation (beta)

Beta: figures in the sandbox now; production figures follow. Every figure the sandbox returns is invented, and nothing here is for public display. The routes, parameters and the full answer are in the reference: Valuation.

Both valuation routes answer a sandbox credential holding the read:valuations scope; without it, both answer 404 not_found, so ask us if yours lacks it. GET /v1/valuations needs dealer_id on a sandbox credential.

Send adjustment_mode or currency, or ask for valuation=bhc_valuation, to see figures. The answer then carries the valuation adjuster (adjustment) and the Battery Health Check value grid (value_grid), with "illustrative": true and SANDBOX_DATA in warnings. valuation=bhc_valuation alone gives them too, in percent mode and GBP, with Battery Health Check’s single value for the car in values. valuation=battery_adjustment or base_provider alone gives sandbox figures without those two blocks. Read illustrative, not mode: mode reports the production mode (contract) even while the sandbox shows figures. A request with none of the four is answered exactly as production answers it, with no figure.

What each fixture car shows

RequestWhat comes back
GET /v1/tests/990000002/valuation?adjustment_mode=percentA percentage: the battery sits 7.3 points below the reference for its age and mileage, so adjustment.percent is -3.7, with a full value grid in GBP.
GET /v1/tests/990000002/valuation?valuation=bhc_valuationThe Battery Health Check valuation of the same car: one value in values, and the same adjustment and value grid in GBP.
GET /v1/tests/990000019/valuation?adjustment_mode=absolute&currency=EURAn amount in euros on an Irish car, here an Irish import at a GB dealer: adjustment.amount -357, currency EUR, and a value grid in EUR.
GET /v1/tests/990000001/valuation?adjustment_mode=percentA battery at or above its reference: adjustment.percent is 0.0. The adjustment is never an uplift.
GET /v1/valuations?vin=BHCTESTVIN0000099&dealer_id=990001&adjustment_mode=percentA car the sandbox holds no test of: not_tested in every block, every figure null.

Every fixture car whose test is not referred gives a percentage, an amount and a value grid in GBP. The Irish cars also give them in euros: 990000019, and the Irish dealer’s 990000036 and 990000037. A euro request for any other car answers not_available with NO_VALUE.

No figure for a battery that should not have one

A car whose battery test may not be published, or whose battery is below 70%, gets no figure in any block: status is refer, and reason says why. To see a refer:

Fixture testreason
990000022SAFETY_FINDING: a safety finding on the test.
990000023BELOW_70: the battery is below 70%.
990000004AVILOO_FINDING: a finding on the test, so it may not be published.

The other fixtures that cannot be published refer with their own publish reason, as the fixture table suggests: an inconclusive, provisional, failed, stale or unfinished test, and a model in validation.


Fixture VINs and registrations

Every fixture identifier is impossible on a real vehicle, so sandbox data can never be matched to a car in your stock:

IdentifierShapeWhy it cannot be real
VIN^BHCTESTVIN\d{7}$It contains the letter I, which ISO 3779 does not allow in a VIN. Our own validator accepts it, so it passes every request.
Registration, Great BritainZZnnLLL, for example ZZ19PLTNo current-style plate starts ZZ.
Registration, Irelandnnn-QX-n, for example 231-QX-1001QX is no Irish county or city code.
Registration, Northern Ireland styleLZZnnnn, for example BZZ4410ZZ is no Northern Ireland area code.
Registration, prefix eraLnnnLZZ, for example R100AZZZZ is no area code.

Plates are returned compact, with no spaces or hyphens (231QX1001, ZZ19PLT), exactly as production returns every registration. Every request accepts a plate compact, spaced or hyphenated, in either case: ZZ19 PLT, zz19-plt and 231 QX 1001 all find their fixtures, as they would in production.

If your own systems validate VINs or registrations strictly, allow these shapes in your test environment only, never in production. As one expression, compact or spaced: ^(ZZ\d{2} ?[A-Z]{3}|\d{2,3}[- ]?QX[- ]?\d{1,6}|[A-Z]ZZ ?\d{1,4}|[A-Z]\d{1,3} ?[A-Z]ZZ)$.

Vehicles with no test. BHCTESTVIN0000099, BHCTESTVIN0000098 and ZZ70NOT match no fixture: use them to exercise your “not tested” path.

A real VIN or registration looked up with a sandbox credential also finds nothing. The sandbox answers “not found” for anything outside its catalogue; it never returns a figure for a car it does not hold.

Simulating webhook events

POST /v1/sandbox/simulate

Sandbox credentials only; any other credential receives 404 not_found. Required scope: manage:webhooks. Limited to 10 requests a minute.

Queues one delivery of a real event, carrying a fixture test or a fixture connection, to your own webhooks. Register a webhook on your sandbox credential first with POST /v1/webhooks, using a separate receiver URL from your production one (see How the sandbox differs).

Request body

FieldTypeDescription
eventstringRequired. A test event, bhc.test.completed, bhc.test.failed or bhc.test.warranty_changed; or a connection event, bhc.connection.created, bhc.connection.updated or bhc.connection.revoked.
fixture_idintegerRequired. For a test event, a fixture test id: bhc.test.completed needs a completed fixture, bhc.test.failed a failed one, and bhc.test.warranty_changed one with a warranty state. For a connection event, the dealer_id of one of the three fixture connections, 990001, 990003 or 990004.
endpoint_idintegerOptional. One of your webhooks. Without it, every enabled webhook of yours subscribed to the event receives it.
platform_referencestringOptional, connection events only; a test event ignores it, as it ignores any key it does not read. The delivery’s data.platform_reference carries it in place of the fixture connection’s own (sandbox-north, sandbox-south or sandbox-ireland), so you can send a reference you issued, or one you did not, and rehearse the reference check in step 4 of the platform quickstart. It takes what a Connect link’s ref takes: up to 100 letters, digits, ., _ and -, counted after surrounding spaces are removed. An empty string sends null, as for a dealer who connected without a reference. Only the delivery changes: GET /v1/connections still lists the fixture connection with its own reference.
POST /v1/sandbox/simulate
{ "event": "bhc.test.completed", "fixture_id": 990000001 }

POST /v1/sandbox/simulate
{ "event": "bhc.connection.created", "fixture_id": 990001 }

POST /v1/sandbox/simulate
{ "event": "bhc.connection.created", "fixture_id": 990001, "platform_reference": "c0n-7Hq2xK9vLm4pR8sT" }

Response 202 Accepted

{
  "data": {
    "queued": 1,
    "deliveries": [
      { "id": 5521, "endpoint_id": 12, "event_id": "x0pV3sEw9qL2mB7tYc4n1A" }
    ]
  },
  "meta": { "environment": "sandbox", "request_id": "req_k2m4n6p8r0t2" }
}

Errors

StatusCodeWhen
400invalid_requestThe body is not a JSON object.
400invalid_fieldfixture_id or endpoint_id is not an integer, or, on a connection event, platform_reference is not a string a Connect link’s ref would take.
404not_foundThe credential is not a sandbox credential, fixture_id is not a fixture (or, for a connection event, not a fixture connection), or endpoint_id is not one of your webhooks.
422validationAn unknown event (the error lists the six events as allowed), an event the fixture cannot produce, a webhook that is disabled or not subscribed to the event, or no enabled webhook subscribed to it.

The delivery

The delivery has exactly the production shape. For a test event it is {"event": …, "data": {"test": …, "dealer": {"id", "name"}}}, where data.test is the fixture as GET /v1/tests/{id} returns it. For a connection event, data is the fixture connection exactly as the sandbox’s GET /v1/connections lists it, with revoked_at (the time you simulated it) on bhc.connection.revoked, and with your platform_reference if you sent one; the fixture connection itself does not change. It is signed with that webhook’s own secret (see Signing), retried on failure, and can be re-sent with POST /v1/webhooks/{id}/replay, all as in production. It also carries the header BHC-Environment: sandbox, a dealer name containing “Sandbox” and a BHCTESTVIN VIN. The test object’s own warnings are the fixture’s, exactly as a real test’s would be.

How the sandbox differs from production

Recognising a sandbox response

  • Every response to a sandbox credential, the token response included, carries the header BHC-Environment: sandbox. Production responses never carry it.
  • Every sandbox success envelope carries "environment": "sandbox" in meta. Production envelopes have no environment key.
  • Objects introduced alongside the sandbox (publish blocks, passports, batch lookup and stock-check results, battery readings and vehicle history responses with each reading and check in them, and the structured output of MCP tools) carry SANDBOX_DATA in their own warnings array, including an item that found nothing.
  • A test object never carries SANDBOX_DATA: its warnings are AVILOO’s vocabulary, and a fixture’s are exactly what a real test in that state would carry. Recognise a fixture test by the response header and envelope, its BHCTESTVIN VIN, its SANDBOX-TEST- internal_reference and its dealer name.

What is different

AreaIn the sandbox
Certificates and previews/certificate and /preview return a signed link to a specimen: a two-page PDF or a 1920 × 1440 JPEG (the size of a production preview) watermarked “SPECIMEN · SANDBOX · NOT A BATTERY TEST”, the same file for every fixture. The link needs no token and expires after an hour, like a production link. Every fixture with a certificate carries an invented certificate_number in production’s format (BHC-XXXX-XXXX-XXXX), fixed for that fixture: it never changes, even as the fixture’s dates move. As for a platform credential, /certificate returns the anonymised specimen PDF, with the VIN masked, with or without ?variant=anonymised, and ?variant=full is 403 variant_not_permitted. Fixture 990000021, and the failed and unfinished fixtures, always answer 409 with retry_after_seconds, so you can exercise your retry path.
Warranty documents/warranty returns a signed link to a specimen warranty PDF, watermarked and stating no terms, for a fixture whose warranty carries a document; any other fixture is 404, as in production. As for a platform credential, it is the anonymised specimen, with the VIN masked, with or without ?variant=anonymised, and ?format=image returns the anonymised specimen image; ?variant=full is 403 variant_not_permitted, and an unknown variant or format is 400 invalid_field, as in production.
Who you areAlways a platform credential, connected to three fixture dealers (North, with one branch; South; and Ireland). Pass dealer_id wherever a platform credential must.
DataFixed. The fixtures never change except that their dates move with today, so a test that is 140 days old is always 140 days old. Nothing you do changes them.
WebhooksReal: the webhooks you register on your sandbox credential, and the deliveries simulate sends to them, are stored and delivered like production ones. No real event ever reaches them.
Connect settingsGET and PUT /v1/connect-settings work and store your own list, so you can rehearse them. connect_url is null, because no dealer can connect a sandbox credential, and your return URLs are never followed.
Rate limitsThe sandbox column of the rate-limit table: the platform figures, except GET /v1/providers. If you exceed one you receive HTTP 429; wait the seconds in its Retry-After header (never more than 60).
Other providersInvented history checks from provenance providers production does not serve, marked sandbox_illustrative: see Providers in the sandbox.
WarrantyEvery sandbox warranty block carries "source": "sandbox_illustrative"; in production it is "provider_record". Fixture 990000001 is the only one whose terms are filled, with invented values: issued_at (when its result arrived), expires_at (a year later) and soh_threshold_percent. Every other fixture’s terms are null, as they are in production unless AVILOO has sent them with its warranty notice. mileage_limit is null on every fixture, as on every production warranty, because AVILOO sends the limit without its unit and we never assume one (its shape when filled, {value, unit}, is in the warranty reference). created_at is filled on 990000040 only: production fills it from AVILOO’s warranty notice, and only where the notice reached us after we began storing it. 990000001 shows a warranty whose notice arrived before that, with terms but no created_at; 990000040 shows one whose notice arrived after. On both, the timestamps keep production’s order: AVILOO created the warranty seconds before the result arrived, the notice reached us after the result, and state_changed_at, as_of and the test’s updated_at are no earlier than the notice. compensation is null on every fixture, as it is in production.

Use a separate webhook receiver

Register a different URL for sandbox webhooks from the one your production credential uses. Each webhook has its own signing secret, so a production receiver that verifies signatures rejects a sandbox delivery; but a receiver configured with the sandbox secret, or one that does not verify signatures, would accept fixture data as if it were real. Never publish anything a sandbox credential returns.