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.

RequestScopeWhat it does
GET /api/v1/listings?limit=50&cursor=listings:writeYour 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:writeAdds 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:writeWithdraws a live ad.
PUT /api/v1/listings/{stock_no}/photoslistings: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:readLeads 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:writeThe 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

FieldRequiredNotes
stock_no
Stock number
YesUnique for each bike in your yard. It is how we match a row to its ad next time.
make
Make
YesFor example Honda, Yamaha, Harley-Davidson.
model
Model
YesFor example CBR500R.
year
Year
YesThe model year, four digits.
price
Drive-away price
YesOne all-inclusive price in dollars (dealer ads must show the drive-away price).
condition
Condition
YesNew, demo, used, damaged (repairable write-off), statutory write-off or parts only.
variant
Variant
NoFor example ABS or SE.
odometer_km
Odometer (km)
NoWhole kilometres.
engine_cc
Engine size (cc)
NoEngine capacity in cc.
colour
Colour
No
category
Category
NoSport, naked, cruiser, touring, adventure, dirt, scooter and so on. Taken from the model when left out.
description
Description
NoPlain text. Leave the VIN out: it is never shown in an ad.
photo
Photo URLs
NoUp to 12 https:// links, in order: one per column, or several in one cell separated by | , or spaces.
rego_no
Registration number
NoThe plate number. Shown on the ad where the state requires it.
rego_status
Registered?
NoRegistered, unregistered, recreational or cannot be registered. Taken as registered when a plate is given.
lams
LAMS approved
NoYes or no.
vin
VIN
NoStored encrypted and never shown in an ad, a report or a download.
frame_no
Frame number
NoStored encrypted and never shown in an ad, a report or a download.
engine_no
Engine number
NoStored encrypted and never shown.
suburb
Suburb
NoWhere the bike is. Your dealership's suburb when left out.
postcode
Postcode
No
price_type
Price basis
NoLeave out, or "drive away". Prices plus government charges are not accepted.
writeoff_status
Written-off status (WOVR)
NoNot recorded, repairable, statutory or unknown. Needed for damaged stock.
writeoff_state
Written off in (state)
NoNSW, VIC, QLD, WA, SA, TAS, ACT or NT.
sold_as
Sold as
NoWhole, track only or parts only. Needed for damaged stock.
runs_and_rides
Runs and rides?
NoRuns and rides, runs but not rideable, does not run, or unknown. Needed for damaged stock.
damage_types
Damage
NoAny of: cosmetic, crash, bent frame, engine, mechanical, flood, fire, hail, stolen recovered, missing parts, project.
damage_description
Damage report
NoWhat is damaged, in plain words.
vin_plate_photo
VIN or compliance plate photo URL
NoNeeded for damaged stock. Never shown in the ad.
has_spare_key
Keys present
NoYes or no.

Answers you may get

  • 400 a request we cannot read; 401 a missing, unknown or revoked key; 403 a key without the scope, or a dealership that is not verified or has no Pro or Group plan; 404 not one of your ads or runs; 409 an ad in a state that does not allow it; 413 a body over 64 KB; 429 too many requests; 503 Bike 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.