For dealers
Dealer API and lead webhook
Dealers on the Pro and Group plans can connect their own system to Bike Domain: keep ads in step with the yard, send photos, and read leads as they arrive.
Keys
A manager or the owner makes a key under API keys in the dealer console. The key starts with bd_live_ and is shown once: we keep only a fingerprint of it. Send it on every request as Authorization: Bearer followed by the key. A key may do one or both of:
listings:write: list, add, change and withdraw your ads, send their photos, and read the result of each change;leads:read: read your leads and their messages.
Each key may make 600 requests an hour; past that the answer is 429 with a Retry-After header. Every call is logged against the key. Revoke a key from the console and it stops at once. Keys stop working while the dealership has no Pro or Group plan, and start again when it does.
Endpoints
All answers are JSON. Times are ISO 8601.
| Request | Scope | What it does |
|---|---|---|
GET /api/v1/listings?limit=50&cursor= | listings:write | Your ads, newest first, 100 at most a page. Pass next_cursor back as cursor for the next page; status=active narrows the list. |
PUT /api/v1/listings/{stock_no} | listings:write | Adds or changes the ad with this stock number, through the same checks as a file import. A new ad starts as a draft and goes to our checks once its photos are in and your page is approved. A live ad takes changes to its price, odometer, colour, registration and description; other changes need a new ad. |
DELETE /api/v1/listings/{stock_no} | listings:write | Withdraws a live ad. |
PUT /api/v1/listings/{stock_no}/photos | listings:write | {"photos": [up to 12 https links in order]}, and vin_plate_photo for damaged stock. We fetch them in the background. Photos of a live ad do not change this way (a new photo is checked before it is shown). |
GET /api/v1/leads?since= | leads:read | Leads with activity after since, oldest first, with their messages. Pass next_since back as since, exactly as given, for the next page. has_more is true while another page is waiting; on the last page, keep next_since and send it on your next poll to get only the leads with newer activity. A page with no leads returns a null next_since: keep the since you sent. The buyer's email address is included only when they agreed to share it with you. |
GET /api/v1/runs/{id} | listings:write | The result of a change or an import: counts, errors and warnings. |
Adding or changing an ad
PUT /api/v1/listings/A1234
Authorization: Bearer bd_live_...
Content-Type: application/json
{
"make": "Honda",
"model": "CB500X",
"year": 2021,
"price": 8990,
"condition": "used",
"odometer_km": 12500,
"colour": "Red",
"rego_status": "registered",
"rego_no": "ABC123",
"description": "One owner, serviced by us, new tyres. Comes with the spare key and books.",
"photo": ["https://images.dealer.example/a1234-1.jpg", "https://images.dealer.example/a1234-2.jpg"]
}201 {"status": "created", "listing_id": 100512, "run_id": 88, "warnings": []}
202 {"status": "invalid", "run_id": 89, "errors": [{"field": "year", "code": "year_range", "message": "..."}], "warnings": []}An ad that fails the checks is answered 202 with an errors list, one entry per field, and nothing is saved. The VIN, frame number and engine number are stored encrypted, never shown in an ad, and never returned by the API.
Fields
| Field | Required | Notes |
|---|---|---|
stock_noStock number | Yes | Unique for each bike in your yard. It is how we match a row to its ad next time. |
makeMake | Yes | For example Honda, Yamaha, Harley-Davidson. |
modelModel | Yes | For example CBR500R. |
yearYear | Yes | The model year, four digits. |
priceDrive-away price | Yes | One all-inclusive price in dollars (dealer ads must show the drive-away price). |
conditionCondition | Yes | New, demo, used, damaged (repairable write-off), statutory write-off or parts only. |
variantVariant | No | For example ABS or SE. |
odometer_kmOdometer (km) | No | Whole kilometres. |
engine_ccEngine size (cc) | No | Engine capacity in cc. |
colourColour | No | |
categoryCategory | No | Sport, naked, cruiser, touring, adventure, dirt, scooter and so on. Taken from the model when left out. |
descriptionDescription | No | Plain text. Leave the VIN out: it is never shown in an ad. |
photoPhoto URLs | No | Up to 12 https:// links, in order: one per column, or several in one cell separated by | , or spaces. |
rego_noRegistration number | No | The plate number. Shown on the ad where the state requires it. |
rego_statusRegistered? | No | Registered, unregistered, recreational or cannot be registered. Taken as registered when a plate is given. |
lamsLAMS approved | No | Yes or no. |
vinVIN | No | Stored encrypted and never shown in an ad, a report or a download. |
frame_noFrame number | No | Stored encrypted and never shown in an ad, a report or a download. |
engine_noEngine number | No | Stored encrypted and never shown. |
suburbSuburb | No | Where the bike is. Your dealership's suburb when left out. |
postcodePostcode | No | |
price_typePrice basis | No | Leave out, or "drive away". Prices plus government charges are not accepted. |
writeoff_statusWritten-off status (WOVR) | No | Not recorded, repairable, statutory or unknown. Needed for damaged stock. |
writeoff_stateWritten off in (state) | No | NSW, VIC, QLD, WA, SA, TAS, ACT or NT. |
sold_asSold as | No | Whole, track only or parts only. Needed for damaged stock. |
runs_and_ridesRuns and rides? | No | Runs and rides, runs but not rideable, does not run, or unknown. Needed for damaged stock. |
damage_typesDamage | No | Any of: cosmetic, crash, bent frame, engine, mechanical, flood, fire, hail, stolen recovered, missing parts, project. |
damage_descriptionDamage report | No | What is damaged, in plain words. |
vin_plate_photoVIN or compliance plate photo URL | No | Needed for damaged stock. Never shown in the ad. |
has_spare_keyKeys present | No | Yes or no. |
Answers you may get
400a request we cannot read;401a missing, unknown or revoked key;403a key without the scope, or a dealership that is not verified or has no Pro or Group plan;404not one of your ads or runs;409an ad in a state that does not allow it;413a body over 64 KB;429too many requests;503Bike Domain is read-only for a moment (try again later).
Lead webhook
On the Pro and Group plans you can give us an https address under your dealership profile. We post each new lead there as JSON. If your address does not answer with a 2xx status we try again three times, after 1, 5 and 25 minutes. We never follow a redirect, and addresses on private or internal networks are refused.
POST (your address)
Content-Type: application/json
X-BikeDomain-Event: lead.created
X-BikeDomain-Delivery: 5521
X-BikeDomain-Signature: t=1790000000,v1=5f0c...
{
"event": "lead.created",
"id": "8d5e...",
"created_at": "2026-10-01T09:30:00.000Z",
"listing": {"id": 100512, "stock_no": "A1234", "title": "2021 Honda CB500X", "year": 2021,
"make": "Honda", "model": "CB500X", "price_cents": 899000, "url": "https://bikedomain.com.au/bike/..."},
"customer": {"name": "Sam", "phone": "+61400000000"},
"message": "Hi, is this bike still available?"
}Each post is signed with your webhook secret (shown once when you set the address; make a new one from your profile at any time). Check the X-BikeDomain-Signature header before you trust the body, and refuse one older than five minutes:
import { createHmac, timingSafeEqual } from 'node:crypto';
// header: the X-BikeDomain-Signature value, body: the raw request body as received
export function verify(secret, body, header, nowSeconds) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
if (!m || Math.abs(nowSeconds - Number(m[1])) > 300) return false;
const want = createHmac('sha256', secret).update(m[1] + '.' + body).digest();
const got = Buffer.from(m[2], 'hex');
return got.length === want.length && timingSafeEqual(got, want);
}ADF lead emails
Any dealer can also have each new lead emailed to their dealer system in the ADF 1.0 format, one lead per email. Set the address under your dealership profile and send a test lead from there. The buyer's email address is in it only when they agreed to share it.
