← API v2 Overview

Vehicles

Look up vehicle data, create stock records, update advert and stock fields, manage media, review market data, and generate advert copy.

The Vehicle Object

Generated from the OpenAPI schema. Always matches the live API.

Fields (168)
AttributeTypeRequiredDescriptionExample
idinteger-84213
tagstring-AB12CDEF
countrystring-UK
registrationstring or null-EO68NRJ
urlstring-bmw-3-series-320i-m-sport-saloon-4dr-auto
url_fullstring-https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/
typeenum-Vehicle stock type, output as a slug. On create accepts either the slug (e.g. in-stock) or the stored key (s/t/u/r/a). See GET /reference/vehicle-types.in-stock
createdinteger-1779974135
updatedinteger-1781303332
statusobject-
status.idinteger-Type-independent status code (1 draft/initial, 2 active, 3 sold/closed, 4 deleted).2
status.nameenum-Type-aware status slug. For stock vehicles, id 2 reads as "reserved" when the vehicle has a reservation and id 3 reads as "complete" once handed over.for-sale
status.labelstring-Type-aware human-readable status label.For Sale
ownerstring-Staff user the vehicle is owned by, if assigned.
parentinteger or null-Parent vehicle id for variant/linked records, or null.
dataobject-
data.vehicleobject-
data.vehicle.typeenum-Vehicle class. Case-sensitive; use the canonical capitalised value (Car, Van, Bike, Truck, Crossover, Motorhome, Caravan, Farm, Plant) as returned by /reference vehicle taxonomy; an unrecognised class is rejected on this field. Some fields apply only to certain classes (e.g. wheelbase to vans).Car
data.vehicle.makestring-Manufacturer / make. Send the manufacturer name; it is matched (case-insensitively) against the make taxonomy for the vehicle class. A value with no match is accepted and stored as a custom make. Read back as the value you sent. See /reference vehicle taxonomy.BMW
data.vehicle.modelstring-Model name. Matched against the model taxonomy for the chosen make; a value with no match (or any model under a custom make) is accepted and stored as a custom model.3 Series
data.vehicle.generationstring-Model generation. Matched against the generation taxonomy for the chosen make/model; an unmatched value is accepted and stored as custom.Saloon (2019 - 2023)
data.vehicle.derivativestring-Manufacturer derivative / full spec name. Matched against the derivative taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.320i M Sport 4dr Auto
data.vehicle.trimstring-Trim level. Matched against the trim taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.M Sport
data.vehicle.engine_sizestring-Engine size in litres. Matched against the engine-size taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.2.0
data.vehicle.bodystring-Body style.Saloon
data.vehicle.colourstring-Paint colour.Black
data.vehicle.colour_namestring-Manufacturer colour name.Sapphire Black
data.vehicle.fuelstring-Fuel type.Petrol
data.vehicle.transmissionstring-Transmission type.Automatic
data.vehicle.drivetrainstring-Drivetrain. Applies to cars and bikes.RWD
data.vehicle.seatsinteger or null-Number of seats.5
data.vehicle.doorsinteger or null-Number of doors.5
data.vehicle.wheelbasestring-Wheelbase. Applies to vans.LWB
data.vehicle.cab_typestring-Cab type. Applies to vans and trucks.Double Cab
data.vehicle.mileageinteger or null-Odometer reading in miles.38450
data.vehicle.registeredstring (date) or null-First registration date (YYYY-MM-DD).2020-03-01
data.vehicle.categorystring-Vehicle category. Applies to farm, plant and trucks.Tractor
data.vehicle.driver_positionstring-Driver position (steering side).RHD
data.vehicle.interior_upholsterystring-Interior upholstery material.Leather
data.vehicle.interior_colourstring-Interior colour.Black
data.vehicle.exterior_finishstring-Exterior paint finish.Metallic
data.vehicle.groupstring-Vehicle grouping label (free text, for your own categorisation).Demo Fleet
data.vehicle.hourstring-
data.vehicle.bedroom_layoutstring or null-Bedroom layout. Applies to caravans and motorhomes.Fixed island bed
data.vehicle.end_layoutstring or null-End layout. Applies to caravans and motorhomes.End washroom
data.vehicle.bedroominteger or null-Number of bedrooms. Applies to caravans and motorhomes.2
data.vehicle.berthinteger or null-Number of berths. Applies to caravans and motorhomes.4
data.vehicle.seat_beltinteger or null-Number of belted seats. Applies to caravans and motorhomes.4
data.vehicle.wheelchairstring or null-Wheelchair accessible (Yes/No). Applies to caravans and motorhomes.No
data.optionobject-
data.option.option_customarray of string-Custom (dealer-added) option names.["12 Month Warranty"]
data.option.attentionstring-Short attention grabber shown on listings.Full Service History
data.option.descriptionstring-Plain-text advert description.One owner from new, full BMW service history.
data.option.websitestring-HTML advert body shown on the website.<p>One owner from new.</p>
data.option.featureobject-
data.historyobject-
data.history.previous_ownerinteger or null-Number of previous owners.1
data.history.keysinteger or null-Number of keys supplied.2
data.history.v5string-Whether a V5C logbook is present (Yes/No).Yes
data.history.yearinteger or null-Year of manufacture.2020
data.history.conditionstring-Overall condition.Used
data.history.condition_interiorstring-Interior condition.Good
data.history.condition_exteriorstring-Exterior condition.Good
data.history.condition_tyrestring-Tyre condition.Good
data.history.service_historystring-Service history type.Full
data.history.service_laststring (date) or null-Date of last service (YYYY-MM-DD).2025-09-01
data.history.service_milesinteger or null-Mileage at last service.36000
data.history.mot_expirystring (date) or null-MOT expiry date (YYYY-MM-DD).2026-03-01
data.history.mot_yearstring-Whether 12 months' MOT is included (Yes/No).Yes
data.history.mot_insurancestring-Whether MOT insurance is included (Yes/No).No
data.history.warranty_expirystring (date) or null-Warranty expiry date (YYYY-MM-DD).2026-03-01
data.history.warranty_monthinteger or null-Remaining warranty in months.12
data.history.warranty_battery_monthinteger or null-Remaining battery warranty in months (EVs).60
data.history.service_notestring-Free-text service history note.Serviced at 12k and 24k miles.
data.stockobject-
data.stock.referencestring-Free-text stock reference.REF-1024
data.stock.numberstring-Stock number.STK1024
data.stock.locationstring-Business location. Accepts a location id on write; published as the location name.Main Forecourt
data.stock.notesstring-Internal notes (not shown publicly).Awaiting valet.
data.stock.vinstring-Vehicle identification number (uppercased alphanumeric).WBA8E9105HK000000
data.stock.engine_numberstring-Engine number.B47D20A
data.stock.key_numberstring-Key/security number.K12345
data.stock.originstring-Where the vehicle was sourced from.Part Exchange
data.stock.vatstring-VAT scheme display value (see vat_scheme for the normalised value).Inc VAT
data.stock.vat_pricingstring-How VAT is reflected in the price.Inc. VAT
data.stock.due_in_datestring (date) or null-Date the vehicle is due into stock (YYYY-MM-DD).2026-06-20
data.stock.forecourt_datestring (date) or null-Date the vehicle went on the forecourt (YYYY-MM-DD).2026-06-12
data.stock.price_websitestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.12500.00
data.stock.price_channelstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.13495.00
data.stock.price_reservestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.12000.00
data.stock.price_auction_startstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.10000.00
data.stock.price_auction_reservestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.11000.00
data.stock.price_auction_buy_nowstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.13000.00
data.stock.price_auction_durationstring-Auction duration.7 Days
data.stock.price_auction_dealerway_typestring-Dealerway auction type. Only available when the dealerway channel is enabled. One of: Live Auction, Auction with Buy Now, Buy Now.Buy Now
data.stock.price_rrpstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.24995.00
data.stock.price_poaboolean-
data.stock.funding_providerstring-Funding/finance provider name. Requires vehicle-pricing:read to read.Close Brothers
data.stock.funding_provider_idinteger or null-Funding provider contact id. Requires vehicle-pricing:read to read.42
data.stock.funding_provider_totalstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.8000.00
data.stock.stock_quantityinteger or null-Quantity available (for new/multi-stock vehicles).1
data.stock.stock_variationobject-Stock variation data (new vehicle configurator variants).
data.stock.purchase_datestring (date) or null-Purchase date (read-only; set via the purchase workflow). Requires vehicle-pricing:read.2026-01-15
data.stock.purchase_invoicestring-PINV-2048
data.stock.purchase_supplierstring-BCA Auction
data.stock.purchase_supplier_idinteger or null-Supplier contact id the vehicle was purchased from (read-only; set via the purchase workflow). Requires vehicle-pricing:read.30418
data.stock.purchase_supplier_invoicestring-BCA-99812
data.stock.purchase_pricestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.9000.00
data.stock.purchase_price_vatstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.0.00
data.stock.purchase_price_totalstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.9000.00
data.stock.purchase_coststring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.450.00
data.stock.purchase_cost_vatstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.90.00
data.stock.purchase_cost_totalstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.540.00
data.stock.purchase_valuestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.9450.00
data.stock.purchase_value_vatstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.90.00
data.stock.purchase_value_totalstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.9540.00
data.stock.purchase_cost_dataarray of object-Additional purchase costs (transport, valeting, repairs, ...). Writing rows recomputes the read-only purchase_cost/value totals. Read requires vehicle-pricing:read.
data.specobject-
data.spec.performanceobject-top_speed, zero_sixty.{"top_speed":155,"zero_sixty":5.8}
data.spec.engineobject-make, cylinders, bhp, ps, nm, gears...{"make":"BMW","cylinders":4,"capacity":1998,"bhp":181,"ps":184,"nm":300,"gears":8}
data.spec.batteryobject-charge_time, range, kwh, health.{"range":239,"kwh":58,"charge_time":"8h 15m","health":100}
data.spec.otherobject-axles, country, sector.{"axles":2,"country":"GB","sector":"Retail"}
data.spec.insuranceobject-group, code.{"group":"21E","code":"21E"}
data.spec.fuelobject-mpg_*, emission_*, ulez, caz.{"mpg_combined":48.7,"emission_co2":132,"ulez":true,"caz":true}
data.spec.sizeobject-length, width, height, weights, boot.{"length":4709,"width":2073,"height":1442,"wheelbase":2851,"kerb_weight":1545,"boot_seats_up":480}
data.appraisalobject-
data.appraisal.detailsobject-
data.appraisal.details.customer_idstring-Linked contact id - the value the GET /vehicles appraisal_contact filter matches. Empty when the appraisal is not linked to a contact.4471
data.appraisal.details.customerstring-Linked contact name, captured when the link was made.Ada Buyer
data.appraisal.calculationobject-
data.appraisal.calculation.offerstring-The working offer figure from the appraisal calculator; the confirmed figure lives in confirm.offer.9500.00
data.appraisal.calculation.finance_settlementstring-Outstanding finance on the vehicle, as recorded on the appraisal.2000.00
data.appraisal.confirmobject-
data.appraisal.confirm.offerstring-The confirmed offer made to the customer.9500.00
data.appraisal.confirm.expirystring-Date the confirmed offer is good until (YYYY-MM-DD), empty for no expiry.2026-09-06
data.appraisal.confirm.appraised_atinteger-Unix timestamp the offer was confirmed, 0 before confirmation.1756137600
data.appraisal.confirm.agreed_amountstring-The figure the vehicle was actually taken in at, set when the appraisal is accepted.9250.00
data.appraisal.confirm.decisionstring-accepted or rejected once decided, empty while awaiting a decision.accepted
data.appraisal.confirm.decision_atinteger-Unix timestamp of the decision, 0 before one.1756224000
data.appraisal.confirm.stock_idstring-The stock vehicle created when the appraisal was accepted, empty before acceptance.18342
data.appraisal.confirm.stock_tagstring-The created stock vehicle's tag.a1b2c3d4
data.lookupobject-
data.lookup.dvlaobject-{"make":"BMW","colour":"BLACK","fuel_type":"PETROL","year_of_manufacture":2020,"tax_status":"Taxed"}
data.lookup.dvsaobject-{"mot_tests":[{"completed_date":"2025-03-01","test_result":"PASSED","odometer_value":36000}]}
data.lookup.checkobject-{"stolen":false,"finance":false,"written_off":false,"previous_keepers":1}
data.tagarray of object-[{"name":"Service","checked":false,"colour":"primary","type":"check"}]
data.financeobject-
data.finance.example_monthlystring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.507.75
data.finance.exampleobject-
data.finance.example.cash_pricestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.20000.00
data.finance.example.total_depositstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.2000.00
data.finance.example.total_creditstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.18000.00
data.finance.example.first_paymentstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.507.75
data.finance.example.monthly_paymentstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.507.75
data.finance.example.total_monthly_paymentsinteger or null-Number of monthly payments.25
data.finance.example.final_paymentstring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.7856.00
data.finance.example.terminteger or null-Agreement duration in months.27
data.finance.example.admin_feestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.0.00
data.finance.example.option_purchase_feestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.10.00
data.finance.example.interest_chargestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.3057.50
data.finance.example.total_payablestring (2dp decimal) or null-Monetary amount as a fixed 2dp decimal string.23057.50
data.finance.example.fixed_interest_ratenumber or null-Annual fixed interest rate (percent).10.36
data.finance.example.representative_aprnumber or null-Representative APR (percent).10.9
mediaobject-
media.photoarray of string-Photo media item ids, in display order.["m7Yk2p9q","r3Tn8w1z"]
media.videoarray of string-Video media item ids.["v9Lp4m2x"]
media.youtubearray of string-YouTube video ids.["dQw4w9WgXcQ"]
media.photo_spinarray of string-360-spin frame media item ids.["s5Qw8r3t"]
Example object
{
    "id": 84213,
    "tag": "AB12CDEF",
    "country": "UK",
    "registration": "EO68NRJ",
    "url": "bmw-3-series-320i-m-sport-saloon-4dr-auto",
    "url_full": "https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/",
    "type": "in-stock",
    "created": 1779974135,
    "updated": 1781303332,
    "status": {
        "id": 2,
        "name": "for-sale",
        "label": "For Sale"
    },
    "owner": "",
    "parent": 0,
    "data": {
        "vehicle": {
            "type": "Car",
            "make": "BMW",
            "model": "3 Series",
            "generation": "Saloon (2019 - 2023)",
            "derivative": "320i M Sport 4dr Auto",
            "trim": "M Sport",
            "engine_size": "2.0",
            "body": "Saloon",
            "colour": "Black",
            "colour_name": "Sapphire Black",
            "fuel": "Petrol",
            "transmission": "Automatic",
            "drivetrain": "RWD",
            "seats": 5,
            "doors": 5,
            "wheelbase": "LWB",
            "cab_type": "Double Cab",
            "mileage": 38450,
            "registered": "2020-03-01",
            "category": "Tractor",
            "driver_position": "RHD",
            "interior_upholstery": "Leather",
            "interior_colour": "Black",
            "exterior_finish": "Metallic",
            "group": "Demo Fleet",
            "hour": "",
            "bedroom_layout": "Fixed island bed",
            "end_layout": "End washroom",
            "bedroom": 2,
            "berth": 4,
            "seat_belt": 4,
            "wheelchair": "No"
        },
        "option": {
            "option_custom": [
                "12 Month Warranty"
            ],
            "attention": "Full Service History",
            "description": "One owner from new, full BMW service history.",
            "website": "<p>One owner from new.</p>",
            "feature": {}
        },
        "history": {
            "previous_owner": 1,
            "keys": 2,
            "v5": "Yes",
            "year": 2020,
            "condition": "Used",
            "condition_interior": "Good",
            "condition_exterior": "Good",
            "condition_tyre": "Good",
            "service_history": "Full",
            "service_last": "2025-09-01",
            "service_miles": 36000,
            "mot_expiry": "2026-03-01",
            "mot_year": "Yes",
            "mot_insurance": "No",
            "warranty_expiry": "2026-03-01",
            "warranty_month": 12,
            "warranty_battery_month": 60,
            "service_note": "Serviced at 12k and 24k miles."
        },
        "stock": {
            "reference": "REF-1024",
            "number": "STK1024",
            "location": "Main Forecourt",
            "notes": "Awaiting valet.",
            "vin": "WBA8E9105HK000000",
            "engine_number": "B47D20A",
            "key_number": "K12345",
            "origin": "Part Exchange",
            "vat": "Inc VAT",
            "vat_pricing": "Inc. VAT",
            "due_in_date": "2026-06-20",
            "forecourt_date": "2026-06-12",
            "price_website": "12500.00",
            "price_channel": "13495.00",
            "price_reserve": "12000.00",
            "price_auction_start": "10000.00",
            "price_auction_reserve": "11000.00",
            "price_auction_buy_now": "13000.00",
            "price_auction_duration": "7 Days",
            "price_auction_dealerway_type": "Buy Now",
            "price_rrp": "24995.00",
            "price_poa": false,
            "funding_provider": "Close Brothers",
            "funding_provider_id": 42,
            "funding_provider_total": "8000.00",
            "stock_quantity": 1,
            "stock_variation": {},
            "purchase_date": "2026-01-15",
            "purchase_invoice": "PINV-2048",
            "purchase_supplier": "BCA Auction",
            "purchase_supplier_id": 30418,
            "purchase_supplier_invoice": "BCA-99812",
            "purchase_price": "9000.00",
            "purchase_price_vat": "0.00",
            "purchase_price_total": "9000.00",
            "purchase_cost": "450.00",
            "purchase_cost_vat": "90.00",
            "purchase_cost_total": "540.00",
            "purchase_value": "9450.00",
            "purchase_value_vat": "90.00",
            "purchase_value_total": "9540.00",
            "purchase_cost_data": [
                {
                    "type": "",
                    "supplier": "",
                    "cost": "0.00",
                    "vat": "0.00",
                    "invoice": "",
                    "reference": "",
                    "date": "2026-01-01",
                    "id": "",
                    "total": "0.00"
                }
            ]
        },
        "spec": {
            "performance": {
                "top_speed": 155,
                "zero_sixty": 5.8
            },
            "engine": {
                "make": "BMW",
                "cylinders": 4,
                "capacity": 1998,
                "bhp": 181,
                "ps": 184,
                "nm": 300,
                "gears": 8
            },
            "battery": {
                "range": 239,
                "kwh": 58,
                "charge_time": "8h 15m",
                "health": 100
            },
            "other": {
                "axles": 2,
                "country": "GB",
                "sector": "Retail"
            },
            "insurance": {
                "group": "21E",
                "code": "21E"
            },
            "fuel": {
                "mpg_combined": 48.7,
                "emission_co2": 132,
                "ulez": true,
                "caz": true
            },
            "size": {
                "length": 4709,
                "width": 2073,
                "height": 1442,
                "wheelbase": 2851,
                "kerb_weight": 1545,
                "boot_seats_up": 480
            }
        },
        "appraisal": {
            "details": {
                "customer_id": "4471",
                "customer": "Ada Buyer"
            },
            "calculation": {
                "offer": "9500.00",
                "finance_settlement": "2000.00"
            },
            "confirm": {
                "offer": "9500.00",
                "expiry": "2026-09-06",
                "appraised_at": 1756137600,
                "agreed_amount": "9250.00",
                "decision": "accepted",
                "decision_at": 1756224000,
                "stock_id": "18342",
                "stock_tag": "a1b2c3d4"
            }
        },
        "lookup": {
            "dvla": {
                "make": "BMW",
                "colour": "BLACK",
                "fuel_type": "PETROL",
                "year_of_manufacture": 2020,
                "tax_status": "Taxed"
            },
            "dvsa": {
                "mot_tests": [
                    {
                        "completed_date": "2025-03-01",
                        "test_result": "PASSED",
                        "odometer_value": 36000
                    }
                ]
            },
            "check": {
                "stolen": false,
                "finance": false,
                "written_off": false,
                "previous_keepers": 1
            }
        },
        "tag": [
            {
                "name": "Service",
                "checked": false,
                "colour": "primary",
                "type": "check"
            }
        ],
        "finance": {
            "example_monthly": "507.75",
            "example": {
                "cash_price": "20000.00",
                "total_deposit": "2000.00",
                "total_credit": "18000.00",
                "first_payment": "507.75",
                "monthly_payment": "507.75",
                "total_monthly_payments": 25,
                "final_payment": "7856.00",
                "term": 27,
                "admin_fee": "0.00",
                "option_purchase_fee": "10.00",
                "interest_charge": "3057.50",
                "total_payable": "23057.50",
                "fixed_interest_rate": 10.36,
                "representative_apr": 10.9
            }
        }
    },
    "media": {
        "photo": [
            "m7Yk2p9q",
            "r3Tn8w1z"
        ],
        "video": [
            "v9Lp4m2x"
        ],
        "youtube": [
            "dQw4w9WgXcQ"
        ],
        "photo_spin": [
            "s5Qw8r3t"
        ]
    }
}

Endpoints

GET List Vehicles

GET /2.0/vehicles · scope vehicles:read

List vehicles with pagination and optional filters.

Parameters (62)
ParameterInTypeRequiredDescriptionExample
pagequeryinteger-Page number, starting at 1 (offset pagination).
per_pagequeryinteger-Results per page (maximum 500).
viewqueryenum-Response detail: "simple" for a compact object or "full" for the complete object.
statusqueryenum-Filter by lifecycle status (or the code 1-4). Filters match the underlying status code, which is broader than the type-aware name a vehicle reads back: sold (3) includes handed-over vehicles that read back as complete, and for-sale (2) includes vehicles that read back as reserved.for-sale
typequeryenum-Filter by stock type: s (stock), t (template), u (used/booked-in), r (courtesy/loan).s
registrationquerystring-Filter by registration. Exact match, or use % for wildcard matching (minimum 3 characters).AB12CDE
reserve_contactqueryinteger-Filter to vehicles reserved by this contact id.
appraisal_contactqueryinteger-Filter to appraisals raised for this contact id (pair with type=appraisal).
sold_contactqueryinteger-Filter to vehicles sold to this contact id.
ownerquerystring-Filter by owner.
parentqueryinteger-Filter by parent.
countryquerystring-Filter by country.
tagquerystring-Filter by tag. Supports wildcards (%) with the search:wildcard scope.
makequerystring-Exact match, or use % for wildcard matching (minimum 3 characters).BMW
modelquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).3 Series
generationquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
derivativequerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
trimquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
fuelquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
transmissionquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
drivetrainquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
bodyquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
colourquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
groupquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
vinquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
referencequerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
numberquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
seatsquerystring-Exact match, or a two-element array [from, to] for a range (e.g. seats[]=2&seats[]=5). An empty bound is open-ended.
doorsquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
mileagequerystring-Exact match, or a two-element array [from, to] for a range (e.g. mileage[]=10000&mileage[]=50000). An empty bound is open-ended.
yearquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
registeredquerystring-Exact match (YYYY-MM-DD), or a two-element array [from, to] for a range (e.g. registered[]=2020-01-01&registered[]=2022-12-31). An empty bound is open-ended.
price_websitequerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
price_channelquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
identifierquerystring-Registration, VIN or stock number. Exact match, or use % for wildcard matching (minimum 3 characters).AB12CDE
engine_sizequerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
hourquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
categoryquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
conditionquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
bedroom_layoutquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
end_layoutquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
bedroomquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
berthquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
wheelchairquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
locationquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
engine_numberquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
chassisquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
key_numberquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
vatquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
featuredquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
accelerationquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
battery_rangequerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
battery_healthquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
ulezquerystring-Exact match, or use % for wildcard matching (minimum 3 characters).
mpgquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
weight_kerbquerystring-Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
reservedqueryinteger-1 if the vehicle is reserved (data.reserve set), 0 otherwise.
sold_completequeryinteger-1 if the sale is complete (data.sold.complete set), 0 otherwise.
createdquerystring-Unix timestamp exact match, or a two-element array [from, to] for a range (e.g. created[]=1704067200&created[]=1735689600). An empty bound is open-ended.
updatedquerystring-Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended.
cursorquerystring-Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKPaginated vehicles

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": 84213,
            "tag": "AB12CDEF",
            "country": "UK",
            "registration": "EO68NRJ",
            "url": "bmw-3-series-320i-m-sport-saloon-4dr-auto",
            "url_full": "https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/",
            "type": "in-stock",
            "created": 1779974135,
            "updated": 1781303332,
            "status": {
                "id": 2,
                "name": "for-sale",
                "label": "For Sale"
            },
            "owner": "",
            "parent": 0,
            "data": {
                "vehicle": {
                    "type": "Car",
                    "make": "BMW",
                    "model": "3 Series",
                    "generation": "Saloon (2019 - 2023)",
                    "derivative": "320i M Sport 4dr Auto",
                    "trim": "M Sport",
                    "engine_size": "2.0",
                    "body": "Saloon",
                    "colour": "Black",
                    "colour_name": "Sapphire Black",
                    "fuel": "Petrol",
                    "transmission": "Automatic",
                    "drivetrain": "RWD",
                    "seats": 5,
                    "doors": 5,
                    "wheelbase": "LWB",
                    "cab_type": "Double Cab",
                    "mileage": 38450,
                    "registered": "2020-03-01",
                    "category": "Tractor",
                    "driver_position": "RHD",
                    "interior_upholstery": "Leather",
                    "interior_colour": "Black",
                    "exterior_finish": "Metallic",
                    "group": "Demo Fleet",
                    "hour": "",
                    "bedroom_layout": "Fixed island bed",
                    "end_layout": "End washroom",
                    "bedroom": 2,
                    "berth": 4,
                    "seat_belt": 4,
                    "wheelchair": "No"
                },
                "option": {
                    "option_custom": [
                        "12 Month Warranty"
                    ],
                    "attention": "Full Service History",
                    "description": "One owner from new, full BMW service history.",
                    "website": "<p>One owner from new.</p>",
                    "feature": {}
                },
                "history": {
                    "previous_owner": 1,
                    "keys": 2,
                    "v5": "Yes",
                    "year": 2020,
                    "condition": "Used",
                    "condition_interior": "Good",
                    "condition_exterior": "Good",
                    "condition_tyre": "Good",
                    "service_history": "Full",
                    "service_last": "2025-09-01",
                    "service_miles": 36000,
                    "mot_expiry": "2026-03-01",
                    "mot_year": "Yes",
                    "mot_insurance": "No",
                    "warranty_expiry": "2026-03-01",
                    "warranty_month": 12,
                    "warranty_battery_month": 60,
                    "service_note": "Serviced at 12k and 24k miles."
                },
                "stock": {
                    "reference": "REF-1024",
                    "number": "STK1024",
                    "location": "Main Forecourt",
                    "notes": "Awaiting valet.",
                    "vin": "WBA8E9105HK000000",
                    "engine_number": "B47D20A",
                    "key_number": "K12345",
                    "origin": "Part Exchange",
                    "vat": "Inc VAT",
                    "vat_pricing": "Inc. VAT",
                    "due_in_date": "2026-06-20",
                    "forecourt_date": "2026-06-12",
                    "price_website": "12500.00",
                    "price_channel": "13495.00",
                    "price_reserve": "12000.00",
                    "price_auction_start": "10000.00",
                    "price_auction_reserve": "11000.00",
                    "price_auction_buy_now": "13000.00",
                    "price_auction_duration": "7 Days",
                    "price_auction_dealerway_type": "Buy Now",
                    "price_rrp": "24995.00",
                    "price_poa": false,
                    "funding_provider": "Close Brothers",
                    "funding_provider_id": 42,
                    "funding_provider_total": "8000.00",
                    "stock_quantity": 1,
                    "stock_variation": {},
                    "purchase_date": "2026-01-15",
                    "purchase_invoice": "PINV-2048",
                    "purchase_supplier": "BCA Auction",
                    "purchase_supplier_id": 30418,
                    "purchase_supplier_invoice": "BCA-99812",
                    "purchase_price": "9000.00",
                    "purchase_price_vat": "0.00",
                    "purchase_price_total": "9000.00",
                    "purchase_cost": "450.00",
                    "purchase_cost_vat": "90.00",
                    "purchase_cost_total": "540.00",
                    "purchase_value": "9450.00",
                    "purchase_value_vat": "90.00",
                    "purchase_value_total": "9540.00",
                    "purchase_cost_data": [
                        {
                            "type": "",
                            "supplier": "",
                            "cost": "0.00",
                            "vat": "0.00",
                            "invoice": "",
                            "reference": "",
                            "date": "2026-01-01",
                            "id": "",
                            "total": "0.00"
                        }
                    ]
                },
                "spec": {
                    "performance": {
                        "top_speed": 155,
                        "zero_sixty": 5.8
                    },
                    "engine": {
                        "make": "BMW",
                        "cylinders": 4,
                        "capacity": 1998,
                        "bhp": 181,
                        "ps": 184,
                        "nm": 300,
                        "gears": 8
                    },
                    "battery": {
                        "range": 239,
                        "kwh": 58,
                        "charge_time": "8h 15m",
                        "health": 100
                    },
                    "other": {
                        "axles": 2,
                        "country": "GB",
                        "sector": "Retail"
                    },
                    "insurance": {
                        "group": "21E",
                        "code": "21E"
                    },
                    "fuel": {
                        "mpg_combined": 48.7,
                        "emission_co2": 132,
                        "ulez": true,
                        "caz": true
                    },
                    "size": {
                        "length": 4709,
                        "width": 2073,
                        "height": 1442,
                        "wheelbase": 2851,
                        "kerb_weight": 1545,
                        "boot_seats_up": 480
                    }
                },
                "appraisal": {
                    "details": {
                        "customer_id": "4471",
                        "customer": "Ada Buyer"
                    },
                    "calculation": {
                        "offer": "9500.00",
                        "finance_settlement": "2000.00"
                    },
                    "confirm": {
                        "offer": "9500.00",
                        "expiry": "2026-09-06",
                        "appraised_at": 1756137600,
                        "agreed_amount": "9250.00",
                        "decision": "accepted",
                        "decision_at": 1756224000,
                        "stock_id": "18342",
                        "stock_tag": "a1b2c3d4"
                    }
                },
                "lookup": {
                    "dvla": {
                        "make": "BMW",
                        "colour": "BLACK",
                        "fuel_type": "PETROL",
                        "year_of_manufacture": 2020,
                        "tax_status": "Taxed"
                    },
                    "dvsa": {
                        "mot_tests": [
                            {
                                "completed_date": "2025-03-01",
                                "test_result": "PASSED",
                                "odometer_value": 36000
                            }
                        ]
                    },
                    "check": {
                        "stolen": false,
                        "finance": false,
                        "written_off": false,
                        "previous_keepers": 1
                    }
                },
                "tag": [
                    {
                        "name": "Service",
                        "checked": false,
                        "colour": "primary",
                        "type": "check"
                    }
                ],
                "finance": {
                    "example_monthly": "507.75",
                    "example": {
                        "cash_price": "20000.00",
                        "total_deposit": "2000.00",
                        "total_credit": "18000.00",
                        "first_payment": "507.75",
                        "monthly_payment": "507.75",
                        "total_monthly_payments": 25,
                        "final_payment": "7856.00",
                        "term": 27,
                        "admin_fee": "0.00",
                        "option_purchase_fee": "10.00",
                        "interest_charge": "3057.50",
                        "total_payable": "23057.50",
                        "fixed_interest_rate": 10.36,
                        "representative_apr": 10.9
                    }
                }
            },
            "media": {
                "photo": [
                    "m7Yk2p9q",
                    "r3Tn8w1z"
                ],
                "video": [
                    "v9Lp4m2x"
                ],
                "youtube": [
                    "dQw4w9WgXcQ"
                ],
                "photo_spin": [
                    "s5Qw8r3t"
                ]
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}

POST Create Vehicle

POST /2.0/vehicles · scope vehicles:write

Create a draft vehicle from lookup or supplied vehicle data.

Request body
AttributeTypeRequiredDescriptionExample
countrystring-Country code the vehicle belongs to (e.g. UK; GB is treated as UK). Defaults to the business country.UK
registrationstring-Vehicle registration number (case-insensitive; spaces ignored). Optional for a draft.EO68NRJ
statusenum-Initial status. Accepts a numeric code (1-4), the default slug (draft/for-sale/sold/deleted) or any type-aware slug. Defaults to draft.draft
typeenum-Vehicle stock type. Accepts the slug (in-stock/to-order/customer/courtesy/appraisal) or the stored key (s/t/u/r/a). Defaults to in-stock.in-stock
dataobject-Writable vehicle data, grouped by section. Only the fields listed here are accepted; unknown fields are rejected.
data.vehicleobject-
data.vehicle.typestring-Vehicle class. Case-sensitive; use the canonical capitalised value (Car, Van, Bike, Truck, Crossover, Motorhome, Caravan, Farm, Plant) as returned by /reference vehicle taxonomy; an unrecognised class is rejected on this field. Some fields apply only to certain classes (e.g. wheelbase to vans).Car
data.vehicle.makestring-Manufacturer / make. Send the manufacturer name; it is matched (case-insensitively) against the make taxonomy for the vehicle class. A value with no match is accepted and stored as a custom make. Read back as the value you sent. See /reference vehicle taxonomy.BMW
data.vehicle.modelstring-Model name. Matched against the model taxonomy for the chosen make; a value with no match (or any model under a custom make) is accepted and stored as a custom model.3 Series
data.vehicle.generationstring-Model generation. Matched against the generation taxonomy for the chosen make/model; an unmatched value is accepted and stored as custom.Saloon (2019 - 2023)
data.vehicle.derivativestring-Manufacturer derivative / full spec name. Matched against the derivative taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.320i M Sport 4dr Auto
data.vehicle.trimstring-Trim level. Matched against the trim taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.M Sport
data.vehicle.engine_sizestring-Engine size in litres. Matched against the engine-size taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.2.0
data.vehicle.bodystring-Body style. Value is validated against the configured option list.Saloon
data.vehicle.colourstring-Paint colour. Value is validated against the configured option list.Black
data.vehicle.colour_namestring-Manufacturer colour name.Sapphire Black
data.vehicle.fuelstring-Fuel type. Value is validated against the configured option list.Petrol
data.vehicle.transmissionstring-Transmission type. Value is validated against the configured option list.Automatic
data.vehicle.drivetrainstring-Drivetrain. Applies to cars and bikes. Value is validated against the configured option list.RWD
data.vehicle.seatsinteger or null-Number of seats.5
data.vehicle.doorsinteger or null-Number of doors.5
data.vehicle.wheelbasestring-Wheelbase. Applies to vans.LWB
data.vehicle.cab_typestring-Cab type. Applies to vans and trucks.Double Cab
data.vehicle.mileageinteger or null-Odometer reading in miles.38450
data.vehicle.registeredstring (date) or null-First registration date (YYYY-MM-DD).2020-03-01
data.vehicle.categorystring-Vehicle category. Applies to farm, plant and trucks.Tractor
data.vehicle.driver_positionstring-Driver position (steering side).RHD
data.vehicle.interior_upholsterystring-Interior upholstery material.Leather
data.vehicle.interior_colourstring-Interior colour.Black
data.vehicle.exterior_finishstring-Exterior paint finish.Metallic
data.vehicle.groupstring-Vehicle grouping label (free text, for your own categorisation).Demo Fleet
data.vehicle.bedroom_layoutstring or null-Bedroom layout. Applies to caravans and motorhomes. Value is validated against the configured option list.Fixed island bed
data.vehicle.end_layoutstring or null-End layout. Applies to caravans and motorhomes. Value is validated against the configured option list.End washroom
data.vehicle.bedroominteger or null-Number of bedrooms. Applies to caravans and motorhomes.2
data.vehicle.berthinteger or null-Number of berths. Applies to caravans and motorhomes.4
data.vehicle.seat_beltinteger or null-Number of belted seats. Applies to caravans and motorhomes.4
data.vehicle.wheelchairstring or null-Wheelchair accessible (Yes/No). Applies to caravans and motorhomes. Value is validated against the configured option list.No
data.optionobject-
data.option.optionarray of string-Factory/standard option names. Write-only: accepted on create/update but not returned (read the resolved options via the feature object).["Sat Nav","Heated Seats"]
data.option.option_customarray of string-Custom (dealer-added) option names.["12 Month Warranty"]
data.option.attentionstring-Short attention grabber shown on listings.Full Service History
data.option.descriptionstring-Plain-text advert description.One owner from new, full BMW service history.
data.option.websitestring-HTML advert body shown on the website.<p>One owner from new.</p>
data.historyobject-
data.history.previous_ownerinteger or null-Number of previous owners.1
data.history.keysinteger or null-Number of keys supplied.2
data.history.v5string-Whether a V5C logbook is present (Yes/No).Yes
data.history.yearinteger or null-Year of manufacture.2020
data.history.conditionstring-Overall condition.Used
data.history.condition_interiorstring-Interior condition.Good
data.history.condition_exteriorstring-Exterior condition.Good
data.history.condition_tyrestring-Tyre condition.Good
data.history.service_historystring-Service history type.Full
data.history.service_laststring (date) or null-Date of last service (YYYY-MM-DD).2025-09-01
data.history.service_milesinteger or null-Mileage at last service.36000
data.history.mot_expirystring (date) or null-MOT expiry date (YYYY-MM-DD).2026-03-01
data.history.mot_yearstring-Whether 12 months' MOT is included (Yes/No).Yes
data.history.mot_insurancestring-Whether MOT insurance is included (Yes/No).No
data.history.warranty_expirystring (date) or null-Warranty expiry date (YYYY-MM-DD).2026-03-01
data.history.warranty_monthinteger or null-Remaining warranty in months.12
data.history.warranty_battery_monthinteger or null-Remaining battery warranty in months (EVs).60
data.history.service_notestring-Free-text service history note.Serviced at 12k and 24k miles.
data.stockobject-
data.stock.referencestring-Free-text stock reference.REF-1024
data.stock.numberstring-Stock number.STK1024
data.stock.locationstring-Business location. Accepts a location id on write; published as the location name.Main Forecourt
data.stock.notesstring-Internal notes (not shown publicly).Awaiting valet.
data.stock.vinstring-Vehicle identification number (uppercased alphanumeric).WBA8E9105HK000000
data.stock.engine_numberstring-Engine number.B47D20A
data.stock.key_numberstring-Key/security number.K12345
data.stock.originstring-Where the vehicle was sourced from.Part Exchange
data.stock.vatstring-VAT scheme display value (see vat_scheme for the normalised value).Inc VAT
data.stock.vat_pricingstring-How VAT is reflected in the price.Inc. VAT
data.stock.due_in_datestring (date) or null-Date the vehicle is due into stock (YYYY-MM-DD).2026-06-20
data.stock.forecourt_datestring (date) or null-Date the vehicle went on the forecourt (YYYY-MM-DD).2026-06-12
data.stock.price_websitenumber or null-Website price as a fixed 2dp decimal string.12500.00
data.stock.price_channelnumber or null-Channel price (published to sales channels) as a fixed 2dp decimal string.13495.00
data.stock.price_reservenumber or null-Reserve/minimum price (2dp decimal string).12000.00
data.stock.price_auction_startnumber or null-Auction starting price (2dp decimal string).10000.00
data.stock.price_auction_reservenumber or null-Auction reserve price (2dp decimal string).11000.00
data.stock.price_auction_buy_nownumber or null-Auction Buy Now price (2dp decimal string).13000.00
data.stock.price_auction_durationstring-Auction duration.7 Days
data.stock.price_auction_dealerway_typestring-Dealerway auction type. Only available when the dealerway channel is enabled. One of: Live Auction, Auction with Buy Now, Buy Now.Buy Now
data.stock.price_rrpnumber or null-Manufacturer RRP (2dp decimal string).24995.00
data.stock.funding_providerstring-Funding/finance provider name. Requires vehicle-pricing:read to read.Close Brothers
data.stock.funding_provider_idinteger or null-Funding provider contact id. Requires vehicle-pricing:read to read.42
data.stock.funding_provider_totalnumber or null-Outstanding funding amount (2dp decimal string). Requires vehicle-pricing:read to read.8000.00
data.stock.stock_quantityinteger or null-Quantity available (for new/multi-stock vehicles).1
data.stock.stock_variationobject-Stock variation data (new vehicle configurator variants).
data.stock.purchase_cost_dataarray of object-Additional purchase costs (transport, valeting, repairs, ...). Writing rows recomputes the read-only purchase_cost/value totals. Read requires vehicle-pricing:read.
data.settingobject-
data.setting.featuredenum-Whether the vehicle is featured. Accepts the strings "Yes" or "No".Yes
data.setting.poaenum-Price on application (hides the price). Accepts the strings "Yes" or "No".No
data.specobject-
data.spec.performanceobject-top_speed, zero_sixty.{"top_speed":155,"zero_sixty":5.8}
data.spec.engineobject-make, cylinders, bhp, ps, nm, gears...{"make":"BMW","cylinders":4,"capacity":1998,"bhp":181,"ps":184,"nm":300,"gears":8}
data.spec.batteryobject-charge_time, range, kwh, health.{"range":239,"kwh":58,"charge_time":"8h 15m","health":100}
data.spec.otherobject-axles, country, sector.{"axles":2,"country":"GB","sector":"Retail"}
data.spec.insuranceobject-group, code.{"group":"21E","code":"21E"}
data.spec.fuelobject-mpg_*, emission_*, ulez, caz.{"mpg_combined":48.7,"emission_co2":132,"ulez":true,"caz":true}
data.spec.sizeobject-length, width, height, weights, boot.{"length":4709,"width":2073,"height":1442,"wheelbase":2851,"kerb_weight":1545,"boot_seats_up":480}
{
    "country": "UK",
    "registration": "EO68NRJ",
    "status": "draft",
    "type": "in-stock",
    "data": {
        "vehicle": {
            "type": "Car",
            "make": "BMW",
            "model": "3 Series",
            "generation": "Saloon (2019 - 2023)",
            "derivative": "320i M Sport 4dr Auto",
            "trim": "M Sport",
            "engine_size": "2.0",
            "body": "Saloon",
            "colour": "Black",
            "colour_name": "Sapphire Black",
            "fuel": "Petrol",
            "transmission": "Automatic",
            "drivetrain": "RWD",
            "seats": 5,
            "doors": 5,
            "wheelbase": "LWB",
            "cab_type": "Double Cab",
            "mileage": 38450,
            "registered": "2020-03-01",
            "category": "Tractor",
            "driver_position": "RHD",
            "interior_upholstery": "Leather",
            "interior_colour": "Black",
            "exterior_finish": "Metallic",
            "group": "Demo Fleet",
            "bedroom_layout": "Fixed island bed",
            "end_layout": "End washroom",
            "bedroom": 2,
            "berth": 4,
            "seat_belt": 4,
            "wheelchair": "No"
        },
        "option": {
            "option": [
                "Sat Nav",
                "Heated Seats"
            ],
            "option_custom": [
                "12 Month Warranty"
            ],
            "attention": "Full Service History",
            "description": "One owner from new, full BMW service history.",
            "website": "<p>One owner from new.</p>"
        },
        "history": {
            "previous_owner": 1,
            "keys": 2,
            "v5": "Yes",
            "year": 2020,
            "condition": "Used",
            "condition_interior": "Good",
            "condition_exterior": "Good",
            "condition_tyre": "Good",
            "service_history": "Full",
            "service_last": "2025-09-01",
            "service_miles": 36000,
            "mot_expiry": "2026-03-01",
            "mot_year": "Yes",
            "mot_insurance": "No",
            "warranty_expiry": "2026-03-01",
            "warranty_month": 12,
            "warranty_battery_month": 60,
            "service_note": "Serviced at 12k and 24k miles."
        },
        "stock": {
            "reference": "REF-1024",
            "number": "STK1024",
            "location": "Main Forecourt",
            "notes": "Awaiting valet.",
            "vin": "WBA8E9105HK000000",
            "engine_number": "B47D20A",
            "key_number": "K12345",
            "origin": "Part Exchange",
            "vat": "Inc VAT",
            "vat_pricing": "Inc. VAT",
            "due_in_date": "2026-06-20",
            "forecourt_date": "2026-06-12",
            "price_website": "12500.00",
            "price_channel": "13495.00",
            "price_reserve": "12000.00",
            "price_auction_start": "10000.00",
            "price_auction_reserve": "11000.00",
            "price_auction_buy_now": "13000.00",
            "price_auction_duration": "7 Days",
            "price_auction_dealerway_type": "Buy Now",
            "price_rrp": "24995.00",
            "funding_provider": "Close Brothers",
            "funding_provider_id": 42,
            "funding_provider_total": "8000.00",
            "stock_quantity": 1,
            "stock_variation": {},
            "purchase_cost_data": [
                {
                    "type": "",
                    "supplier": "",
                    "cost": 0,
                    "vat": 0,
                    "invoice": "",
                    "reference": "",
                    "date": "2026-01-01",
                    "id": ""
                }
            ]
        },
        "setting": {
            "featured": "Yes",
            "poa": "No"
        },
        "spec": {
            "performance": {
                "top_speed": 155,
                "zero_sixty": 5.8
            },
            "engine": {
                "make": "BMW",
                "cylinders": 4,
                "capacity": 1998,
                "bhp": 181,
                "ps": 184,
                "nm": 300,
                "gears": 8
            },
            "battery": {
                "range": 239,
                "kwh": 58,
                "charge_time": "8h 15m",
                "health": 100
            },
            "other": {
                "axles": 2,
                "country": "GB",
                "sector": "Retail"
            },
            "insurance": {
                "group": "21E",
                "code": "21E"
            },
            "fuel": {
                "mpg_combined": 48.7,
                "emission_co2": 132,
                "ulez": true,
                "caz": true
            },
            "size": {
                "length": 4709,
                "width": 2073,
                "height": 1442,
                "wheelbase": 2851,
                "kerb_weight": 1545,
                "boot_seats_up": 480
            }
        }
    }
}
Responses
StatusDescription
201 CreatedVehicle created

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "country": "UK",
        "registration": "EO68NRJ",
        "url": "bmw-3-series-320i-m-sport-saloon-4dr-auto",
        "url_full": "https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/",
        "type": "in-stock",
        "created": 1779974135,
        "updated": 1781303332,
        "status": {
            "id": 2,
            "name": "for-sale",
            "label": "For Sale"
        },
        "owner": "",
        "parent": 0,
        "data": {
            "vehicle": {
                "type": "Car",
                "make": "BMW",
                "model": "3 Series",
                "generation": "Saloon (2019 - 2023)",
                "derivative": "320i M Sport 4dr Auto",
                "trim": "M Sport",
                "engine_size": "2.0",
                "body": "Saloon",
                "colour": "Black",
                "colour_name": "Sapphire Black",
                "fuel": "Petrol",
                "transmission": "Automatic",
                "drivetrain": "RWD",
                "seats": 5,
                "doors": 5,
                "wheelbase": "LWB",
                "cab_type": "Double Cab",
                "mileage": 38450,
                "registered": "2020-03-01",
                "category": "Tractor",
                "driver_position": "RHD",
                "interior_upholstery": "Leather",
                "interior_colour": "Black",
                "exterior_finish": "Metallic",
                "group": "Demo Fleet",
                "hour": "",
                "bedroom_layout": "Fixed island bed",
                "end_layout": "End washroom",
                "bedroom": 2,
                "berth": 4,
                "seat_belt": 4,
                "wheelchair": "No"
            },
            "option": {
                "option_custom": [
                    "12 Month Warranty"
                ],
                "attention": "Full Service History",
                "description": "One owner from new, full BMW service history.",
                "website": "<p>One owner from new.</p>",
                "feature": {}
            },
            "history": {
                "previous_owner": 1,
                "keys": 2,
                "v5": "Yes",
                "year": 2020,
                "condition": "Used",
                "condition_interior": "Good",
                "condition_exterior": "Good",
                "condition_tyre": "Good",
                "service_history": "Full",
                "service_last": "2025-09-01",
                "service_miles": 36000,
                "mot_expiry": "2026-03-01",
                "mot_year": "Yes",
                "mot_insurance": "No",
                "warranty_expiry": "2026-03-01",
                "warranty_month": 12,
                "warranty_battery_month": 60,
                "service_note": "Serviced at 12k and 24k miles."
            },
            "stock": {
                "reference": "REF-1024",
                "number": "STK1024",
                "location": "Main Forecourt",
                "notes": "Awaiting valet.",
                "vin": "WBA8E9105HK000000",
                "engine_number": "B47D20A",
                "key_number": "K12345",
                "origin": "Part Exchange",
                "vat": "Inc VAT",
                "vat_pricing": "Inc. VAT",
                "due_in_date": "2026-06-20",
                "forecourt_date": "2026-06-12",
                "price_website": "12500.00",
                "price_channel": "13495.00",
                "price_reserve": "12000.00",
                "price_auction_start": "10000.00",
                "price_auction_reserve": "11000.00",
                "price_auction_buy_now": "13000.00",
                "price_auction_duration": "7 Days",
                "price_auction_dealerway_type": "Buy Now",
                "price_rrp": "24995.00",
                "price_poa": false,
                "funding_provider": "Close Brothers",
                "funding_provider_id": 42,
                "funding_provider_total": "8000.00",
                "stock_quantity": 1,
                "stock_variation": {},
                "purchase_date": "2026-01-15",
                "purchase_invoice": "PINV-2048",
                "purchase_supplier": "BCA Auction",
                "purchase_supplier_id": 30418,
                "purchase_supplier_invoice": "BCA-99812",
                "purchase_price": "9000.00",
                "purchase_price_vat": "0.00",
                "purchase_price_total": "9000.00",
                "purchase_cost": "450.00",
                "purchase_cost_vat": "90.00",
                "purchase_cost_total": "540.00",
                "purchase_value": "9450.00",
                "purchase_value_vat": "90.00",
                "purchase_value_total": "9540.00",
                "purchase_cost_data": [
                    {
                        "type": "",
                        "supplier": "",
                        "cost": "0.00",
                        "vat": "0.00",
                        "invoice": "",
                        "reference": "",
                        "date": "2026-01-01",
                        "id": "",
                        "total": "0.00"
                    }
                ]
            },
            "spec": {
                "performance": {
                    "top_speed": 155,
                    "zero_sixty": 5.8
                },
                "engine": {
                    "make": "BMW",
                    "cylinders": 4,
                    "capacity": 1998,
                    "bhp": 181,
                    "ps": 184,
                    "nm": 300,
                    "gears": 8
                },
                "battery": {
                    "range": 239,
                    "kwh": 58,
                    "charge_time": "8h 15m",
                    "health": 100
                },
                "other": {
                    "axles": 2,
                    "country": "GB",
                    "sector": "Retail"
                },
                "insurance": {
                    "group": "21E",
                    "code": "21E"
                },
                "fuel": {
                    "mpg_combined": 48.7,
                    "emission_co2": 132,
                    "ulez": true,
                    "caz": true
                },
                "size": {
                    "length": 4709,
                    "width": 2073,
                    "height": 1442,
                    "wheelbase": 2851,
                    "kerb_weight": 1545,
                    "boot_seats_up": 480
                }
            },
            "appraisal": {
                "details": {
                    "customer_id": "4471",
                    "customer": "Ada Buyer"
                },
                "calculation": {
                    "offer": "9500.00",
                    "finance_settlement": "2000.00"
                },
                "confirm": {
                    "offer": "9500.00",
                    "expiry": "2026-09-06",
                    "appraised_at": 1756137600,
                    "agreed_amount": "9250.00",
                    "decision": "accepted",
                    "decision_at": 1756224000,
                    "stock_id": "18342",
                    "stock_tag": "a1b2c3d4"
                }
            },
            "lookup": {
                "dvla": {
                    "make": "BMW",
                    "colour": "BLACK",
                    "fuel_type": "PETROL",
                    "year_of_manufacture": 2020,
                    "tax_status": "Taxed"
                },
                "dvsa": {
                    "mot_tests": [
                        {
                            "completed_date": "2025-03-01",
                            "test_result": "PASSED",
                            "odometer_value": 36000
                        }
                    ]
                },
                "check": {
                    "stolen": false,
                    "finance": false,
                    "written_off": false,
                    "previous_keepers": 1
                }
            },
            "tag": [
                {
                    "name": "Service",
                    "checked": false,
                    "colour": "primary",
                    "type": "check"
                }
            ],
            "finance": {
                "example_monthly": "507.75",
                "example": {
                    "cash_price": "20000.00",
                    "total_deposit": "2000.00",
                    "total_credit": "18000.00",
                    "first_payment": "507.75",
                    "monthly_payment": "507.75",
                    "total_monthly_payments": 25,
                    "final_payment": "7856.00",
                    "term": 27,
                    "admin_fee": "0.00",
                    "option_purchase_fee": "10.00",
                    "interest_charge": "3057.50",
                    "total_payable": "23057.50",
                    "fixed_interest_rate": 10.36,
                    "representative_apr": 10.9
                }
            }
        },
        "media": {
            "photo": [
                "m7Yk2p9q",
                "r3Tn8w1z"
            ],
            "video": [
                "v9Lp4m2x"
            ],
            "youtube": [
                "dQw4w9WgXcQ"
            ],
            "photo_spin": [
                "s5Qw8r3t"
            ]
        }
    }
}

GET Get Vehicle

GET /2.0/vehicles/{id} · scope vehicles:read

Retrieve a single vehicle by id.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKVehicle

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "country": "UK",
        "registration": "EO68NRJ",
        "url": "bmw-3-series-320i-m-sport-saloon-4dr-auto",
        "url_full": "https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/",
        "type": "in-stock",
        "created": 1779974135,
        "updated": 1781303332,
        "status": {
            "id": 2,
            "name": "for-sale",
            "label": "For Sale"
        },
        "owner": "",
        "parent": 0,
        "data": {
            "vehicle": {
                "type": "Car",
                "make": "BMW",
                "model": "3 Series",
                "generation": "Saloon (2019 - 2023)",
                "derivative": "320i M Sport 4dr Auto",
                "trim": "M Sport",
                "engine_size": "2.0",
                "body": "Saloon",
                "colour": "Black",
                "colour_name": "Sapphire Black",
                "fuel": "Petrol",
                "transmission": "Automatic",
                "drivetrain": "RWD",
                "seats": 5,
                "doors": 5,
                "wheelbase": "LWB",
                "cab_type": "Double Cab",
                "mileage": 38450,
                "registered": "2020-03-01",
                "category": "Tractor",
                "driver_position": "RHD",
                "interior_upholstery": "Leather",
                "interior_colour": "Black",
                "exterior_finish": "Metallic",
                "group": "Demo Fleet",
                "hour": "",
                "bedroom_layout": "Fixed island bed",
                "end_layout": "End washroom",
                "bedroom": 2,
                "berth": 4,
                "seat_belt": 4,
                "wheelchair": "No"
            },
            "option": {
                "option_custom": [
                    "12 Month Warranty"
                ],
                "attention": "Full Service History",
                "description": "One owner from new, full BMW service history.",
                "website": "<p>One owner from new.</p>",
                "feature": {}
            },
            "history": {
                "previous_owner": 1,
                "keys": 2,
                "v5": "Yes",
                "year": 2020,
                "condition": "Used",
                "condition_interior": "Good",
                "condition_exterior": "Good",
                "condition_tyre": "Good",
                "service_history": "Full",
                "service_last": "2025-09-01",
                "service_miles": 36000,
                "mot_expiry": "2026-03-01",
                "mot_year": "Yes",
                "mot_insurance": "No",
                "warranty_expiry": "2026-03-01",
                "warranty_month": 12,
                "warranty_battery_month": 60,
                "service_note": "Serviced at 12k and 24k miles."
            },
            "stock": {
                "reference": "REF-1024",
                "number": "STK1024",
                "location": "Main Forecourt",
                "notes": "Awaiting valet.",
                "vin": "WBA8E9105HK000000",
                "engine_number": "B47D20A",
                "key_number": "K12345",
                "origin": "Part Exchange",
                "vat": "Inc VAT",
                "vat_pricing": "Inc. VAT",
                "due_in_date": "2026-06-20",
                "forecourt_date": "2026-06-12",
                "price_website": "12500.00",
                "price_channel": "13495.00",
                "price_reserve": "12000.00",
                "price_auction_start": "10000.00",
                "price_auction_reserve": "11000.00",
                "price_auction_buy_now": "13000.00",
                "price_auction_duration": "7 Days",
                "price_auction_dealerway_type": "Buy Now",
                "price_rrp": "24995.00",
                "price_poa": false,
                "funding_provider": "Close Brothers",
                "funding_provider_id": 42,
                "funding_provider_total": "8000.00",
                "stock_quantity": 1,
                "stock_variation": {},
                "purchase_date": "2026-01-15",
                "purchase_invoice": "PINV-2048",
                "purchase_supplier": "BCA Auction",
                "purchase_supplier_id": 30418,
                "purchase_supplier_invoice": "BCA-99812",
                "purchase_price": "9000.00",
                "purchase_price_vat": "0.00",
                "purchase_price_total": "9000.00",
                "purchase_cost": "450.00",
                "purchase_cost_vat": "90.00",
                "purchase_cost_total": "540.00",
                "purchase_value": "9450.00",
                "purchase_value_vat": "90.00",
                "purchase_value_total": "9540.00",
                "purchase_cost_data": [
                    {
                        "type": "",
                        "supplier": "",
                        "cost": "0.00",
                        "vat": "0.00",
                        "invoice": "",
                        "reference": "",
                        "date": "2026-01-01",
                        "id": "",
                        "total": "0.00"
                    }
                ]
            },
            "spec": {
                "performance": {
                    "top_speed": 155,
                    "zero_sixty": 5.8
                },
                "engine": {
                    "make": "BMW",
                    "cylinders": 4,
                    "capacity": 1998,
                    "bhp": 181,
                    "ps": 184,
                    "nm": 300,
                    "gears": 8
                },
                "battery": {
                    "range": 239,
                    "kwh": 58,
                    "charge_time": "8h 15m",
                    "health": 100
                },
                "other": {
                    "axles": 2,
                    "country": "GB",
                    "sector": "Retail"
                },
                "insurance": {
                    "group": "21E",
                    "code": "21E"
                },
                "fuel": {
                    "mpg_combined": 48.7,
                    "emission_co2": 132,
                    "ulez": true,
                    "caz": true
                },
                "size": {
                    "length": 4709,
                    "width": 2073,
                    "height": 1442,
                    "wheelbase": 2851,
                    "kerb_weight": 1545,
                    "boot_seats_up": 480
                }
            },
            "appraisal": {
                "details": {
                    "customer_id": "4471",
                    "customer": "Ada Buyer"
                },
                "calculation": {
                    "offer": "9500.00",
                    "finance_settlement": "2000.00"
                },
                "confirm": {
                    "offer": "9500.00",
                    "expiry": "2026-09-06",
                    "appraised_at": 1756137600,
                    "agreed_amount": "9250.00",
                    "decision": "accepted",
                    "decision_at": 1756224000,
                    "stock_id": "18342",
                    "stock_tag": "a1b2c3d4"
                }
            },
            "lookup": {
                "dvla": {
                    "make": "BMW",
                    "colour": "BLACK",
                    "fuel_type": "PETROL",
                    "year_of_manufacture": 2020,
                    "tax_status": "Taxed"
                },
                "dvsa": {
                    "mot_tests": [
                        {
                            "completed_date": "2025-03-01",
                            "test_result": "PASSED",
                            "odometer_value": 36000
                        }
                    ]
                },
                "check": {
                    "stolen": false,
                    "finance": false,
                    "written_off": false,
                    "previous_keepers": 1
                }
            },
            "tag": [
                {
                    "name": "Service",
                    "checked": false,
                    "colour": "primary",
                    "type": "check"
                }
            ],
            "finance": {
                "example_monthly": "507.75",
                "example": {
                    "cash_price": "20000.00",
                    "total_deposit": "2000.00",
                    "total_credit": "18000.00",
                    "first_payment": "507.75",
                    "monthly_payment": "507.75",
                    "total_monthly_payments": 25,
                    "final_payment": "7856.00",
                    "term": 27,
                    "admin_fee": "0.00",
                    "option_purchase_fee": "10.00",
                    "interest_charge": "3057.50",
                    "total_payable": "23057.50",
                    "fixed_interest_rate": 10.36,
                    "representative_apr": 10.9
                }
            }
        },
        "media": {
            "photo": [
                "m7Yk2p9q",
                "r3Tn8w1z"
            ],
            "video": [
                "v9Lp4m2x"
            ],
            "youtube": [
                "dQw4w9WgXcQ"
            ],
            "photo_spin": [
                "s5Qw8r3t"
            ]
        }
    }
}

PATCH Update Vehicle

PATCH /2.0/vehicles/{id} · scope vehicles:write

Update allowed vehicle data fields.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
dataobjectYesWritable vehicle data, grouped by section. Only the fields listed here are accepted; unknown fields are rejected.
data.vehicleobject-
data.vehicle.typestring-Vehicle class. Case-sensitive; use the canonical capitalised value (Car, Van, Bike, Truck, Crossover, Motorhome, Caravan, Farm, Plant) as returned by /reference vehicle taxonomy; an unrecognised class is rejected on this field. Some fields apply only to certain classes (e.g. wheelbase to vans).Car
data.vehicle.makestring-Manufacturer / make. Send the manufacturer name; it is matched (case-insensitively) against the make taxonomy for the vehicle class. A value with no match is accepted and stored as a custom make. Read back as the value you sent. See /reference vehicle taxonomy.BMW
data.vehicle.modelstring-Model name. Matched against the model taxonomy for the chosen make; a value with no match (or any model under a custom make) is accepted and stored as a custom model.3 Series
data.vehicle.generationstring-Model generation. Matched against the generation taxonomy for the chosen make/model; an unmatched value is accepted and stored as custom.Saloon (2019 - 2023)
data.vehicle.derivativestring-Manufacturer derivative / full spec name. Matched against the derivative taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.320i M Sport 4dr Auto
data.vehicle.trimstring-Trim level. Matched against the trim taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.M Sport
data.vehicle.engine_sizestring-Engine size in litres. Matched against the engine-size taxonomy for the chosen make/model/generation; an unmatched value is accepted and stored as custom.2.0
data.vehicle.bodystring-Body style. Value is validated against the configured option list.Saloon
data.vehicle.colourstring-Paint colour. Value is validated against the configured option list.Black
data.vehicle.colour_namestring-Manufacturer colour name.Sapphire Black
data.vehicle.fuelstring-Fuel type. Value is validated against the configured option list.Petrol
data.vehicle.transmissionstring-Transmission type. Value is validated against the configured option list.Automatic
data.vehicle.drivetrainstring-Drivetrain. Applies to cars and bikes. Value is validated against the configured option list.RWD
data.vehicle.seatsinteger or null-Number of seats.5
data.vehicle.doorsinteger or null-Number of doors.5
data.vehicle.wheelbasestring-Wheelbase. Applies to vans.LWB
data.vehicle.cab_typestring-Cab type. Applies to vans and trucks.Double Cab
data.vehicle.mileageinteger or null-Odometer reading in miles.38450
data.vehicle.registeredstring (date) or null-First registration date (YYYY-MM-DD).2020-03-01
data.vehicle.categorystring-Vehicle category. Applies to farm, plant and trucks.Tractor
data.vehicle.driver_positionstring-Driver position (steering side).RHD
data.vehicle.interior_upholsterystring-Interior upholstery material.Leather
data.vehicle.interior_colourstring-Interior colour.Black
data.vehicle.exterior_finishstring-Exterior paint finish.Metallic
data.vehicle.groupstring-Vehicle grouping label (free text, for your own categorisation).Demo Fleet
data.vehicle.bedroom_layoutstring or null-Bedroom layout. Applies to caravans and motorhomes. Value is validated against the configured option list.Fixed island bed
data.vehicle.end_layoutstring or null-End layout. Applies to caravans and motorhomes. Value is validated against the configured option list.End washroom
data.vehicle.bedroominteger or null-Number of bedrooms. Applies to caravans and motorhomes.2
data.vehicle.berthinteger or null-Number of berths. Applies to caravans and motorhomes.4
data.vehicle.seat_beltinteger or null-Number of belted seats. Applies to caravans and motorhomes.4
data.vehicle.wheelchairstring or null-Wheelchair accessible (Yes/No). Applies to caravans and motorhomes. Value is validated against the configured option list.No
data.optionobject-
data.option.optionarray of string-Factory/standard option names. Write-only: accepted on create/update but not returned (read the resolved options via the feature object).["Sat Nav","Heated Seats"]
data.option.option_customarray of string-Custom (dealer-added) option names.["12 Month Warranty"]
data.option.attentionstring-Short attention grabber shown on listings.Full Service History
data.option.descriptionstring-Plain-text advert description.One owner from new, full BMW service history.
data.option.websitestring-HTML advert body shown on the website.<p>One owner from new.</p>
data.historyobject-
data.history.previous_ownerinteger or null-Number of previous owners.1
data.history.keysinteger or null-Number of keys supplied.2
data.history.v5string-Whether a V5C logbook is present (Yes/No).Yes
data.history.yearinteger or null-Year of manufacture.2020
data.history.conditionstring-Overall condition.Used
data.history.condition_interiorstring-Interior condition.Good
data.history.condition_exteriorstring-Exterior condition.Good
data.history.condition_tyrestring-Tyre condition.Good
data.history.service_historystring-Service history type.Full
data.history.service_laststring (date) or null-Date of last service (YYYY-MM-DD).2025-09-01
data.history.service_milesinteger or null-Mileage at last service.36000
data.history.mot_expirystring (date) or null-MOT expiry date (YYYY-MM-DD).2026-03-01
data.history.mot_yearstring-Whether 12 months' MOT is included (Yes/No).Yes
data.history.mot_insurancestring-Whether MOT insurance is included (Yes/No).No
data.history.warranty_expirystring (date) or null-Warranty expiry date (YYYY-MM-DD).2026-03-01
data.history.warranty_monthinteger or null-Remaining warranty in months.12
data.history.warranty_battery_monthinteger or null-Remaining battery warranty in months (EVs).60
data.history.service_notestring-Free-text service history note.Serviced at 12k and 24k miles.
data.stockobject-
data.stock.referencestring-Free-text stock reference.REF-1024
data.stock.numberstring-Stock number.STK1024
data.stock.locationstring-Business location. Accepts a location id on write; published as the location name.Main Forecourt
data.stock.notesstring-Internal notes (not shown publicly).Awaiting valet.
data.stock.vinstring-Vehicle identification number (uppercased alphanumeric).WBA8E9105HK000000
data.stock.engine_numberstring-Engine number.B47D20A
data.stock.key_numberstring-Key/security number.K12345
data.stock.originstring-Where the vehicle was sourced from.Part Exchange
data.stock.vatstring-VAT scheme display value (see vat_scheme for the normalised value).Inc VAT
data.stock.vat_pricingstring-How VAT is reflected in the price.Inc. VAT
data.stock.due_in_datestring (date) or null-Date the vehicle is due into stock (YYYY-MM-DD).2026-06-20
data.stock.forecourt_datestring (date) or null-Date the vehicle went on the forecourt (YYYY-MM-DD).2026-06-12
data.stock.price_websitenumber or null-Website price as a fixed 2dp decimal string.12500.00
data.stock.price_channelnumber or null-Channel price (published to sales channels) as a fixed 2dp decimal string.13495.00
data.stock.price_reservenumber or null-Reserve/minimum price (2dp decimal string).12000.00
data.stock.price_auction_startnumber or null-Auction starting price (2dp decimal string).10000.00
data.stock.price_auction_reservenumber or null-Auction reserve price (2dp decimal string).11000.00
data.stock.price_auction_buy_nownumber or null-Auction Buy Now price (2dp decimal string).13000.00
data.stock.price_auction_durationstring-Auction duration.7 Days
data.stock.price_auction_dealerway_typestring-Dealerway auction type. Only available when the dealerway channel is enabled. One of: Live Auction, Auction with Buy Now, Buy Now.Buy Now
data.stock.price_rrpnumber or null-Manufacturer RRP (2dp decimal string).24995.00
data.stock.funding_providerstring-Funding/finance provider name. Requires vehicle-pricing:read to read.Close Brothers
data.stock.funding_provider_idinteger or null-Funding provider contact id. Requires vehicle-pricing:read to read.42
data.stock.funding_provider_totalnumber or null-Outstanding funding amount (2dp decimal string). Requires vehicle-pricing:read to read.8000.00
data.stock.stock_quantityinteger or null-Quantity available (for new/multi-stock vehicles).1
data.stock.stock_variationobject-Stock variation data (new vehicle configurator variants).
data.stock.purchase_cost_dataarray of object-Additional purchase costs (transport, valeting, repairs, ...). Writing rows recomputes the read-only purchase_cost/value totals. Read requires vehicle-pricing:read.
data.settingobject-
data.setting.featuredenum-Whether the vehicle is featured. Accepts the strings "Yes" or "No".Yes
data.setting.poaenum-Price on application (hides the price). Accepts the strings "Yes" or "No".No
data.specobject-
data.spec.performanceobject-top_speed, zero_sixty.{"top_speed":155,"zero_sixty":5.8}
data.spec.engineobject-make, cylinders, bhp, ps, nm, gears...{"make":"BMW","cylinders":4,"capacity":1998,"bhp":181,"ps":184,"nm":300,"gears":8}
data.spec.batteryobject-charge_time, range, kwh, health.{"range":239,"kwh":58,"charge_time":"8h 15m","health":100}
data.spec.otherobject-axles, country, sector.{"axles":2,"country":"GB","sector":"Retail"}
data.spec.insuranceobject-group, code.{"group":"21E","code":"21E"}
data.spec.fuelobject-mpg_*, emission_*, ulez, caz.{"mpg_combined":48.7,"emission_co2":132,"ulez":true,"caz":true}
data.spec.sizeobject-length, width, height, weights, boot.{"length":4709,"width":2073,"height":1442,"wheelbase":2851,"kerb_weight":1545,"boot_seats_up":480}
{
    "data": {
        "vehicle": {
            "type": "Car",
            "make": "BMW",
            "model": "3 Series",
            "generation": "Saloon (2019 - 2023)",
            "derivative": "320i M Sport 4dr Auto",
            "trim": "M Sport",
            "engine_size": "2.0",
            "body": "Saloon",
            "colour": "Black",
            "colour_name": "Sapphire Black",
            "fuel": "Petrol",
            "transmission": "Automatic",
            "drivetrain": "RWD",
            "seats": 5,
            "doors": 5,
            "wheelbase": "LWB",
            "cab_type": "Double Cab",
            "mileage": 38450,
            "registered": "2020-03-01",
            "category": "Tractor",
            "driver_position": "RHD",
            "interior_upholstery": "Leather",
            "interior_colour": "Black",
            "exterior_finish": "Metallic",
            "group": "Demo Fleet",
            "bedroom_layout": "Fixed island bed",
            "end_layout": "End washroom",
            "bedroom": 2,
            "berth": 4,
            "seat_belt": 4,
            "wheelchair": "No"
        },
        "option": {
            "option": [
                "Sat Nav",
                "Heated Seats"
            ],
            "option_custom": [
                "12 Month Warranty"
            ],
            "attention": "Full Service History",
            "description": "One owner from new, full BMW service history.",
            "website": "<p>One owner from new.</p>"
        },
        "history": {
            "previous_owner": 1,
            "keys": 2,
            "v5": "Yes",
            "year": 2020,
            "condition": "Used",
            "condition_interior": "Good",
            "condition_exterior": "Good",
            "condition_tyre": "Good",
            "service_history": "Full",
            "service_last": "2025-09-01",
            "service_miles": 36000,
            "mot_expiry": "2026-03-01",
            "mot_year": "Yes",
            "mot_insurance": "No",
            "warranty_expiry": "2026-03-01",
            "warranty_month": 12,
            "warranty_battery_month": 60,
            "service_note": "Serviced at 12k and 24k miles."
        },
        "stock": {
            "reference": "REF-1024",
            "number": "STK1024",
            "location": "Main Forecourt",
            "notes": "Awaiting valet.",
            "vin": "WBA8E9105HK000000",
            "engine_number": "B47D20A",
            "key_number": "K12345",
            "origin": "Part Exchange",
            "vat": "Inc VAT",
            "vat_pricing": "Inc. VAT",
            "due_in_date": "2026-06-20",
            "forecourt_date": "2026-06-12",
            "price_website": "12500.00",
            "price_channel": "13495.00",
            "price_reserve": "12000.00",
            "price_auction_start": "10000.00",
            "price_auction_reserve": "11000.00",
            "price_auction_buy_now": "13000.00",
            "price_auction_duration": "7 Days",
            "price_auction_dealerway_type": "Buy Now",
            "price_rrp": "24995.00",
            "funding_provider": "Close Brothers",
            "funding_provider_id": 42,
            "funding_provider_total": "8000.00",
            "stock_quantity": 1,
            "stock_variation": {},
            "purchase_cost_data": [
                {
                    "type": "",
                    "supplier": "",
                    "cost": 0,
                    "vat": 0,
                    "invoice": "",
                    "reference": "",
                    "date": "2026-01-01",
                    "id": ""
                }
            ]
        },
        "setting": {
            "featured": "Yes",
            "poa": "No"
        },
        "spec": {
            "performance": {
                "top_speed": 155,
                "zero_sixty": 5.8
            },
            "engine": {
                "make": "BMW",
                "cylinders": 4,
                "capacity": 1998,
                "bhp": 181,
                "ps": 184,
                "nm": 300,
                "gears": 8
            },
            "battery": {
                "range": 239,
                "kwh": 58,
                "charge_time": "8h 15m",
                "health": 100
            },
            "other": {
                "axles": 2,
                "country": "GB",
                "sector": "Retail"
            },
            "insurance": {
                "group": "21E",
                "code": "21E"
            },
            "fuel": {
                "mpg_combined": 48.7,
                "emission_co2": 132,
                "ulez": true,
                "caz": true
            },
            "size": {
                "length": 4709,
                "width": 2073,
                "height": 1442,
                "wheelbase": 2851,
                "kerb_weight": 1545,
                "boot_seats_up": 480
            }
        }
    }
}
Responses
StatusDescription
200 OKVehicle updated

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "country": "UK",
        "registration": "EO68NRJ",
        "url": "bmw-3-series-320i-m-sport-saloon-4dr-auto",
        "url_full": "https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/",
        "type": "in-stock",
        "created": 1779974135,
        "updated": 1781303332,
        "status": {
            "id": 2,
            "name": "for-sale",
            "label": "For Sale"
        },
        "owner": "",
        "parent": 0,
        "data": {
            "vehicle": {
                "type": "Car",
                "make": "BMW",
                "model": "3 Series",
                "generation": "Saloon (2019 - 2023)",
                "derivative": "320i M Sport 4dr Auto",
                "trim": "M Sport",
                "engine_size": "2.0",
                "body": "Saloon",
                "colour": "Black",
                "colour_name": "Sapphire Black",
                "fuel": "Petrol",
                "transmission": "Automatic",
                "drivetrain": "RWD",
                "seats": 5,
                "doors": 5,
                "wheelbase": "LWB",
                "cab_type": "Double Cab",
                "mileage": 38450,
                "registered": "2020-03-01",
                "category": "Tractor",
                "driver_position": "RHD",
                "interior_upholstery": "Leather",
                "interior_colour": "Black",
                "exterior_finish": "Metallic",
                "group": "Demo Fleet",
                "hour": "",
                "bedroom_layout": "Fixed island bed",
                "end_layout": "End washroom",
                "bedroom": 2,
                "berth": 4,
                "seat_belt": 4,
                "wheelchair": "No"
            },
            "option": {
                "option_custom": [
                    "12 Month Warranty"
                ],
                "attention": "Full Service History",
                "description": "One owner from new, full BMW service history.",
                "website": "<p>One owner from new.</p>",
                "feature": {}
            },
            "history": {
                "previous_owner": 1,
                "keys": 2,
                "v5": "Yes",
                "year": 2020,
                "condition": "Used",
                "condition_interior": "Good",
                "condition_exterior": "Good",
                "condition_tyre": "Good",
                "service_history": "Full",
                "service_last": "2025-09-01",
                "service_miles": 36000,
                "mot_expiry": "2026-03-01",
                "mot_year": "Yes",
                "mot_insurance": "No",
                "warranty_expiry": "2026-03-01",
                "warranty_month": 12,
                "warranty_battery_month": 60,
                "service_note": "Serviced at 12k and 24k miles."
            },
            "stock": {
                "reference": "REF-1024",
                "number": "STK1024",
                "location": "Main Forecourt",
                "notes": "Awaiting valet.",
                "vin": "WBA8E9105HK000000",
                "engine_number": "B47D20A",
                "key_number": "K12345",
                "origin": "Part Exchange",
                "vat": "Inc VAT",
                "vat_pricing": "Inc. VAT",
                "due_in_date": "2026-06-20",
                "forecourt_date": "2026-06-12",
                "price_website": "12500.00",
                "price_channel": "13495.00",
                "price_reserve": "12000.00",
                "price_auction_start": "10000.00",
                "price_auction_reserve": "11000.00",
                "price_auction_buy_now": "13000.00",
                "price_auction_duration": "7 Days",
                "price_auction_dealerway_type": "Buy Now",
                "price_rrp": "24995.00",
                "price_poa": false,
                "funding_provider": "Close Brothers",
                "funding_provider_id": 42,
                "funding_provider_total": "8000.00",
                "stock_quantity": 1,
                "stock_variation": {},
                "purchase_date": "2026-01-15",
                "purchase_invoice": "PINV-2048",
                "purchase_supplier": "BCA Auction",
                "purchase_supplier_id": 30418,
                "purchase_supplier_invoice": "BCA-99812",
                "purchase_price": "9000.00",
                "purchase_price_vat": "0.00",
                "purchase_price_total": "9000.00",
                "purchase_cost": "450.00",
                "purchase_cost_vat": "90.00",
                "purchase_cost_total": "540.00",
                "purchase_value": "9450.00",
                "purchase_value_vat": "90.00",
                "purchase_value_total": "9540.00",
                "purchase_cost_data": [
                    {
                        "type": "",
                        "supplier": "",
                        "cost": "0.00",
                        "vat": "0.00",
                        "invoice": "",
                        "reference": "",
                        "date": "2026-01-01",
                        "id": "",
                        "total": "0.00"
                    }
                ]
            },
            "spec": {
                "performance": {
                    "top_speed": 155,
                    "zero_sixty": 5.8
                },
                "engine": {
                    "make": "BMW",
                    "cylinders": 4,
                    "capacity": 1998,
                    "bhp": 181,
                    "ps": 184,
                    "nm": 300,
                    "gears": 8
                },
                "battery": {
                    "range": 239,
                    "kwh": 58,
                    "charge_time": "8h 15m",
                    "health": 100
                },
                "other": {
                    "axles": 2,
                    "country": "GB",
                    "sector": "Retail"
                },
                "insurance": {
                    "group": "21E",
                    "code": "21E"
                },
                "fuel": {
                    "mpg_combined": 48.7,
                    "emission_co2": 132,
                    "ulez": true,
                    "caz": true
                },
                "size": {
                    "length": 4709,
                    "width": 2073,
                    "height": 1442,
                    "wheelbase": 2851,
                    "kerb_weight": 1545,
                    "boot_seats_up": 480
                }
            },
            "appraisal": {
                "details": {
                    "customer_id": "4471",
                    "customer": "Ada Buyer"
                },
                "calculation": {
                    "offer": "9500.00",
                    "finance_settlement": "2000.00"
                },
                "confirm": {
                    "offer": "9500.00",
                    "expiry": "2026-09-06",
                    "appraised_at": 1756137600,
                    "agreed_amount": "9250.00",
                    "decision": "accepted",
                    "decision_at": 1756224000,
                    "stock_id": "18342",
                    "stock_tag": "a1b2c3d4"
                }
            },
            "lookup": {
                "dvla": {
                    "make": "BMW",
                    "colour": "BLACK",
                    "fuel_type": "PETROL",
                    "year_of_manufacture": 2020,
                    "tax_status": "Taxed"
                },
                "dvsa": {
                    "mot_tests": [
                        {
                            "completed_date": "2025-03-01",
                            "test_result": "PASSED",
                            "odometer_value": 36000
                        }
                    ]
                },
                "check": {
                    "stolen": false,
                    "finance": false,
                    "written_off": false,
                    "previous_keepers": 1
                }
            },
            "tag": [
                {
                    "name": "Service",
                    "checked": false,
                    "colour": "primary",
                    "type": "check"
                }
            ],
            "finance": {
                "example_monthly": "507.75",
                "example": {
                    "cash_price": "20000.00",
                    "total_deposit": "2000.00",
                    "total_credit": "18000.00",
                    "first_payment": "507.75",
                    "monthly_payment": "507.75",
                    "total_monthly_payments": 25,
                    "final_payment": "7856.00",
                    "term": 27,
                    "admin_fee": "0.00",
                    "option_purchase_fee": "10.00",
                    "interest_charge": "3057.50",
                    "total_payable": "23057.50",
                    "fixed_interest_rate": 10.36,
                    "representative_apr": 10.9
                }
            }
        },
        "media": {
            "photo": [
                "m7Yk2p9q",
                "r3Tn8w1z"
            ],
            "video": [
                "v9Lp4m2x"
            ],
            "youtube": [
                "dQw4w9WgXcQ"
            ],
            "photo_spin": [
                "s5Qw8r3t"
            ]
        }
    }
}

DELETE Delete Vehicle

DELETE /2.0/vehicles/{id} · scope vehicles:delete

Delete a vehicle. The vehicle is unpublished from its sales channels and its status becomes deleted; the record remains readable and can be restored to draft with PATCH /vehicles/{id}/status.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKVehicle deleted

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Lookups

POST Vehicle Lookup

POST /2.0/vehicle-lookups · scope vehicle-lookups:write

Retrieve vehicle data from configured lookup providers.

Request body
AttributeTypeRequiredDescriptionExample
typestringYesHow to interpret identifier: a 2-letter ISO country code (e.g. "UK"; "GB" is treated as "UK") to look up by that country's registration, or "VIN" to look up by VIN. Determines the validation applied to identifier.UK
identifierstringYesThe vehicle registration number (when type is a country) or the VIN (when type is "VIN"). Case-insensitive; spaces are ignored.EO68NRJ
motboolean-Include MOT history in the result. Defaults to true.
featuresboolean-Include factory feature/option data. Defaults to true.
basic_checkboolean-Include a basic provider vehicle check. Defaults to true.
factory_fittedboolean-Include factory-fitted specification data. Defaults to true.
full_checkboolean-Run a full provider check (more detailed; may incur a provider cost). Defaults to false.
{
    "type": "UK",
    "identifier": "EO68NRJ",
    "mot": false,
    "features": false,
    "basic_check": false,
    "factory_fitted": false,
    "full_check": false
}
Responses
StatusDescription
200 OKVehicle lookup result

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "country": "",
        "identifier": "",
        "registration": "",
        "url": "",
        "data": {},
        "media": {
            "photo": [
                ""
            ],
            "video": [
                ""
            ],
            "youtube": [
                ""
            ],
            "photo_spin": [
                ""
            ]
        }
    }
}

Recognitions

POST Vehicle Recognition

POST /2.0/vehicle-recognitions · scope vehicle-recognitions:write

Recognise a registration or VIN from image data or an identifier.

Request body
AttributeTypeRequiredDescriptionExample
typeenum-What to recognise: registration, vin, or auto to detect which. Defaults to auto.auto
countrystring-Country code for the registration format (e.g. UK; GB is treated as UK). Defaults to the business country.UK
imagestring-Image to read the plate or VIN from, as a base64 string or a data: URL. Provide this or identifier.data:image/jpeg;base64,/9j/4AAQSkZJRg...
identifierstring-A known registration or VIN to validate and normalise instead of reading from an image.EO68NRJ
{
    "type": "auto",
    "country": "UK",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "identifier": "EO68NRJ"
}
Responses
StatusDescription
200 OKVehicle recognition result

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "type": "registration",
        "identifier": "",
        "source": "text",
        "country": "",
        "registration": "",
        "vin": "",
        "summary": {},
        "match": {
            "id": 0,
            "tag": ""
        }
    }
}

Taxonomy

GET Vehicle Taxonomy

GET /2.0/vehicle-taxonomy · scope vehicle-taxonomy:read

Discover vehicle taxonomy values.

Parameters (9)
ParameterInTypeRequiredDescriptionExample
typequeryenum-Filter by type.
makequerystring-Filter by make.
modelquerystring-Filter by model.
generationquerystring-Filter by generation.
derivativequerystring-Filter by derivative.
listqueryenum-Filter by list.
countryquerystring-Filter by country.
cursorquerystring-Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKVehicle taxonomy values

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "type": "",
            "country": "",
            "level": "",
            "items": [
                {}
            ]
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}

Pricing

GET Get Vehicle Pricing

GET /2.0/vehicles/{id}/pricing · scope vehicle-pricing:read

Retrieve internal vehicle pricing and valuation data.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKVehicle pricing and valuation data

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "registration": "",
        "currency": "",
        "vat_pricing": "",
        "vat_status": "",
        "prices": {
            "forecourt": "",
            "retail": "",
            "rrp": ""
        },
        "valuations": {},
        "metrics": {},
        "confidence": {}
    }
}

Competitors

GET Get Vehicle Competitors

GET /2.0/vehicles/{id}/competitors · scope vehicle-competitors:read

Retrieve internal vehicle competitor pricing data.

Parameters (16)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
trimquerystring-Filter by trim.
engine_minquerynumber-Filter by engine min.
engine_maxquerynumber-Filter by engine max.
fuelquerystring-Filter by fuel.
transmissionquerystring-Filter by transmission.
drivetrainquerystring-Filter by drivetrain.
doorsqueryinteger-Filter by doors.
mileage_minqueryinteger-Filter by mileage min.
mileage_maxqueryinteger-Filter by mileage max.
year_minqueryinteger-Filter by year min.
year_maxqueryinteger-Filter by year max.
conditionquerystring-Filter by condition.
postcodequerystring-Filter by postcode.
distancequeryinteger-Filter by distance.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKVehicle competitor pricing data

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "fields": {},
        "summary": {},
        "more": false,
        "own": {},
        "results": [
            {
                "registration": "",
                "own_vehicle": false,
                "match": false,
                "data": {},
                "photo": [
                    ""
                ],
                "advertiser": {},
                "metadata": {},
                "optional_extras": [
                    ""
                ],
                "comparison": {
                    "valuation": "0.00",
                    "price_difference": "0.00",
                    "price_difference_percentage": 0,
                    "price_difference_band": "light",
                    "forecourt_day": 0,
                    "distance": ""
                }
            }
        ]
    }
}

Status

PATCH Change Vehicle Status

PATCH /2.0/vehicles/{id}/status · scope vehicles:write

Change a vehicle's status under the same process constraints as the dashboard. Accepts draft, for-sale or deleted. Reserved and sold are NOT settable here: use POST /vehicles/{id}/reserve to reserve and create/pay a sale invoice to sell. To take a draft to for-sale, publish it via PUT /vehicles/{id}/channels. A reserved vehicle must have its reservation cancelled first.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
statusenumYesTarget status.deleted
{
    "status": "deleted"
}
Responses
StatusDescription
200 OKChange Vehicle Status

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "country": "UK",
        "registration": "EO68NRJ",
        "url": "bmw-3-series-320i-m-sport-saloon-4dr-auto",
        "url_full": "https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/",
        "type": "in-stock",
        "created": 1779974135,
        "updated": 1781303332,
        "status": {
            "id": 2,
            "name": "for-sale",
            "label": "For Sale"
        },
        "owner": "",
        "parent": 0,
        "data": {
            "vehicle": {
                "type": "Car",
                "make": "BMW",
                "model": "3 Series",
                "generation": "Saloon (2019 - 2023)",
                "derivative": "320i M Sport 4dr Auto",
                "trim": "M Sport",
                "engine_size": "2.0",
                "body": "Saloon",
                "colour": "Black",
                "colour_name": "Sapphire Black",
                "fuel": "Petrol",
                "transmission": "Automatic",
                "drivetrain": "RWD",
                "seats": 5,
                "doors": 5,
                "wheelbase": "LWB",
                "cab_type": "Double Cab",
                "mileage": 38450,
                "registered": "2020-03-01",
                "category": "Tractor",
                "driver_position": "RHD",
                "interior_upholstery": "Leather",
                "interior_colour": "Black",
                "exterior_finish": "Metallic",
                "group": "Demo Fleet",
                "hour": "",
                "bedroom_layout": "Fixed island bed",
                "end_layout": "End washroom",
                "bedroom": 2,
                "berth": 4,
                "seat_belt": 4,
                "wheelchair": "No"
            },
            "option": {
                "option_custom": [
                    "12 Month Warranty"
                ],
                "attention": "Full Service History",
                "description": "One owner from new, full BMW service history.",
                "website": "<p>One owner from new.</p>",
                "feature": {}
            },
            "history": {
                "previous_owner": 1,
                "keys": 2,
                "v5": "Yes",
                "year": 2020,
                "condition": "Used",
                "condition_interior": "Good",
                "condition_exterior": "Good",
                "condition_tyre": "Good",
                "service_history": "Full",
                "service_last": "2025-09-01",
                "service_miles": 36000,
                "mot_expiry": "2026-03-01",
                "mot_year": "Yes",
                "mot_insurance": "No",
                "warranty_expiry": "2026-03-01",
                "warranty_month": 12,
                "warranty_battery_month": 60,
                "service_note": "Serviced at 12k and 24k miles."
            },
            "stock": {
                "reference": "REF-1024",
                "number": "STK1024",
                "location": "Main Forecourt",
                "notes": "Awaiting valet.",
                "vin": "WBA8E9105HK000000",
                "engine_number": "B47D20A",
                "key_number": "K12345",
                "origin": "Part Exchange",
                "vat": "Inc VAT",
                "vat_pricing": "Inc. VAT",
                "due_in_date": "2026-06-20",
                "forecourt_date": "2026-06-12",
                "price_website": "12500.00",
                "price_channel": "13495.00",
                "price_reserve": "12000.00",
                "price_auction_start": "10000.00",
                "price_auction_reserve": "11000.00",
                "price_auction_buy_now": "13000.00",
                "price_auction_duration": "7 Days",
                "price_auction_dealerway_type": "Buy Now",
                "price_rrp": "24995.00",
                "price_poa": false,
                "funding_provider": "Close Brothers",
                "funding_provider_id": 42,
                "funding_provider_total": "8000.00",
                "stock_quantity": 1,
                "stock_variation": {},
                "purchase_date": "2026-01-15",
                "purchase_invoice": "PINV-2048",
                "purchase_supplier": "BCA Auction",
                "purchase_supplier_id": 30418,
                "purchase_supplier_invoice": "BCA-99812",
                "purchase_price": "9000.00",
                "purchase_price_vat": "0.00",
                "purchase_price_total": "9000.00",
                "purchase_cost": "450.00",
                "purchase_cost_vat": "90.00",
                "purchase_cost_total": "540.00",
                "purchase_value": "9450.00",
                "purchase_value_vat": "90.00",
                "purchase_value_total": "9540.00",
                "purchase_cost_data": [
                    {
                        "type": "",
                        "supplier": "",
                        "cost": "0.00",
                        "vat": "0.00",
                        "invoice": "",
                        "reference": "",
                        "date": "2026-01-01",
                        "id": "",
                        "total": "0.00"
                    }
                ]
            },
            "spec": {
                "performance": {
                    "top_speed": 155,
                    "zero_sixty": 5.8
                },
                "engine": {
                    "make": "BMW",
                    "cylinders": 4,
                    "capacity": 1998,
                    "bhp": 181,
                    "ps": 184,
                    "nm": 300,
                    "gears": 8
                },
                "battery": {
                    "range": 239,
                    "kwh": 58,
                    "charge_time": "8h 15m",
                    "health": 100
                },
                "other": {
                    "axles": 2,
                    "country": "GB",
                    "sector": "Retail"
                },
                "insurance": {
                    "group": "21E",
                    "code": "21E"
                },
                "fuel": {
                    "mpg_combined": 48.7,
                    "emission_co2": 132,
                    "ulez": true,
                    "caz": true
                },
                "size": {
                    "length": 4709,
                    "width": 2073,
                    "height": 1442,
                    "wheelbase": 2851,
                    "kerb_weight": 1545,
                    "boot_seats_up": 480
                }
            },
            "appraisal": {
                "details": {
                    "customer_id": "4471",
                    "customer": "Ada Buyer"
                },
                "calculation": {
                    "offer": "9500.00",
                    "finance_settlement": "2000.00"
                },
                "confirm": {
                    "offer": "9500.00",
                    "expiry": "2026-09-06",
                    "appraised_at": 1756137600,
                    "agreed_amount": "9250.00",
                    "decision": "accepted",
                    "decision_at": 1756224000,
                    "stock_id": "18342",
                    "stock_tag": "a1b2c3d4"
                }
            },
            "lookup": {
                "dvla": {
                    "make": "BMW",
                    "colour": "BLACK",
                    "fuel_type": "PETROL",
                    "year_of_manufacture": 2020,
                    "tax_status": "Taxed"
                },
                "dvsa": {
                    "mot_tests": [
                        {
                            "completed_date": "2025-03-01",
                            "test_result": "PASSED",
                            "odometer_value": 36000
                        }
                    ]
                },
                "check": {
                    "stolen": false,
                    "finance": false,
                    "written_off": false,
                    "previous_keepers": 1
                }
            },
            "tag": [
                {
                    "name": "Service",
                    "checked": false,
                    "colour": "primary",
                    "type": "check"
                }
            ],
            "finance": {
                "example_monthly": "507.75",
                "example": {
                    "cash_price": "20000.00",
                    "total_deposit": "2000.00",
                    "total_credit": "18000.00",
                    "first_payment": "507.75",
                    "monthly_payment": "507.75",
                    "total_monthly_payments": 25,
                    "final_payment": "7856.00",
                    "term": 27,
                    "admin_fee": "0.00",
                    "option_purchase_fee": "10.00",
                    "interest_charge": "3057.50",
                    "total_payable": "23057.50",
                    "fixed_interest_rate": 10.36,
                    "representative_apr": 10.9
                }
            }
        },
        "media": {
            "photo": [
                "m7Yk2p9q",
                "r3Tn8w1z"
            ],
            "video": [
                "v9Lp4m2x"
            ],
            "youtube": [
                "dQw4w9WgXcQ"
            ],
            "photo_spin": [
                "s5Qw8r3t"
            ]
        }
    }
}

Sell

POST Mark a Sold Vehicle Complete

POST /2.0/vehicles/{id}/sell/complete · scope vehicles:write

Mark a sold vehicle's handover/delivery complete (sets data.sold.complete and reads as status "complete"). Optionally records the handover date, handover staff, sale channel, finance end date, commissions and the handover checklist. Runs the deal/checkout handover the first time and releases any assigned key. The vehicle must already be sold (a paid sale invoice).

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
datestring-Handover/completion date (YYYY-MM-DD or Unix timestamp). Defaults to now.2026-06-13
byarray of integer-Staff user ids who handled the handover (see GET /reference/staff-users).[7]
channelstring-Sale channel label.Showroom
finance_endstring-Finance agreement end date (YYYY-MM-DD).2029-06-13
checklistarray of string-Handover checklist items handed over; each must be one of the business handover checklist options.["Logbook (V5C2)","Spare Key"]
commissionsarray of object-Commission rows recorded against the sale.
{
    "date": "2026-06-13",
    "by": [
        7
    ],
    "channel": "Showroom",
    "finance_end": "2029-06-13",
    "checklist": [
        "Logbook (V5C2)",
        "Spare Key"
    ],
    "commissions": [
        {
            "category": "",
            "provider": "",
            "cost": 0,
            "vat": 0,
            "total": 0
        }
    ]
}
Responses
StatusDescription
200 OKMark a Sold Vehicle Complete

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "country": "UK",
        "registration": "EO68NRJ",
        "url": "bmw-3-series-320i-m-sport-saloon-4dr-auto",
        "url_full": "https://example-motors.co.uk/vehicles/AB12CDEF/bmw-3-series-320i-m-sport-saloon-4dr-auto/",
        "type": "in-stock",
        "created": 1779974135,
        "updated": 1781303332,
        "status": {
            "id": 2,
            "name": "for-sale",
            "label": "For Sale"
        },
        "owner": "",
        "parent": 0,
        "data": {
            "vehicle": {
                "type": "Car",
                "make": "BMW",
                "model": "3 Series",
                "generation": "Saloon (2019 - 2023)",
                "derivative": "320i M Sport 4dr Auto",
                "trim": "M Sport",
                "engine_size": "2.0",
                "body": "Saloon",
                "colour": "Black",
                "colour_name": "Sapphire Black",
                "fuel": "Petrol",
                "transmission": "Automatic",
                "drivetrain": "RWD",
                "seats": 5,
                "doors": 5,
                "wheelbase": "LWB",
                "cab_type": "Double Cab",
                "mileage": 38450,
                "registered": "2020-03-01",
                "category": "Tractor",
                "driver_position": "RHD",
                "interior_upholstery": "Leather",
                "interior_colour": "Black",
                "exterior_finish": "Metallic",
                "group": "Demo Fleet",
                "hour": "",
                "bedroom_layout": "Fixed island bed",
                "end_layout": "End washroom",
                "bedroom": 2,
                "berth": 4,
                "seat_belt": 4,
                "wheelchair": "No"
            },
            "option": {
                "option_custom": [
                    "12 Month Warranty"
                ],
                "attention": "Full Service History",
                "description": "One owner from new, full BMW service history.",
                "website": "<p>One owner from new.</p>",
                "feature": {}
            },
            "history": {
                "previous_owner": 1,
                "keys": 2,
                "v5": "Yes",
                "year": 2020,
                "condition": "Used",
                "condition_interior": "Good",
                "condition_exterior": "Good",
                "condition_tyre": "Good",
                "service_history": "Full",
                "service_last": "2025-09-01",
                "service_miles": 36000,
                "mot_expiry": "2026-03-01",
                "mot_year": "Yes",
                "mot_insurance": "No",
                "warranty_expiry": "2026-03-01",
                "warranty_month": 12,
                "warranty_battery_month": 60,
                "service_note": "Serviced at 12k and 24k miles."
            },
            "stock": {
                "reference": "REF-1024",
                "number": "STK1024",
                "location": "Main Forecourt",
                "notes": "Awaiting valet.",
                "vin": "WBA8E9105HK000000",
                "engine_number": "B47D20A",
                "key_number": "K12345",
                "origin": "Part Exchange",
                "vat": "Inc VAT",
                "vat_pricing": "Inc. VAT",
                "due_in_date": "2026-06-20",
                "forecourt_date": "2026-06-12",
                "price_website": "12500.00",
                "price_channel": "13495.00",
                "price_reserve": "12000.00",
                "price_auction_start": "10000.00",
                "price_auction_reserve": "11000.00",
                "price_auction_buy_now": "13000.00",
                "price_auction_duration": "7 Days",
                "price_auction_dealerway_type": "Buy Now",
                "price_rrp": "24995.00",
                "price_poa": false,
                "funding_provider": "Close Brothers",
                "funding_provider_id": 42,
                "funding_provider_total": "8000.00",
                "stock_quantity": 1,
                "stock_variation": {},
                "purchase_date": "2026-01-15",
                "purchase_invoice": "PINV-2048",
                "purchase_supplier": "BCA Auction",
                "purchase_supplier_id": 30418,
                "purchase_supplier_invoice": "BCA-99812",
                "purchase_price": "9000.00",
                "purchase_price_vat": "0.00",
                "purchase_price_total": "9000.00",
                "purchase_cost": "450.00",
                "purchase_cost_vat": "90.00",
                "purchase_cost_total": "540.00",
                "purchase_value": "9450.00",
                "purchase_value_vat": "90.00",
                "purchase_value_total": "9540.00",
                "purchase_cost_data": [
                    {
                        "type": "",
                        "supplier": "",
                        "cost": "0.00",
                        "vat": "0.00",
                        "invoice": "",
                        "reference": "",
                        "date": "2026-01-01",
                        "id": "",
                        "total": "0.00"
                    }
                ]
            },
            "spec": {
                "performance": {
                    "top_speed": 155,
                    "zero_sixty": 5.8
                },
                "engine": {
                    "make": "BMW",
                    "cylinders": 4,
                    "capacity": 1998,
                    "bhp": 181,
                    "ps": 184,
                    "nm": 300,
                    "gears": 8
                },
                "battery": {
                    "range": 239,
                    "kwh": 58,
                    "charge_time": "8h 15m",
                    "health": 100
                },
                "other": {
                    "axles": 2,
                    "country": "GB",
                    "sector": "Retail"
                },
                "insurance": {
                    "group": "21E",
                    "code": "21E"
                },
                "fuel": {
                    "mpg_combined": 48.7,
                    "emission_co2": 132,
                    "ulez": true,
                    "caz": true
                },
                "size": {
                    "length": 4709,
                    "width": 2073,
                    "height": 1442,
                    "wheelbase": 2851,
                    "kerb_weight": 1545,
                    "boot_seats_up": 480
                }
            },
            "appraisal": {
                "details": {
                    "customer_id": "4471",
                    "customer": "Ada Buyer"
                },
                "calculation": {
                    "offer": "9500.00",
                    "finance_settlement": "2000.00"
                },
                "confirm": {
                    "offer": "9500.00",
                    "expiry": "2026-09-06",
                    "appraised_at": 1756137600,
                    "agreed_amount": "9250.00",
                    "decision": "accepted",
                    "decision_at": 1756224000,
                    "stock_id": "18342",
                    "stock_tag": "a1b2c3d4"
                }
            },
            "lookup": {
                "dvla": {
                    "make": "BMW",
                    "colour": "BLACK",
                    "fuel_type": "PETROL",
                    "year_of_manufacture": 2020,
                    "tax_status": "Taxed"
                },
                "dvsa": {
                    "mot_tests": [
                        {
                            "completed_date": "2025-03-01",
                            "test_result": "PASSED",
                            "odometer_value": 36000
                        }
                    ]
                },
                "check": {
                    "stolen": false,
                    "finance": false,
                    "written_off": false,
                    "previous_keepers": 1
                }
            },
            "tag": [
                {
                    "name": "Service",
                    "checked": false,
                    "colour": "primary",
                    "type": "check"
                }
            ],
            "finance": {
                "example_monthly": "507.75",
                "example": {
                    "cash_price": "20000.00",
                    "total_deposit": "2000.00",
                    "total_credit": "18000.00",
                    "first_payment": "507.75",
                    "monthly_payment": "507.75",
                    "total_monthly_payments": 25,
                    "final_payment": "7856.00",
                    "term": 27,
                    "admin_fee": "0.00",
                    "option_purchase_fee": "10.00",
                    "interest_charge": "3057.50",
                    "total_payable": "23057.50",
                    "fixed_interest_rate": 10.36,
                    "representative_apr": 10.9
                }
            }
        },
        "media": {
            "photo": [
                "m7Yk2p9q",
                "r3Tn8w1z"
            ],
            "video": [
                "v9Lp4m2x"
            ],
            "youtube": [
                "dQw4w9WgXcQ"
            ],
            "photo_spin": [
                "s5Qw8r3t"
            ]
        }
    }
}

Describe

POST Generate Vehicle Description

POST /2.0/vehicles/{id}/describe · scope vehicle-descriptions:write

Generate AI advert description or attention text.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
targetenum-What to generate: the long advert description (default) or the short attention grabber.
applyboolean-When true, save the generated text to the vehicle (description writes option.description + the rendered website HTML; attention writes option.attention). Defaults to false (preview only).
lengthinteger-Maximum character length for the attention grabber (20-120, defaults to 30). Only applies when target is attention.
optionsarray of string-Optional list of selling points / feature hints to steer the generated copy.
{
    "target": "description",
    "apply": false,
    "length": 0,
    "options": [
        ""
    ]
}
Responses
StatusDescription
200 OKGenerated vehicle advert text

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "target": "description",
        "text": "",
        "html": "",
        "suggestions": [
            ""
        ],
        "applied": false
    }
}

Media

GET List Vehicle Media

GET /2.0/vehicles/{id}/media · scope vehicle-media:read

List the media attached to a vehicle.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKVehicle media list

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": "",
            "type": "photo",
            "position": 0,
            "facing": "exterior",
            "caption": "",
            "group": "",
            "filename": "",
            "extension": "",
            "duration": 0,
            "url": "",
            "thumbnail_url": "",
            "youtube_id": "",
            "options": {
                "watermark": false,
                "brand_first": {
                    "enable": false,
                    "position": ""
                },
                "brand_second": {
                    "enable": false,
                    "position": ""
                },
                "brand_reserve": {
                    "enable": false,
                    "position": ""
                },
                "brand_sold": {
                    "enable": false,
                    "position": ""
                },
                "ribbon": {
                    "enable": false,
                    "position": "",
                    "color": "",
                    "text_color": "",
                    "text": ""
                },
                "banner": {
                    "enable": false,
                    "position": "",
                    "color": "",
                    "text_color": "",
                    "text": ""
                },
                "background": "",
                "feature_position": ""
            }
        }
    ]
}

POST Add Vehicle Media

POST /2.0/vehicles/{id}/media · scope vehicle-media:write

Attach simple vehicle media. Accepts EITHER a JSON body with base64 file data (this schema) OR a multipart/form-data upload with the file part named "file" plus optional text fields (type, caption, group, filename, extension); use multipart for large media (mp4/mov) to avoid base64 inflation and request-size limits.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
filestring-Base64 image/video data (optionally a data: URL).
filenamestring-Original filename (used for display and to infer the extension).front.jpg
extensionenum-File extension when not derivable from the filename.jpg
typeenum-Media collection. photo (default) is a normal photo/video; exterior_360 and interior_360 are 360 spin frames. YouTube is detected from youtube_id/url and only valid for photo.photo
captionstring-Image caption / alt text.
groupstring-Optional media group label for organising images.
youtube_urlstring-A YouTube watch/share URL to attach as a video (the id is extracted from it). Use this or youtube_id instead of file.https://www.youtube.com/watch?v=dQw4w9WgXcQ
youtube_idstring-A YouTube video id to attach directly.dQw4w9WgXcQ
{
    "file": "",
    "filename": "front.jpg",
    "extension": "jpg",
    "type": "photo",
    "caption": "",
    "group": "",
    "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "youtube_id": "dQw4w9WgXcQ"
}
Responses
StatusDescription
201 CreatedVehicle media attached

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "type": "photo",
        "position": 0,
        "facing": "exterior",
        "caption": "",
        "group": "",
        "filename": "",
        "extension": "",
        "duration": 0,
        "url": "",
        "thumbnail_url": "",
        "youtube_id": "",
        "options": {
            "watermark": false,
            "brand_first": {
                "enable": false,
                "position": ""
            },
            "brand_second": {
                "enable": false,
                "position": ""
            },
            "brand_reserve": {
                "enable": false,
                "position": ""
            },
            "brand_sold": {
                "enable": false,
                "position": ""
            },
            "ribbon": {
                "enable": false,
                "position": "",
                "color": "",
                "text_color": "",
                "text": ""
            },
            "banner": {
                "enable": false,
                "position": "",
                "color": "",
                "text_color": "",
                "text": ""
            },
            "background": "",
            "feature_position": ""
        }
    }
}

PATCH Edit Vehicle Media

PATCH /2.0/vehicles/{id}/media/{media_id} · scope vehicle-media:write

Edit a regular photo's caption and branding/watermark/background overlay options. The image is re-processed.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
media_idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
captionstring-Image caption / alt text. Empty string clears it.
groupstring-Media group label. Empty string clears it.
optionsobject-Branding/watermark/background overlay options. Unspecified overlays keep their current state. Reserved and sold overlays are not settable per image: they are derived from the vehicle's own reserved/sold state and applied automatically to its first photo.
options.watermarkboolean-Apply the business watermark.
options.brand_firstobject-Primary brand logo overlay. position: top_left, top, top_right, bottom_left, bottom, bottom_right.
options.brand_first.enableboolean-Whether the overlay is shown.
options.brand_first.positionenum-Overlay position on the image.
options.brand_secondobject-Secondary brand logo overlay.
options.brand_second.enableboolean-Whether the overlay is shown.
options.brand_second.positionenum-Overlay position on the image.
options.ribbonobject-Corner ribbon. position: top_left, top_right, bottom_left, bottom_right.
options.ribbon.enableboolean-Whether the overlay is shown.
options.ribbon.positionstring-Overlay position on the image (see the parent description for allowed values).
options.ribbon.colorstring-Background hex colour.
options.ribbon.text_colorstring-Text hex colour.
options.ribbon.textstring-Overlay text.
options.bannerobject-Full-width banner. position: top, bottom.
options.banner.enableboolean-Whether the overlay is shown.
options.banner.positionstring-Overlay position on the image (see the parent description for allowed values).
options.banner.colorstring-Background hex colour.
options.banner.text_colorstring-Text hex colour.
options.banner.textstring-Overlay text.
options.backgroundstring or null-Configured background filename (from /my media backgrounds) to composite behind a cut-out of the vehicle, or null to remove.
options.feature_positionstring-Website feature placement for this image.
{
    "caption": "",
    "group": "",
    "options": {
        "watermark": false,
        "brand_first": {
            "enable": false,
            "position": "top_left"
        },
        "brand_second": {
            "enable": false,
            "position": "top_left"
        },
        "ribbon": {
            "enable": false,
            "position": "",
            "color": "",
            "text_color": "",
            "text": ""
        },
        "banner": {
            "enable": false,
            "position": "",
            "color": "",
            "text_color": "",
            "text": ""
        },
        "background": "",
        "feature_position": ""
    }
}
Responses
StatusDescription
200 OKEdit Vehicle Media

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "type": "photo",
        "position": 0,
        "facing": "exterior",
        "caption": "",
        "group": "",
        "filename": "",
        "extension": "",
        "duration": 0,
        "url": "",
        "thumbnail_url": "",
        "youtube_id": "",
        "options": {
            "watermark": false,
            "brand_first": {
                "enable": false,
                "position": ""
            },
            "brand_second": {
                "enable": false,
                "position": ""
            },
            "brand_reserve": {
                "enable": false,
                "position": ""
            },
            "brand_sold": {
                "enable": false,
                "position": ""
            },
            "ribbon": {
                "enable": false,
                "position": "",
                "color": "",
                "text_color": "",
                "text": ""
            },
            "banner": {
                "enable": false,
                "position": "",
                "color": "",
                "text_color": "",
                "text": ""
            },
            "background": "",
            "feature_position": ""
        }
    }
}

DELETE Delete Vehicle Media

DELETE /2.0/vehicles/{id}/media/{media_id} · scope vehicle-media:delete

Delete a vehicle media item.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
media_idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKVehicle media deleted

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Test Drives

GET List Vehicle Test Drives

GET /2.0/vehicles/{id}/test-drives · scope vehicle-drives:read

List a vehicle's active test drive (if any) and its test-drive history. Also covers Book In / Loan Car for those stock types.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKList Vehicle Test Drives

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "active": {
            "code": "",
            "active": false,
            "contact": 0,
            "license_number": "",
            "license_code": "",
            "ni": "",
            "dob": "2026-01-01",
            "license_checked": "2026-01-01",
            "license_checked_by": "",
            "return_date": "2026-01-01",
            "return_time": "",
            "fuel": 0,
            "note": "",
            "condition": "",
            "location": 0,
            "location_name": "",
            "consent": false,
            "photo": [
                {
                    "filename": "",
                    "video": false,
                    "url": "",
                    "thumbnail_url": ""
                }
            ],
            "esign": {
                "name": "",
                "signature": "",
                "signed": 0,
                "ip": "",
                "browser": "",
                "terms_md5": "",
                "terms_sha1": ""
            },
            "started": 0,
            "ended": 0
        },
        "history": [
            {
                "code": "",
                "active": false,
                "contact": 0,
                "license_number": "",
                "license_code": "",
                "ni": "",
                "dob": "2026-01-01",
                "license_checked": "2026-01-01",
                "license_checked_by": "",
                "return_date": "2026-01-01",
                "return_time": "",
                "fuel": 0,
                "note": "",
                "condition": "",
                "location": 0,
                "location_name": "",
                "consent": false,
                "photo": [
                    {
                        "filename": "",
                        "video": false,
                        "url": "",
                        "thumbnail_url": ""
                    }
                ],
                "esign": {
                    "name": "",
                    "signature": "",
                    "signed": 0,
                    "ip": "",
                    "browser": "",
                    "terms_md5": "",
                    "terms_sha1": ""
                },
                "started": 0,
                "ended": 0
            }
        ]
    }
}

POST Start a Vehicle Test Drive

POST /2.0/vehicles/{id}/test-drives · scope vehicle-drives:write

Start a test drive (or Book In / Loan Car). Any currently active drive is archived to history first.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
contactinteger-Contact id of the driver (optional).110166
license_numberstring-Driving licence number (required unless the stock type skips licence checks).SMITH901234AB9CD
license_codestring-Licence check code.Ab12 3Cd4 5Ef6
nistring-National insurance number.QQ123456C
dobstring (date)-Date of birth (YYYY-MM-DD).1990-05-12
license_checkedstring (date)-Date the licence was checked (YYYY-MM-DD).2026-06-12
license_checked_bystring-Business user id who checked the licence.3
return_datestring (date)-Intended return date (YYYY-MM-DD).2026-06-20
return_timestring-Intended return time (HH:MM). Defaults to 23:59 when a return date is given without a time.17:30
fuelinteger-Fuel level at handover (0-100%).75
notestring-Free-text note recorded against the drive.Lunchtime test drive.
conditionstring-Id of a vehicle condition report to attach.
locationinteger-Business location id for the handover.1
consentboolean-Driver consent (required except for stock types that skip consent).true
{
    "contact": 110166,
    "license_number": "SMITH901234AB9CD",
    "license_code": "Ab12 3Cd4 5Ef6",
    "ni": "QQ123456C",
    "dob": "1990-05-12",
    "license_checked": "2026-06-12",
    "license_checked_by": "3",
    "return_date": "2026-06-20",
    "return_time": "17:30",
    "fuel": 75,
    "note": "Lunchtime test drive.",
    "condition": "",
    "location": 1,
    "consent": true
}
Responses
StatusDescription
200 OKStart a Vehicle Test Drive

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "code": "",
        "active": false,
        "contact": 0,
        "license_number": "",
        "license_code": "",
        "ni": "",
        "dob": "2026-01-01",
        "license_checked": "2026-01-01",
        "license_checked_by": "",
        "return_date": "2026-01-01",
        "return_time": "",
        "fuel": 0,
        "note": "",
        "condition": "",
        "location": 0,
        "location_name": "",
        "consent": false,
        "photo": [
            {
                "filename": "",
                "video": false,
                "url": "",
                "thumbnail_url": ""
            }
        ],
        "esign": {
            "name": "",
            "signature": "",
            "signed": 0,
            "ip": "",
            "browser": "",
            "terms_md5": "",
            "terms_sha1": ""
        },
        "started": 0,
        "ended": 0
    }
}

POST End the Active Test Drive

POST /2.0/vehicles/{id}/test-drives/end · scope vehicle-drives:write

End the active test drive, recording the return and moving it to history.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKEnd the Active Test Drive

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "code": "",
        "active": false,
        "contact": 0,
        "license_number": "",
        "license_code": "",
        "ni": "",
        "dob": "2026-01-01",
        "license_checked": "2026-01-01",
        "license_checked_by": "",
        "return_date": "2026-01-01",
        "return_time": "",
        "fuel": 0,
        "note": "",
        "condition": "",
        "location": 0,
        "location_name": "",
        "consent": false,
        "photo": [
            {
                "filename": "",
                "video": false,
                "url": "",
                "thumbnail_url": ""
            }
        ],
        "esign": {
            "name": "",
            "signature": "",
            "signed": 0,
            "ip": "",
            "browser": "",
            "terms_md5": "",
            "terms_sha1": ""
        },
        "started": 0,
        "ended": 0
    }
}

POST E-Sign the Active Test Drive

POST /2.0/vehicles/{id}/test-drives/esign · scope vehicle-drives:write

Record the customer's signed agreement to the test-drive terms.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
signaturestringYesSignature image as a base64 data URL (data:image/...).data:image/png;base64,iVBORw0KGgo...
namestringYesPrinted name of the signatory.JOHN SMITH
{
    "signature": "data:image/png;base64,iVBORw0KGgo...",
    "name": "JOHN SMITH"
}
Responses
StatusDescription
200 OKE-Sign the Active Test Drive

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "code": "",
        "active": false,
        "contact": 0,
        "license_number": "",
        "license_code": "",
        "ni": "",
        "dob": "2026-01-01",
        "license_checked": "2026-01-01",
        "license_checked_by": "",
        "return_date": "2026-01-01",
        "return_time": "",
        "fuel": 0,
        "note": "",
        "condition": "",
        "location": 0,
        "location_name": "",
        "consent": false,
        "photo": [
            {
                "filename": "",
                "video": false,
                "url": "",
                "thumbnail_url": ""
            }
        ],
        "esign": {
            "name": "",
            "signature": "",
            "signed": 0,
            "ip": "",
            "browser": "",
            "terms_md5": "",
            "terms_sha1": ""
        },
        "started": 0,
        "ended": 0
    }
}

POST Email the Test Drive Terms

POST /2.0/vehicles/{id}/test-drives/email · scope vehicle-drives:write

Email the test-drive terms summary to the active drive's contact.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKEmail the Test Drive Terms

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "code": "",
        "contact": 0,
        "email": "",
        "sent": false
    }
}

POST Attach a Test Drive Photo

POST /2.0/vehicles/{id}/test-drives/photo · scope vehicle-drives:write

Attach a photo or video (e.g. licence or condition image) to the active test drive. Accepts a JSON body with base64 file data (this schema) OR a multipart/form-data upload with the file part named "file" (recommended for large files).

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
filestringYesBase64 file data (optionally a data: URL).
filenamestring-Original filename (used for display and to infer the extension).drive-front.jpg
extensionenum-File extension when not derivable from the filename.jpg
{
    "file": "",
    "filename": "drive-front.jpg",
    "extension": "jpg"
}
Responses
StatusDescription
200 OKAttach a Test Drive Photo

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "filename": "",
        "video": false,
        "url": "",
        "thumbnail_url": ""
    }
}

Documents

GET List Vehicle Documents

GET /2.0/vehicles/{id}/documents · scope vehicle-documents:read

List the documents attached to a vehicle.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKList Vehicle Documents

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": "",
            "name": "",
            "description": "",
            "public": false,
            "extension": "",
            "mime": "",
            "size": 0,
            "size_label": "",
            "icon": "",
            "uploaded": 0
        }
    ]
}

POST Upload a Vehicle Document

POST /2.0/vehicles/{id}/documents · scope vehicle-documents:write

Upload a document (base64 file) to a vehicle, optionally public with a description.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
filestringYesBase64 file data (optionally a data: URL).data:application/pdf;base64,JVBERi0xLjQK...
filenamestring-Original filename (used for display and to infer the extension).service-history.pdf
extensionenum-File extension when not derivable from the filename.pdf
descriptionstring-Document description (required when public).Full service history
publicboolean-Whether the document is shown on the public website vehicle page. Defaults to false.false
{
    "file": "data:application/pdf;base64,JVBERi0xLjQK...",
    "filename": "service-history.pdf",
    "extension": "pdf",
    "description": "Full service history",
    "public": false
}
Responses
StatusDescription
200 OKUpload a Vehicle Document

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "name": "",
        "description": "",
        "public": false,
        "extension": "",
        "mime": "",
        "size": 0,
        "size_label": "",
        "icon": "",
        "uploaded": 0
    }
}

GET Download a Vehicle Document

GET /2.0/vehicles/{id}/documents/{document_id}/download · scope vehicle-documents:read

Download a vehicle document's file content (base64 encoded).

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
document_idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKDownload a Vehicle Document

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "name": "",
        "extension": "",
        "mime": "",
        "size": 0,
        "encoding": "base64",
        "content": ""
    }
}

PATCH Update a Vehicle Document

PATCH /2.0/vehicles/{id}/documents/{document_id} · scope vehicle-documents:write

Update a document's description or public/private status.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
document_idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
descriptionstring-Document description (required when public).Full service history
publicboolean-A description is required when setting public to true.
{
    "description": "Full service history",
    "public": false
}
Responses
StatusDescription
200 OKUpdate a Vehicle Document

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "name": "",
        "description": "",
        "public": false,
        "extension": "",
        "mime": "",
        "size": 0,
        "size_label": "",
        "icon": "",
        "uploaded": 0
    }
}

DELETE Delete a Vehicle Document

DELETE /2.0/vehicles/{id}/documents/{document_id} · scope vehicle-documents:delete

Delete a vehicle document and its file.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
document_idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKDelete a Vehicle Document

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

Tags

GET List Vehicle Tags

GET /2.0/vehicles/{id}/tags · scope vehicles:read

List the tags applied to a vehicle, plus the tags available for its stock type.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKList Vehicle Tags

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "applied": [
            {
                "name": "Hot lead",
                "checked": false,
                "colour": "success",
                "type": "default"
            }
        ],
        "available": [
            {
                "name": "",
                "colour": "",
                "type": "default",
                "defaulted": false
            }
        ]
    }
}

PUT Set Vehicle Tags

PUT /2.0/vehicles/{id}/tags · scope vehicles:write

Replace the tags applied to a vehicle. Each tag name must be available for the vehicle's stock type.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
tagsarray of stringYesThe full set of tags to apply. Each item is a tag name string, or an object { name, checked }.[{"name":"MOT","checked":true},{"name":"Valet","checked":false}]
{
    "tags": [
        {
            "name": "MOT",
            "checked": true
        },
        {
            "name": "Valet",
            "checked": false
        }
    ]
}
Responses
StatusDescription
200 OKSet Vehicle Tags

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "applied": [
            {
                "name": "Hot lead",
                "checked": false,
                "colour": "success",
                "type": "default"
            }
        ],
        "available": [
            {
                "name": "",
                "colour": "",
                "type": "default",
                "defaulted": false
            }
        ]
    }
}

Channels

GET List Vehicle Sales Channels

GET /2.0/vehicles/{id}/channels · scope vehicles:read

List the sales channels available to the vehicle with their publish state (enabled, removing, offline, error), plus the per-vehicle AutoTrader/Dealerway publishing options.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKList Vehicle Sales Channels

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "published": false,
        "channels": [
            {
                "id": "autotrader",
                "name": "AutoTrader",
                "category": "Marketplace",
                "enabled": false,
                "removing": false,
                "offline": false,
                "error": ""
            }
        ],
        "options": {
            "autotrader": {
                "advert": false,
                "advertiser": false,
                "profile": false,
                "locator": false,
                "demo": false,
                "poa": false,
                "exclude": false,
                "overwrite": false,
                "discrepancy": false
            },
            "dealerway": {
                "location": ""
            }
        }
    }
}

PUT Publish Vehicle to Sales Channels

PUT /2.0/vehicles/{id}/channels · scope vehicles:write

Set which sales channels the vehicle is published to (on/off) and/or update the publishing options. Publishing a draft vehicle moves it to for-sale; channels not listed are removed.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
channelsarray of string-The full set of channel ids the vehicle should be published to (e.g. website, autotrader, dealerway). Channels currently published but omitted here are removed. Each id must be available to the business (see GET /vehicles/{id}/channels). Publishing a draft vehicle moves it to for-sale.["website","autotrader"]
optionsobject-Per-vehicle publishing options, grouped per platform. Only the supplied platforms/fields are changed.
options.autotraderobject-AutoTrader publishing options.
options.autotrader.advertboolean-Publish the AutoTrader retail advert.true
options.autotrader.advertiserboolean-Include on the AutoTrader advertiser page.
options.autotrader.profileboolean-Include on the AutoTrader profile.
options.autotrader.locatorboolean-Include in the AutoTrader locator.
options.autotrader.demoboolean-Mark as ex-demonstrator.false
options.autotrader.poaboolean-Price on application (hide price on AutoTrader).
options.autotrader.excludeboolean-Exclude from the advert.
options.autotrader.overwriteboolean-Allow MotorDesk to overwrite third-party changes.
options.autotrader.discrepancyboolean-Ignore AutoTrader discrepancy warnings.
options.dealerwayobject-Dealerway publishing options.
options.dealerway.locationstring-Dealerway location id (from the business's configured Dealerway locations).
{
    "channels": [
        "website",
        "autotrader"
    ],
    "options": {
        "autotrader": {
            "advert": true,
            "advertiser": false,
            "profile": false,
            "locator": false,
            "demo": false,
            "poa": false,
            "exclude": false,
            "overwrite": false,
            "discrepancy": false
        },
        "dealerway": {
            "location": ""
        }
    }
}
Responses
StatusDescription
200 OKPublish Vehicle to Sales Channels

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "published": false,
        "channels": [
            {
                "id": "autotrader",
                "name": "AutoTrader",
                "category": "Marketplace",
                "enabled": false,
                "removing": false,
                "offline": false,
                "error": ""
            }
        ],
        "options": {
            "autotrader": {
                "advert": false,
                "advertiser": false,
                "profile": false,
                "locator": false,
                "demo": false,
                "poa": false,
                "exclude": false,
                "overwrite": false,
                "discrepancy": false
            },
            "dealerway": {
                "location": ""
            }
        }
    }
}

Reserve

GET Get Vehicle Reservation

GET /2.0/vehicles/{id}/reserve · scope vehicle-reserve:read

Read the vehicle's current reservation (customer, deposit, method, deposit invoice number), or reserved=false when not reserved.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKGet Vehicle Reservation

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "reserved": true,
        "cancelled": false,
        "credit_note": "000412",
        "reservation": {
            "customer": 60123,
            "method": "Bank Transfer",
            "deposit": 500,
            "transaction": "TXN-8841",
            "date": 1781303332,
            "reserved_at": 1781303332,
            "vat": true,
            "invoice": "001984",
            "credit_note": ""
        }
    }
}

POST Reserve a Vehicle

POST /2.0/vehicles/{id}/reserve · scope vehicle-reserve:write

Reserve a for-sale vehicle for a customer. Optionally takes a deposit, captured on a paid deposit invoice created through the invoice API. The vehicle reads as "Reserved" until the reservation is cancelled or the sale completes. Online/terminal payment capture is not handled by the API.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
customerintegerYesCustomer (contact) id to reserve for.60123
methodenumYesDeposit payment method. "No Payment" reserves without a deposit/invoice.Bank Transfer
depositnumber-Deposit amount (gross). Defaults to the vehicle's reserve price, then the business reserve deposit. Forced to 0 for "No Payment".500
datestring-Reservation date (YYYY-MM-DD or Unix timestamp). Defaults to today.2026-06-13
transactionstring-Payment reference recorded on the deposit invoice.TXN-8841
create_invoiceboolean-Whether to raise a paid deposit invoice for the deposit. Defaults to true. When false (or the method is "No Payment", or the deposit is 0) no invoice is raised, but the deposit amount and method are still recorded on the reservation, so cancellation has no invoice to credit.true
{
    "customer": 60123,
    "method": "Bank Transfer",
    "deposit": 500,
    "date": "2026-06-13",
    "transaction": "TXN-8841",
    "create_invoice": true
}
Responses
StatusDescription
200 OKReserve a Vehicle

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "reserved": true,
        "cancelled": false,
        "credit_note": "000412",
        "reservation": {
            "customer": 60123,
            "method": "Bank Transfer",
            "deposit": 500,
            "transaction": "TXN-8841",
            "date": 1781303332,
            "reserved_at": 1781303332,
            "vat": true,
            "invoice": "001984",
            "credit_note": ""
        }
    }
}

DELETE Cancel a Vehicle Reservation

DELETE /2.0/vehicles/{id}/reserve · scope vehicle-reserve:write

Cancel the reservation: the deposit invoice (if any) is fully credit-noted, the reservation is archived to history, and the vehicle returns to for-sale. No online/terminal refund is attempted.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKCancel a Vehicle Reservation

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "reserved": true,
        "cancelled": false,
        "credit_note": "000412",
        "reservation": {
            "customer": 60123,
            "method": "Bank Transfer",
            "deposit": 500,
            "transaction": "TXN-8841",
            "date": 1781303332,
            "reserved_at": 1781303332,
            "vat": true,
            "invoice": "001984",
            "credit_note": ""
        }
    }
}

Appraisal

POST Request an Appraisal Offer

POST /2.0/vehicles/{id}/appraisal/request-offer · scope vehicle-appraisals:write

Request that an offer be made on an appraisal awaiting one (raises the dashboard appraisal-request alert for staff who can confirm offers). Appraisal vehicles only.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRequest an Appraisal Offer

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "status": {
            "id": 2,
            "name": "appraised",
            "label": "Appraised"
        },
        "offer": {
            "offer": 8500,
            "max_offer": 9000,
            "agreed_amount": 8750,
            "expiry": "2026-06-30",
            "appraised_by": 7,
            "comments": "Minor kerbing to alloys.",
            "decision": ""
        },
        "stock": {
            "id": 84599,
            "tag": "ZZ99YYXX"
        },
        "requested": true
    }
}

POST Confirm an Appraisal Offer

POST /2.0/vehicles/{id}/appraisal/offer · scope vehicle-appraisals:write

Confirm an offer on an appraisal (Added -> Appraised), recording the offer amount, optional max offer, expiry and the appraising staff member. Appraisal vehicles only.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
offernumberYesOffer amount (greater than zero).8500
max_offernumber-Optional ceiling the offer can be raised to on acceptance; must be >= offer.9000
expirystringYesOffer expiry date (YYYY-MM-DD), today or later.2026-06-30
appraised_byintegerYesStaff user id who appraised the vehicle (see GET /reference/staff-users).7
commentsstring-Optional appraisal comments.Minor kerbing to alloys.
{
    "offer": 8500,
    "max_offer": 9000,
    "expiry": "2026-06-30",
    "appraised_by": 7,
    "comments": "Minor kerbing to alloys."
}
Responses
StatusDescription
200 OKConfirm an Appraisal Offer

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "status": {
            "id": 2,
            "name": "appraised",
            "label": "Appraised"
        },
        "offer": {
            "offer": 8500,
            "max_offer": 9000,
            "agreed_amount": 8750,
            "expiry": "2026-06-30",
            "appraised_by": 7,
            "comments": "Minor kerbing to alloys.",
            "decision": ""
        },
        "stock": {
            "id": 84599,
            "tag": "ZZ99YYXX"
        },
        "requested": true
    }
}

POST Accept an Appraisal Offer

POST /2.0/vehicles/{id}/appraisal/accept · scope vehicle-appraisals:write

Accept an appraised offer at an agreed amount (Appraised -> Accepted). Creates the stock vehicle from the appraisal and returns its id/tag. The agreed amount must be between the confirmed offer and any max offer. Appraisal vehicles only.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
agreed_amountnumberYesFinal agreed purchase amount. Must be between the confirmed offer and any max offer.8750
{
    "agreed_amount": 8750
}
Responses
StatusDescription
200 OKAccept an Appraisal Offer

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "status": {
            "id": 2,
            "name": "appraised",
            "label": "Appraised"
        },
        "offer": {
            "offer": 8500,
            "max_offer": 9000,
            "agreed_amount": 8750,
            "expiry": "2026-06-30",
            "appraised_by": 7,
            "comments": "Minor kerbing to alloys.",
            "decision": ""
        },
        "stock": {
            "id": 84599,
            "tag": "ZZ99YYXX"
        },
        "requested": true
    }
}

POST Decline an Appraisal Offer

POST /2.0/vehicles/{id}/appraisal/decline · scope vehicle-appraisals:write

Decline an appraised offer (Appraised -> Rejected). Appraisal vehicles only.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKDecline an Appraisal Offer

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "status": {
            "id": 2,
            "name": "appraised",
            "label": "Appraised"
        },
        "offer": {
            "offer": 8500,
            "max_offer": 9000,
            "agreed_amount": 8750,
            "expiry": "2026-06-30",
            "appraised_by": 7,
            "comments": "Minor kerbing to alloys.",
            "decision": ""
        },
        "stock": {
            "id": 84599,
            "tag": "ZZ99YYXX"
        },
        "requested": true
    }
}

POST Reopen an Appraisal

POST /2.0/vehicles/{id}/appraisal/reopen · scope vehicle-appraisals:write

Reopen an appraised or rejected appraisal back to Added so a new offer can be made. Appraisal vehicles only.

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKReopen an Appraisal

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 84213,
        "tag": "AB12CDEF",
        "status": {
            "id": 2,
            "name": "appraised",
            "label": "Appraised"
        },
        "offer": {
            "offer": 8500,
            "max_offer": 9000,
            "agreed_amount": 8750,
            "expiry": "2026-06-30",
            "appraised_by": 7,
            "comments": "Minor kerbing to alloys.",
            "decision": ""
        },
        "stock": {
            "id": 84599,
            "tag": "ZZ99YYXX"
        },
        "requested": true
    }
}

Jobs

GET List Vehicle Jobs

GET /2.0/vehicles/{id}/jobs · scope vehicle-jobs:read

List the job boards applied to a vehicle, each with its stages, tasks, notes, clocking, documents and purchases, plus a progress summary.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKList Vehicle Jobs

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": [
        {
            "id": "",
            "board_id": 0,
            "tag": "",
            "name": "Vehicle Prep & Sale",
            "description": "",
            "complete": false,
            "progress": {
                "percent": 0,
                "stage_total": 0,
                "stage_done": 0,
                "complete": false,
                "issue": false,
                "priority": false
            },
            "time_total_minutes": 0,
            "created": 0,
            "updated": 0,
            "stages": [
                {
                    "index": 0,
                    "name": "Mechanical Work",
                    "complete": false,
                    "priority": false,
                    "issue": false,
                    "due_in": 0,
                    "due_at": 0,
                    "assignees": {
                        "users": [
                            {
                                "id": 0,
                                "name": ""
                            }
                        ],
                        "providers": [
                            {
                                "id": 0,
                                "name": ""
                            }
                        ],
                        "provider_notify": false
                    },
                    "time_total_minutes": 0,
                    "tasks": [
                        {
                            "index": 0,
                            "name": "",
                            "status": 0,
                            "status_label": "pending",
                            "instruction": ""
                        }
                    ],
                    "notes": [
                        {
                            "index": 0,
                            "user": 0,
                            "author": "",
                            "time": 0,
                            "note": "",
                            "privacy": false
                        }
                    ],
                    "time": [
                        {
                            "index": 0,
                            "user": 0,
                            "author": "",
                            "time": 0,
                            "hour": 0,
                            "minute": 0,
                            "total": 0
                        }
                    ],
                    "documents": [
                        {
                            "id": "",
                            "name": "",
                            "mime": "",
                            "extension": "",
                            "size": 0,
                            "size_label": "",
                            "icon": "",
                            "user": 0
                        }
                    ],
                    "purchases": [
                        {
                            "id": "",
                            "name": "",
                            "mime": "",
                            "extension": "",
                            "size": 0,
                            "size_label": "",
                            "icon": "",
                            "user": 0,
                            "purchase_queue_id": 0
                        }
                    ],
                    "updated": 0
                }
            ]
        }
    ]
}

POST Apply a Job Board to a Vehicle

POST /2.0/vehicles/{id}/jobs · scope vehicle-jobs:write

Apply a business job board to the vehicle, copying its stages onto the vehicle. Identify the board by its numeric id or tag (see GET /reference/job-boards).

Parameters (1)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
boardstringYesThe job board to apply, identified by its numeric id or its tag (see GET /reference/job-boards).prep-sale
{
    "board": "prep-sale"
}
Responses
StatusDescription
200 OKApply a Job Board to a Vehicle

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

GET Get a Vehicle Job

GET /2.0/vehicles/{id}/jobs/{job_id} · scope vehicle-jobs:read

Retrieve a single applied job board with its full stage detail.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
fieldsquerystring-Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel.
Responses
StatusDescription
200 OKGet a Vehicle Job

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

DELETE Remove a Vehicle Job

DELETE /2.0/vehicles/{id}/jobs/{job_id} · scope vehicle-jobs:delete

Remove an applied job board from the vehicle (archived to job history).

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRemove a Vehicle Job

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}

POST Add a Job Stage

POST /2.0/vehicles/{id}/jobs/{job_id}/stages · scope vehicle-jobs:write

Add a stage to a job, optionally complete, with assignees and a due date. Returns the updated job.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
namestringYesStage name.Mechanical Work
completeboolean-Whether the stage is complete. Defaults to false (not complete).false
priorityboolean-Flag the stage as high priority.
issueboolean-Flag the stage as having an issue.
usersarray of integer-Assigned staff user ids (see GET /reference/staff-users).[12]
providersarray of integer-Assigned service-provider (customer) ids.
provider_notifyboolean-Whether assigned providers are notified. Defaults to true.
due_ininteger or null-Days until the stage is due (sets a deadline timestamp), or null for no deadline.3
{
    "name": "Mechanical Work",
    "complete": false,
    "priority": false,
    "issue": false,
    "users": [
        12
    ],
    "providers": [
        0
    ],
    "provider_notify": false,
    "due_in": 3
}
Responses
StatusDescription
200 OKAdd a Job Stage

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

PUT Reorder Job Stages

PUT /2.0/vehicles/{id}/jobs/{job_id}/stages · scope vehicle-jobs:write

Reorder a job's stages. The order array must list every current stage index exactly once. Returns the updated job.

Parameters (2)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
orderarray of integerYesThe current stage indices in their new order. Must be a complete permutation of 0..N-1.[2,0,1]
{
    "order": [
        2,
        0,
        1
    ]
}
Responses
StatusDescription
200 OKReorder Job Stages

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

PATCH Update a Job Stage

PATCH /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage} · scope vehicle-jobs:write

Update a stage's name, completion (complete: true|false), priority, issue flag, assignees or due date. Completing a stage clears its issue and priority flags. Returns the updated job.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
namestring-Stage name.Mechanical Work
completeboolean-Mark the stage complete (true) or not complete (false). Completing a stage clears its issue and priority flags.true
priorityboolean-High-priority flag (cleared automatically when the stage completes).
issueboolean-Issue/alert flag (cleared automatically when the stage completes).
usersarray of integer-Assigned staff user ids (see GET /reference/staff-users). Replaces the current set.
providersarray of integer-Assigned external service-provider (contact) ids. Replaces the current set.
provider_notifyboolean-Whether assigned providers are notified.
due_ininteger or null-Days until due, or null to clear the deadline.
{
    "name": "Mechanical Work",
    "complete": true,
    "priority": false,
    "issue": false,
    "users": [
        0
    ],
    "providers": [
        0
    ],
    "provider_notify": false,
    "due_in": 0
}
Responses
StatusDescription
200 OKUpdate a Job Stage

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

DELETE Remove a Job Stage

DELETE /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage} · scope vehicle-jobs:delete

Remove a stage from a job. Remaining stages re-index. Returns the updated job.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRemove a Job Stage

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

POST Add a Stage Task

POST /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/tasks · scope vehicle-jobs:write

Add a task to a stage. Returns the updated job.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
namestringYesTask name.Replace brake pads
statusinteger-0 pending (default), 10 done.0
instructionstring-Optional task instructions.
{
    "name": "Replace brake pads",
    "status": 0,
    "instruction": ""
}
Responses
StatusDescription
200 OKAdd a Stage Task

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

PATCH Update a Stage Task

PATCH /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/tasks/{task} · scope vehicle-jobs:write

Update a task's status (0 pending / 10 done), name or instruction. Returns the updated job.

Parameters (4)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
taskpathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
statusinteger-0 pending, 10 done.
namestring-Task name.
instructionstring-Task instructions.
{
    "status": 0,
    "name": "",
    "instruction": ""
}
Responses
StatusDescription
200 OKUpdate a Stage Task

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

DELETE Remove a Stage Task

DELETE /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/tasks/{task} · scope vehicle-jobs:delete

Remove a task from a stage. Remaining tasks re-index. Returns the updated job.

Parameters (4)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
taskpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRemove a Stage Task

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

POST Add a Stage Note

POST /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/notes · scope vehicle-jobs:write

Add a note to a stage. Returns the updated job.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
notestringYesNote text.Waiting on parts from supplier.
privacyboolean-Whether the note is private to its author. Defaults to false.
userinteger-Author staff user id (see GET /reference/staff-users). Defaults to the system user.
{
    "note": "Waiting on parts from supplier.",
    "privacy": false,
    "user": 0
}
Responses
StatusDescription
200 OKAdd a Stage Note

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

DELETE Remove a Stage Note

DELETE /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/notes/{note} · scope vehicle-jobs:delete

Remove a note from a stage. Remaining notes re-index. Returns the updated job.

Parameters (4)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
notepathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRemove a Stage Note

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

POST Add a Stage Clocking Entry

POST /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/time · scope vehicle-jobs:write

Record a job clocking entry (time worked) against a stage. Returns the updated job.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
hourinteger-Hours worked. Defaults to 0.1
minuteinteger-Minutes worked (0-59). Defaults to 0.30
totalinteger-Explicit total minutes, overriding hour*60+minute.
userinteger-Staff user id the time is logged against. Defaults to the system user.
timeinteger-Unix timestamp of the entry. Defaults to now.
{
    "hour": 1,
    "minute": 30,
    "total": 0,
    "user": 0,
    "time": 0
}
Responses
StatusDescription
200 OKAdd a Stage Clocking Entry

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

DELETE Remove a Stage Clocking Entry

DELETE /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/time/{entry} · scope vehicle-jobs:delete

Remove a clocking entry from a stage. Remaining entries re-index. Returns the updated job.

Parameters (4)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
entrypathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRemove a Stage Clocking Entry

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

POST Upload a Stage Document

POST /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/documents · scope vehicle-jobs:write

Upload a document (base64 file) to a stage. The file is stored privately and also listed under the vehicle's documents. Returns the updated job.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
filestringYesBase64 file data (optionally a data: URL).data:application/pdf;base64,JVBERi0xLjQK...
filenamestring-Original filename (used for display and to infer the extension).inspection.pdf
extensionenum-File extension when not derivable from the filename.pdf
{
    "file": "data:application/pdf;base64,JVBERi0xLjQK...",
    "filename": "inspection.pdf",
    "extension": "pdf"
}
Responses
StatusDescription
200 OKUpload a Stage Document

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

DELETE Remove a Stage Document

DELETE /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/documents/{document_id} · scope vehicle-jobs:delete

Remove a document from a stage (also removed from the vehicle documents) and delete its file. Returns the updated job.

Parameters (4)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
document_idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRemove a Stage Document

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

POST Upload a Stage Purchase Invoice

POST /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/purchases · scope vehicle-jobs:write

Upload a purchase invoice (base64 file) to a stage. The file is queued for invoice processing. Returns the updated job.

Parameters (3)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
Request body
AttributeTypeRequiredDescriptionExample
filestringYesBase64 file data (optionally a data: URL).
filenamestring-Original filename (used for display and to infer the extension).parts-invoice.pdf
extensionenum-File extension when not derivable from the filename.pdf
{
    "file": "",
    "filename": "parts-invoice.pdf",
    "extension": "pdf"
}
Responses
StatusDescription
200 OKUpload a Stage Purchase Invoice

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}

DELETE Remove a Stage Purchase

DELETE /2.0/vehicles/{id}/jobs/{job_id}/stages/{stage}/purchases/{purchase_id} · scope vehicle-jobs:delete

Remove a purchase invoice from a stage, delete its file and cancel its invoice-processing queue entry. Returns the updated job.

Parameters (4)
ParameterInTypeRequiredDescriptionExample
idpathstringYesResource identifier in the path.
job_idpathstringYesResource identifier in the path.
stagepathstringYesResource identifier in the path.
purchase_idpathstringYesResource identifier in the path.
Responses
StatusDescription
200 OKRemove a Stage Purchase

Failures use the standard error responses (4xx/5xx) with the shared error envelope.

{
    "success": true,
    "data": {
        "id": "",
        "board_id": 0,
        "tag": "",
        "name": "Vehicle Prep & Sale",
        "description": "",
        "complete": false,
        "progress": {
            "percent": 0,
            "stage_total": 0,
            "stage_done": 0,
            "complete": false,
            "issue": false,
            "priority": false
        },
        "time_total_minutes": 0,
        "created": 0,
        "updated": 0,
        "stages": [
            {
                "index": 0,
                "name": "Mechanical Work",
                "complete": false,
                "priority": false,
                "issue": false,
                "due_in": 0,
                "due_at": 0,
                "assignees": {
                    "users": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "providers": [
                        {
                            "id": 0,
                            "name": ""
                        }
                    ],
                    "provider_notify": false
                },
                "time_total_minutes": 0,
                "tasks": [
                    {
                        "index": 0,
                        "name": "",
                        "status": 0,
                        "status_label": "pending",
                        "instruction": ""
                    }
                ],
                "notes": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "note": "",
                        "privacy": false
                    }
                ],
                "time": [
                    {
                        "index": 0,
                        "user": 0,
                        "author": "",
                        "time": 0,
                        "hour": 0,
                        "minute": 0,
                        "total": 0
                    }
                ],
                "documents": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0
                    }
                ],
                "purchases": [
                    {
                        "id": "",
                        "name": "",
                        "mime": "",
                        "extension": "",
                        "size": 0,
                        "size_label": "",
                        "icon": "",
                        "user": 0,
                        "purchase_queue_id": 0
                    }
                ],
                "updated": 0
            }
        ]
    }
}
Get Started
Overview
Platform
AuthenticationRate LimitsErrorsVersioningChangelogWebhooks
Reference
Reference DataBusiness
CRM
ContactsLeadsAppointmentsCalls
Content
BlogReviews
Stock
VehiclesListings
Sales
DealsInvoicesOrdersPurchasesDocuments

Base URL

https://api.motordesk.com/2.0/

OpenAPI

View Schema

Credentials

Manage API Keys