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.
| Scope | What it does in the sandbox |
|---|---|
read:tests | List and read the fixture tests and the three fixture connections. |
read:certificates | Signed links to the anonymised specimen certificate PDF and the preview image. |
read:warranties | Signed links to the anonymised specimen warranty PDF and image, for fixtures whose warranty carries a document. |
manage:webhooks | Register 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 id | Name | Connection (platform_reference) |
|---|---|---|
990001 | BHC Sandbox Motors North | sandbox-north |
990002 | BHC Sandbox Motors North – Harrogate (a branch of 990001) | sandbox-north |
990003 | BHC Sandbox Motors South | sandbox-south |
990004 | BHC 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 id | VIN | Registration | Dealer | What it shows |
|---|---|---|---|---|
990000001 | BHCTESTVIN0000001 | ZZ23MGF | North | Final result, excellent; warranty ACTIVE, with the anonymised specimen warranty PDF and image, and the only illustrative warranty terms (see How it differs) |
990000002 | BHCTESTVIN0000002 | ZZ20KNR | North – Harrogate | Final result, good; MOT mileage reads higher than the test (discrepancy) |
990000003 | BHCTESTVIN0000003 | ZZ19NLF | South | Final result, fair; warranty INELIGIBLE (VEHICLE_NOT_SUPPORTED) |
990000004 | BHCTESTVIN0000004 | ZZ21RZE | North | Final result, poor, with an AVILOO finding (SOH_TOO_LOW, result WARNING) |
990000005 | BHCTESTVIN0000005 | ZZ21HDE | North – Harrogate | Provisional: SoH over 100% on a model in validation |
990000006 | BHCTESTVIN0000006 | ZZ24BYD | South | Final result on a model in validation (beta) |
990000007 | BHCTESTVIN0000007 | ZZ22PGT | North | Inconclusive: AVILOO reached no verdict (NO_RELAXED_PHASES) |
990000008 | none | none | North – Harrogate | Failed: the box read nothing from the car (DONGLE_NO_VIN_EXCEPTION) |
990000009 | BHCTESTVIN0000009 | ZZ18UNK | South | Failed: model not yet supported by AVILOO (make and model from the registration record) |
990000010 | BHCTESTVIN0000010 | ZZ23KEV | North | Pending: data acquisition started 10 minutes ago |
990000011 | BHCTESTVIN0000011 | ZZ22HIQ | North – Harrogate | Stalled: no result two days after starting |
990000012 | BHCTESTVIN0000012 | ZZ20VWG | South | Final result, tested 104 days ago: older than 90 days, so not publishable (TEST_OLDER_THAN_90_DAYS) |
990000013 | BHCTESTVIN0000013 | ZZ21TSL | North | Final result, but older than 90 days (stale) |
990000014 | BHCTESTVIN0000014 | ZZ19PLT | North – Harrogate | Plate transfer A: older test of one car under plate ZZ19PLT |
990000015 | BHCTESTVIN0000015 | ZZ19PLT | South | Plate 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 |
990000016 | BHCTESTVIN0000016 | ZZ22SKE | North | Retest, first try: inconclusive (MISSING_SIGNAL ten times, as real inconclusive tests carry it) |
990000017 | BHCTESTVIN0000016 | ZZ22SKE | North | Retest, second try: final result (same car as 16, recovered) |
990000018 | BHCTESTVIN0000018 | ZZ22PST | North – Harrogate | Warranty withdrawn after the test (UNAVAILABLE) |
990000019 | BHCTESTVIN0000019 | none | South | Irish import at a GB dealer, no registration recorded: findable by VIN only |
990000020 | BHCTESTVIN0000020 | ZZ20MOP | South | Plug-in hybrid (PHEV); MOT history from DVSA |
990000021 | BHCTESTVIN0000021 | ZZ21VXC | North | Certificate and preview never ready (always 409) |
990000022 | BHCTESTVIN0000022 | ZZ20NNV | South | Safety finding (CELL_VOLTAGE_SPREAD_CRITICALLY_HIGH); MOT history from DVSA |
990000023 | BHCTESTVIN0000023 | ZZ15NLE | North | Final result, poor, with no AVILOO warning |
990000024 | BHCTESTVIN0000024 | ZZ23RMG | North | Sold on, first dealer (North): same car as 25, an unrelated connection; tested four months earlier, so older than 90 days |
990000025 | BHCTESTVIN0000024 | ZZ23RMG | South | Sold on, second dealer (South): same car as 24. A lookup of its VIN with no dealer_id carries the warning MULTIPLE_DEALERS |
990000026 | BHCTESTVIN0000026 | ZZ24PEU | North | Retest burst, first try: failed (DONGLE_SIDE_TIMEOUT), superseded by 28 |
990000027 | BHCTESTVIN0000026 | ZZ24PEU | North | Retest burst, second try: final result, superseded by 28 a few minutes later |
990000028 | BHCTESTVIN0000026 | ZZ24PEU | North | Retest burst, third try: the car’s current test |
990000029 | BHCTESTVIN0000029 | ZZ23CPR | South | Failed: AVILOO does not recognise the VIN (make and model from the registration record) |
990000030 | none | none | North | Failed: no vehicle detected, box not connected or ignition off (DONGLE_NO_VEHICLE_EXCEPTION); no warranty state established |
990000031 | none | none | North – Harrogate | Failed: the test did not finish (INCOMPLETE) |
990000032 | BHCTESTVIN0000032 | ZZ24XPG | South | Failed: AVILOO has no model group for the car (UNKNOWN_MODEL_GROUP) |
990000033 | BHCTESTVIN0000033 | ZZ22FMM | North | Failed: AVILOO received the data but could not analyse it (EVALUATION_FAILED); warranty PENDING |
990000034 | BHCTESTVIN0000034 | ZZ22VWF | North – Harrogate | Warning result: current sensor (CURRENT_OUTSIDE_ACCEPTABLE_RANGE) |
990000035 | BHCTESTVIN0000035 | ZZ22CTN | South | Warning result: cell voltage spread (CELL_VOLTAGE_SPREAD_TOO_HIGH) |
990000036 | BHCTESTVIN0000036 | 231QX1001 | Ireland | Irish dealer: final result on an Irish plate; English copy withheld (REGION_NOT_REVIEWED) |
990000037 | BHCTESTVIN0000037 | 221QX207 | Ireland | Irish dealer: a second Irish car |
990000038 | BHCTESTVIN0000038 | 201QX4410 | North | Irish-registered car tested at a GB dealer |
990000039 | BHCTESTVIN0000039 | BZZ4410 | South | Northern Ireland style plate; MOT history from DVA NI |
990000040 | BHCTESTVIN0000040 | R100AZZ | North – Harrogate | Prefix-era private plate on a modern car; warranty ACTIVE, the only one whose created_at is filled, with no terms (see How it differs) |
990000041 | BHCTESTVIN0000041 | ZZ25KEV | North | New car (2025): vehicle record found, no MOT yet |
990000042 | BHCTESTVIN0000042 | ZZ26BYD | South | New car (2026): vehicle record found, no MOT yet |
990000043 | BHCTESTVIN0000043 | ZZ23VLV | South | Plug-in hybrid, provisional: SoH over 100% on a supported model |
990000044 | BHCTESTVIN0000044 | ZZ24VWI | North | Provisional on a supported model, with an ACTIVE warranty |
990000045 | BHCTESTVIN0000045 | ZZ22TYH | North – Harrogate | Self-charging hybrid (HEV) |
990000046 | BHCTESTVIN0000046 | ZZ23HSX | North | In progress at AVILOO: awaiting manual verification of a possible safety finding (BATTERY_TEMP_CRITICALLY_HIGH) |
990000047 | BHCTESTVIN0000047 | ZZ23KNE | South | Result under review (DISPUTED) |
990000048 | BHCTESTVIN0000048 | ZZ22MBQ | South | A good result, retested weeks later: this final result stays the car’s current test |
990000049 | BHCTESTVIN0000048 | ZZ22MBQ | South | The retest of 48: failed (DONGLE_SIDE_TIMEOUT). The car’s latest test, but 48 is still its current test |
990000050 | BHCTESTVIN0000050 | ZZ23CTB | North – Harrogate | Inconclusive 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"andSANDBOX_DATAin itswarnings, and every value in it is invented. Its provider’sstatusis 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
availabilityislive; it carriesSANDBOX_DATAtoo. - A sandbox check from the vehicle record provider (
vdg) is built from the fixture’s vehicle record and issandbox_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 advsacheck, markedsandbox_illustrativewithSANDBOX_DATA, and their passport’smotblock comes from it, with DVSA’s attribution and every test numbered, as in production. The test numbers start9999and are not DVSA’s. The cars with an MOT that keep their vehicle record’s history in the passport, often with blank test numbers, areBHCTESTVIN0000007,BHCTESTVIN0000014(its plate now belongs to another car, whose make DVSA’s copy carries),BHCTESTVIN0000034andBHCTESTVIN0000040. They, and every car too new for an MOT, list DVSA withreasonno_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 providervehicle_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.
| Car | Checks | What they show |
|---|---|---|
BHCTESTVIN0000001ZZ23MGF | Vehicle record provider, UK and Irish history check provider | A 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. |
BHCTESTVIN0000002ZZ20KNR | Vehicle record provider, UK history check provider A, UK history check provider B | Outstanding 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. |
BHCTESTVIN0000003ZZ19NLF | Vehicle record provider, UK and Irish history check provider, UK history check provider A | A 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. |
BHCTESTVIN0000004ZZ21RZE | Vehicle record provider, UK history check provider B | A stolen marker: stolen_police is found. |
BHCTESTVIN0000014ZZ19PLT | Vehicle record provider, UK history check provider B | A plate change: the car moved off ZZ19PLT, the plate fixture 990000015 carries now (plate_changes is found). |
BHCTESTVIN0000019no registration | Irish history check provider | An 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)
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
| Request | What comes back |
|---|---|
GET /v1/tests/990000002/valuation?adjustment_mode=percent | A 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_valuation | The 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¤cy=EUR | An 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=percent | A 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=percent | A 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 test | reason |
|---|---|
990000022 | SAFETY_FINDING: a safety finding on the test. |
990000023 | BELOW_70: the battery is below 70%. |
990000004 | AVILOO_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:
| Identifier | Shape | Why 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 Britain | ZZnnLLL, for example ZZ19PLT | No current-style plate starts ZZ. |
| Registration, Ireland | nnn-QX-n, for example 231-QX-1001 | QX is no Irish county or city code. |
| Registration, Northern Ireland style | LZZnnnn, for example BZZ4410 | ZZ is no Northern Ireland area code. |
| Registration, prefix era | LnnnLZZ, for example R100AZZ | ZZ 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
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
| Field | Type | Description |
|---|---|---|
event | string | Required. 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_id | integer | Required. 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_id | integer | Optional. One of your webhooks. Without it, every enabled webhook of yours subscribed to the event receives it. |
platform_reference | string | Optional, 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | The body is not a JSON object. |
| 400 | invalid_field | fixture_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. |
| 404 | not_found | The 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. |
| 422 | validation | An 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"inmeta. Production envelopes have noenvironmentkey. - 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_DATAin their ownwarningsarray, including an item that found nothing. - A test object never carries
SANDBOX_DATA: itswarningsare 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, itsBHCTESTVINVIN, itsSANDBOX-TEST-internal_referenceand its dealer name.
What is different
| Area | In 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 are | Always a platform credential, connected to three fixture dealers (North, with one branch; South; and Ireland). Pass dealer_id wherever a platform credential must. |
| Data | Fixed. 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. |
| Webhooks | Real: 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 settings | GET 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 limits | The 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 providers | Invented history checks from provenance providers production does not serve, marked sandbox_illustrative: see Providers in the sandbox. |
| Warranty | Every 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.