One owner from new.
` | | `data.option.feature` | object | - | | | | `data.history` | object | - | | | | `data.history.previous_owner` | integer or null | - | Number of previous owners. | `1` | | `data.history.keys` | integer or null | - | Number of keys supplied. | `2` | | `data.history.v5` | string | - | Whether a V5C logbook is present (Yes/No). | `Yes` | | `data.history.year` | integer or null | - | Year of manufacture. | `2020` | | `data.history.condition` | string | - | Overall condition. | `Used` | | `data.history.condition_interior` | string | - | Interior condition. | `Good` | | `data.history.condition_exterior` | string | - | Exterior condition. | `Good` | | `data.history.condition_tyre` | string | - | Tyre condition. | `Good` | | `data.history.service_history` | string | - | Service history type. | `Full` | | `data.history.service_last` | string (date) or null | - | Date of last service (YYYY-MM-DD). | `2025-09-01` | | `data.history.service_miles` | integer or null | - | Mileage at last service. | `36000` | | `data.history.mot_expiry` | string (date) or null | - | MOT expiry date (YYYY-MM-DD). | `2026-03-01` | | `data.history.mot_year` | string | - | Whether 12 months' MOT is included (Yes/No). | `Yes` | | `data.history.mot_insurance` | string | - | Whether MOT insurance is included (Yes/No). | `No` | | `data.history.warranty_expiry` | string (date) or null | - | Warranty expiry date (YYYY-MM-DD). | `2026-03-01` | | `data.history.warranty_month` | integer or null | - | Remaining warranty in months. | `12` | | `data.history.warranty_battery_month` | integer or null | - | Remaining battery warranty in months (EVs). | `60` | | `data.history.service_note` | string | - | Free-text service history note. | `Serviced at 12k and 24k miles.` | | `data.stock` | object | - | | | | `data.stock.reference` | string | - | Free-text stock reference. | `REF-1024` | | `data.stock.number` | string | - | Stock number. | `STK1024` | | `data.stock.location` | string | - | Business location. Accepts a location id on write; published as the location name. | `Main Forecourt` | | `data.stock.notes` | string | - | Internal notes (not shown publicly). | `Awaiting valet.` | | `data.stock.vin` | string | - | Vehicle identification number (uppercased alphanumeric). | `WBA8E9105HK000000` | | `data.stock.engine_number` | string | - | Engine number. | `B47D20A` | | `data.stock.key_number` | string | - | Key/security number. | `K12345` | | `data.stock.origin` | string | - | Where the vehicle was sourced from. | `Part Exchange` | | `data.stock.vat` | string | - | VAT scheme display value (see vat_scheme for the normalised value). | `Inc VAT` | | `data.stock.vat_pricing` | string | - | How VAT is reflected in the price. | `Inc. VAT` | | `data.stock.due_in_date` | string (date) or null | - | Date the vehicle is due into stock (YYYY-MM-DD). | `2026-06-20` | | `data.stock.forecourt_date` | string (date) or null | - | Date the vehicle went on the forecourt (YYYY-MM-DD). | `2026-06-12` | | `data.stock.price_website` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `12500.00` | | `data.stock.price_channel` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `13495.00` | | `data.stock.price_reserve` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `12000.00` | | `data.stock.price_auction_start` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `10000.00` | | `data.stock.price_auction_reserve` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `11000.00` | | `data.stock.price_auction_buy_now` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `13000.00` | | `data.stock.price_auction_duration` | string | - | Auction duration. | `7 Days` | | `data.stock.price_auction_dealerway_type` | string | - | 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_rrp` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `24995.00` | | `data.stock.price_poa` | boolean | - | | | | `data.stock.funding_provider` | string | - | Funding/finance provider name. Requires vehicle-pricing:read to read. | `Close Brothers` | | `data.stock.funding_provider_id` | integer or null | - | Funding provider contact id. Requires vehicle-pricing:read to read. | `42` | | `data.stock.funding_provider_total` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `8000.00` | | `data.stock.stock_quantity` | integer or null | - | Quantity available (for new/multi-stock vehicles). | `1` | | `data.stock.stock_variation` | object | - | Stock variation data (new vehicle configurator variants). | | | `data.stock.purchase_date` | string (date) or null | - | Purchase date (read-only; set via the purchase workflow). Requires vehicle-pricing:read. | `2026-01-15` | | `data.stock.purchase_invoice` | string | - | | `PINV-2048` | | `data.stock.purchase_supplier` | string | - | | `BCA Auction` | | `data.stock.purchase_supplier_id` | integer 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_invoice` | string | - | | `BCA-99812` | | `data.stock.purchase_price` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `9000.00` | | `data.stock.purchase_price_vat` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `0.00` | | `data.stock.purchase_price_total` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `9000.00` | | `data.stock.purchase_cost` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `450.00` | | `data.stock.purchase_cost_vat` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `90.00` | | `data.stock.purchase_cost_total` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `540.00` | | `data.stock.purchase_value` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `9450.00` | | `data.stock.purchase_value_vat` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `90.00` | | `data.stock.purchase_value_total` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `9540.00` | | `data.stock.purchase_cost_data` | array of object | - | Additional purchase costs (transport, valeting, repairs, ...). Writing rows recomputes the read-only purchase_cost/value totals. Read requires vehicle-pricing:read. | | | `data.spec` | object | - | | | | `data.spec.performance` | object | - | top_speed, zero_sixty. | `{"top_speed":155,"zero_sixty":5.8}` | | `data.spec.engine` | object | - | make, cylinders, bhp, ps, nm, gears... | `{"make":"BMW","cylinders":4,"capacity":1998,"bhp":181,"ps":184,"nm":300,"gears":8}` | | `data.spec.battery` | object | - | charge_time, range, kwh, health. | `{"range":239,"kwh":58,"charge_time":"8h 15m","health":100}` | | `data.spec.other` | object | - | axles, country, sector. | `{"axles":2,"country":"GB","sector":"Retail"}` | | `data.spec.insurance` | object | - | group, code. | `{"group":"21E","code":"21E"}` | | `data.spec.fuel` | object | - | mpg_*, emission_*, ulez, caz. | `{"mpg_combined":48.7,"emission_co2":132,"ulez":true,"caz":true}` | | `data.spec.size` | object | - | length, width, height, weights, boot. | `{"length":4709,"width":2073,"height":1442,"wheelbase":2851,"kerb_weight":1545,"boot_seats_up":480}` | | `data.appraisal` | object | - | | | | `data.appraisal.details` | object | - | | | | `data.appraisal.details.customer_id` | string | - | 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.customer` | string | - | Linked contact name, captured when the link was made. | `Ada Buyer` | | `data.appraisal.calculation` | object | - | | | | `data.appraisal.calculation.offer` | string | - | The working offer figure from the appraisal calculator; the confirmed figure lives in confirm.offer. | `9500.00` | | `data.appraisal.calculation.finance_settlement` | string | - | Outstanding finance on the vehicle, as recorded on the appraisal. | `2000.00` | | `data.appraisal.confirm` | object | - | | | | `data.appraisal.confirm.offer` | string | - | The confirmed offer made to the customer. | `9500.00` | | `data.appraisal.confirm.expiry` | string | - | Date the confirmed offer is good until (YYYY-MM-DD), empty for no expiry. | `2026-09-06` | | `data.appraisal.confirm.appraised_at` | integer | - | Unix timestamp the offer was confirmed, 0 before confirmation. | `1756137600` | | `data.appraisal.confirm.agreed_amount` | string | - | The figure the vehicle was actually taken in at, set when the appraisal is accepted. | `9250.00` | | `data.appraisal.confirm.decision` | string | - | accepted or rejected once decided, empty while awaiting a decision. | `accepted` | | `data.appraisal.confirm.decision_at` | integer | - | Unix timestamp of the decision, 0 before one. | `1756224000` | | `data.appraisal.confirm.stock_id` | string | - | The stock vehicle created when the appraisal was accepted, empty before acceptance. | `18342` | | `data.appraisal.confirm.stock_tag` | string | - | The created stock vehicle's tag. | `a1b2c3d4` | | `data.lookup` | object | - | | | | `data.lookup.dvla` | object | - | | `{"make":"BMW","colour":"BLACK","fuel_type":"PETROL","year_of_manufacture":2020,"tax_status":"Taxed"}` | | `data.lookup.dvsa` | object | - | | `{"mot_tests":[{"completed_date":"2025-03-01","test_result":"PASSED","odometer_value":36000}]}` | | `data.lookup.check` | object | - | | `{"stolen":false,"finance":false,"written_off":false,"previous_keepers":1}` | | `data.tag` | array of object | - | | `[{"name":"Service","checked":false,"colour":"primary","type":"check"}]` | | `data.finance` | object | - | | | | `data.finance.example_monthly` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `507.75` | | `data.finance.example` | object | - | | | | `data.finance.example.cash_price` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `20000.00` | | `data.finance.example.total_deposit` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `2000.00` | | `data.finance.example.total_credit` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `18000.00` | | `data.finance.example.first_payment` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `507.75` | | `data.finance.example.monthly_payment` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `507.75` | | `data.finance.example.total_monthly_payments` | integer or null | - | Number of monthly payments. | `25` | | `data.finance.example.final_payment` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `7856.00` | | `data.finance.example.term` | integer or null | - | Agreement duration in months. | `27` | | `data.finance.example.admin_fee` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `0.00` | | `data.finance.example.option_purchase_fee` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `10.00` | | `data.finance.example.interest_charge` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `3057.50` | | `data.finance.example.total_payable` | string (2dp decimal) or null | - | Monetary amount as a fixed 2dp decimal string. | `23057.50` | | `data.finance.example.fixed_interest_rate` | number or null | - | Annual fixed interest rate (percent). | `10.36` | | `data.finance.example.representative_apr` | number or null | - | Representative APR (percent). | `10.9` | | `media` | object | - | | | | `media.photo` | array of string | - | Photo media item ids, in display order. | `["m7Yk2p9q","r3Tn8w1z"]` | | `media.video` | array of string | - | Video media item ids. | `["v9Lp4m2x"]` | | `media.youtube` | array of string | - | YouTube video ids. | `["dQw4w9WgXcQ"]` | | `media.photo_spin` | array of string | - | 360-spin frame media item ids. | `["s5Qw8r3t"]` | **Example object** ```json { "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": "One owner from new.
", "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `page` | query | integer | - | Page number, starting at 1 (offset pagination). | | | `per_page` | query | integer | - | Results per page (maximum 500). | | | `view` | query | enum | - | Response detail: "simple" for a compact object or "full" for the complete object. | | | `status` | query | enum | - | 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` | | `type` | query | enum | - | Filter by stock type: s (stock), t (template), u (used/booked-in), r (courtesy/loan). | `s` | | `registration` | query | string | - | Filter by registration. Exact match, or use % for wildcard matching (minimum 3 characters). | `AB12CDE` | | `reserve_contact` | query | integer | - | Filter to vehicles reserved by this contact id. | | | `appraisal_contact` | query | integer | - | Filter to appraisals raised for this contact id (pair with type=appraisal). | | | `sold_contact` | query | integer | - | Filter to vehicles sold to this contact id. | | | `owner` | query | string | - | Filter by owner. | | | `parent` | query | integer | - | Filter by parent. | | | `country` | query | string | - | Filter by country. | | | `tag` | query | string | - | Filter by tag. Supports wildcards (%) with the search:wildcard scope. | | | `make` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | `BMW` | | `model` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | `3 Series` | | `generation` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `derivative` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `trim` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `fuel` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `transmission` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `drivetrain` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `body` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `colour` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `group` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `vin` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `reference` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `number` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `seats` | query | string | - | Exact match, or a two-element array [from, to] for a range (e.g. seats[]=2&seats[]=5). An empty bound is open-ended. | | | `doors` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `mileage` | query | string | - | Exact match, or a two-element array [from, to] for a range (e.g. mileage[]=10000&mileage[]=50000). An empty bound is open-ended. | | | `year` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `registered` | query | string | - | Exact match (YYYY-MM-DD), or a two-element array [from, to] for a range (e.g. registered[]=2020-01-01®istered[]=2022-12-31). An empty bound is open-ended. | | | `price_website` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `price_channel` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `identifier` | query | string | - | Registration, VIN or stock number. Exact match, or use % for wildcard matching (minimum 3 characters). | `AB12CDE` | | `engine_size` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `hour` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `category` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `condition` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `bedroom_layout` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `end_layout` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `bedroom` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `berth` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `wheelchair` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `location` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `engine_number` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `chassis` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `key_number` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `vat` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `featured` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `acceleration` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `battery_range` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `battery_health` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `ulez` | query | string | - | Exact match, or use % for wildcard matching (minimum 3 characters). | | | `mpg` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `weight_kerb` | query | string | - | Exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `reserved` | query | integer | - | 1 if the vehicle is reserved (data.reserve set), 0 otherwise. | | | `sold_complete` | query | integer | - | 1 if the sale is complete (data.sold.complete set), 0 otherwise. | | | `created` | query | string | - | 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. | | | `updated` | query | string | - | Unix timestamp exact match, or a two-element array [from, to] for a range. An empty bound is open-ended. | | | `cursor` | query | string | - | Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Paginated vehicles | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "One owner from new.
", "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** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `country` | string | - | Country code the vehicle belongs to (e.g. UK; GB is treated as UK). Defaults to the business country. | `UK` | | `registration` | string | - | Vehicle registration number (case-insensitive; spaces ignored). Optional for a draft. | `EO68NRJ` | | `status` | enum | - | 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` | | `type` | enum | - | 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` | | `data` | object | - | Writable vehicle data, grouped by section. Only the fields listed here are accepted; unknown fields are rejected. | | | `data.vehicle` | object | - | | | | `data.vehicle.type` | string | - | 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.make` | string | - | 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.model` | string | - | 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.generation` | string | - | 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.derivative` | string | - | 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.trim` | string | - | 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_size` | string | - | 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.body` | string | - | Body style. Value is validated against the configured option list. | `Saloon` | | `data.vehicle.colour` | string | - | Paint colour. Value is validated against the configured option list. | `Black` | | `data.vehicle.colour_name` | string | - | Manufacturer colour name. | `Sapphire Black` | | `data.vehicle.fuel` | string | - | Fuel type. Value is validated against the configured option list. | `Petrol` | | `data.vehicle.transmission` | string | - | Transmission type. Value is validated against the configured option list. | `Automatic` | | `data.vehicle.drivetrain` | string | - | Drivetrain. Applies to cars and bikes. Value is validated against the configured option list. | `RWD` | | `data.vehicle.seats` | integer or null | - | Number of seats. | `5` | | `data.vehicle.doors` | integer or null | - | Number of doors. | `5` | | `data.vehicle.wheelbase` | string | - | Wheelbase. Applies to vans. | `LWB` | | `data.vehicle.cab_type` | string | - | Cab type. Applies to vans and trucks. | `Double Cab` | | `data.vehicle.mileage` | integer or null | - | Odometer reading in miles. | `38450` | | `data.vehicle.registered` | string (date) or null | - | First registration date (YYYY-MM-DD). | `2020-03-01` | | `data.vehicle.category` | string | - | Vehicle category. Applies to farm, plant and trucks. | `Tractor` | | `data.vehicle.driver_position` | string | - | Driver position (steering side). | `RHD` | | `data.vehicle.interior_upholstery` | string | - | Interior upholstery material. | `Leather` | | `data.vehicle.interior_colour` | string | - | Interior colour. | `Black` | | `data.vehicle.exterior_finish` | string | - | Exterior paint finish. | `Metallic` | | `data.vehicle.group` | string | - | Vehicle grouping label (free text, for your own categorisation). | `Demo Fleet` | | `data.vehicle.bedroom_layout` | string or null | - | Bedroom layout. Applies to caravans and motorhomes. Value is validated against the configured option list. | `Fixed island bed` | | `data.vehicle.end_layout` | string or null | - | End layout. Applies to caravans and motorhomes. Value is validated against the configured option list. | `End washroom` | | `data.vehicle.bedroom` | integer or null | - | Number of bedrooms. Applies to caravans and motorhomes. | `2` | | `data.vehicle.berth` | integer or null | - | Number of berths. Applies to caravans and motorhomes. | `4` | | `data.vehicle.seat_belt` | integer or null | - | Number of belted seats. Applies to caravans and motorhomes. | `4` | | `data.vehicle.wheelchair` | string or null | - | Wheelchair accessible (Yes/No). Applies to caravans and motorhomes. Value is validated against the configured option list. | `No` | | `data.option` | object | - | | | | `data.option.option` | array 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_custom` | array of string | - | Custom (dealer-added) option names. | `["12 Month Warranty"]` | | `data.option.attention` | string | - | Short attention grabber shown on listings. | `Full Service History` | | `data.option.description` | string | - | Plain-text advert description. | `One owner from new, full BMW service history.` | | `data.option.website` | string | - | HTML advert body shown on the website. | `One owner from new.
` | | `data.history` | object | - | | | | `data.history.previous_owner` | integer or null | - | Number of previous owners. | `1` | | `data.history.keys` | integer or null | - | Number of keys supplied. | `2` | | `data.history.v5` | string | - | Whether a V5C logbook is present (Yes/No). | `Yes` | | `data.history.year` | integer or null | - | Year of manufacture. | `2020` | | `data.history.condition` | string | - | Overall condition. | `Used` | | `data.history.condition_interior` | string | - | Interior condition. | `Good` | | `data.history.condition_exterior` | string | - | Exterior condition. | `Good` | | `data.history.condition_tyre` | string | - | Tyre condition. | `Good` | | `data.history.service_history` | string | - | Service history type. | `Full` | | `data.history.service_last` | string (date) or null | - | Date of last service (YYYY-MM-DD). | `2025-09-01` | | `data.history.service_miles` | integer or null | - | Mileage at last service. | `36000` | | `data.history.mot_expiry` | string (date) or null | - | MOT expiry date (YYYY-MM-DD). | `2026-03-01` | | `data.history.mot_year` | string | - | Whether 12 months' MOT is included (Yes/No). | `Yes` | | `data.history.mot_insurance` | string | - | Whether MOT insurance is included (Yes/No). | `No` | | `data.history.warranty_expiry` | string (date) or null | - | Warranty expiry date (YYYY-MM-DD). | `2026-03-01` | | `data.history.warranty_month` | integer or null | - | Remaining warranty in months. | `12` | | `data.history.warranty_battery_month` | integer or null | - | Remaining battery warranty in months (EVs). | `60` | | `data.history.service_note` | string | - | Free-text service history note. | `Serviced at 12k and 24k miles.` | | `data.stock` | object | - | | | | `data.stock.reference` | string | - | Free-text stock reference. | `REF-1024` | | `data.stock.number` | string | - | Stock number. | `STK1024` | | `data.stock.location` | string | - | Business location. Accepts a location id on write; published as the location name. | `Main Forecourt` | | `data.stock.notes` | string | - | Internal notes (not shown publicly). | `Awaiting valet.` | | `data.stock.vin` | string | - | Vehicle identification number (uppercased alphanumeric). | `WBA8E9105HK000000` | | `data.stock.engine_number` | string | - | Engine number. | `B47D20A` | | `data.stock.key_number` | string | - | Key/security number. | `K12345` | | `data.stock.origin` | string | - | Where the vehicle was sourced from. | `Part Exchange` | | `data.stock.vat` | string | - | VAT scheme display value (see vat_scheme for the normalised value). | `Inc VAT` | | `data.stock.vat_pricing` | string | - | How VAT is reflected in the price. | `Inc. VAT` | | `data.stock.due_in_date` | string (date) or null | - | Date the vehicle is due into stock (YYYY-MM-DD). | `2026-06-20` | | `data.stock.forecourt_date` | string (date) or null | - | Date the vehicle went on the forecourt (YYYY-MM-DD). | `2026-06-12` | | `data.stock.price_website` | number or null | - | Website price as a fixed 2dp decimal string. | `12500.00` | | `data.stock.price_channel` | number or null | - | Channel price (published to sales channels) as a fixed 2dp decimal string. | `13495.00` | | `data.stock.price_reserve` | number or null | - | Reserve/minimum price (2dp decimal string). | `12000.00` | | `data.stock.price_auction_start` | number or null | - | Auction starting price (2dp decimal string). | `10000.00` | | `data.stock.price_auction_reserve` | number or null | - | Auction reserve price (2dp decimal string). | `11000.00` | | `data.stock.price_auction_buy_now` | number or null | - | Auction Buy Now price (2dp decimal string). | `13000.00` | | `data.stock.price_auction_duration` | string | - | Auction duration. | `7 Days` | | `data.stock.price_auction_dealerway_type` | string | - | 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_rrp` | number or null | - | Manufacturer RRP (2dp decimal string). | `24995.00` | | `data.stock.funding_provider` | string | - | Funding/finance provider name. Requires vehicle-pricing:read to read. | `Close Brothers` | | `data.stock.funding_provider_id` | integer or null | - | Funding provider contact id. Requires vehicle-pricing:read to read. | `42` | | `data.stock.funding_provider_total` | number or null | - | Outstanding funding amount (2dp decimal string). Requires vehicle-pricing:read to read. | `8000.00` | | `data.stock.stock_quantity` | integer or null | - | Quantity available (for new/multi-stock vehicles). | `1` | | `data.stock.stock_variation` | object | - | Stock variation data (new vehicle configurator variants). | | | `data.stock.purchase_cost_data` | array of object | - | Additional purchase costs (transport, valeting, repairs, ...). Writing rows recomputes the read-only purchase_cost/value totals. Read requires vehicle-pricing:read. | | | `data.setting` | object | - | | | | `data.setting.featured` | enum | - | Whether the vehicle is featured. Accepts the strings "Yes" or "No". | `Yes` | | `data.setting.poa` | enum | - | Price on application (hides the price). Accepts the strings "Yes" or "No". | `No` | | `data.spec` | object | - | | | | `data.spec.performance` | object | - | top_speed, zero_sixty. | `{"top_speed":155,"zero_sixty":5.8}` | | `data.spec.engine` | object | - | make, cylinders, bhp, ps, nm, gears... | `{"make":"BMW","cylinders":4,"capacity":1998,"bhp":181,"ps":184,"nm":300,"gears":8}` | | `data.spec.battery` | object | - | charge_time, range, kwh, health. | `{"range":239,"kwh":58,"charge_time":"8h 15m","health":100}` | | `data.spec.other` | object | - | axles, country, sector. | `{"axles":2,"country":"GB","sector":"Retail"}` | | `data.spec.insurance` | object | - | group, code. | `{"group":"21E","code":"21E"}` | | `data.spec.fuel` | object | - | mpg_*, emission_*, ulez, caz. | `{"mpg_combined":48.7,"emission_co2":132,"ulez":true,"caz":true}` | | `data.spec.size` | object | - | length, width, height, weights, boot. | `{"length":4709,"width":2073,"height":1442,"wheelbase":2851,"kerb_weight":1545,"boot_seats_up":480}` | ```json { "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": "One owner from new.
" }, "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** | Status | Description | | --- | --- | | `201` Created | Vehicle created | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "One owner from new.
", "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "One owner from new.
", "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `data` | object | Yes | Writable vehicle data, grouped by section. Only the fields listed here are accepted; unknown fields are rejected. | | | `data.vehicle` | object | - | | | | `data.vehicle.type` | string | - | 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.make` | string | - | 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.model` | string | - | 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.generation` | string | - | 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.derivative` | string | - | 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.trim` | string | - | 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_size` | string | - | 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.body` | string | - | Body style. Value is validated against the configured option list. | `Saloon` | | `data.vehicle.colour` | string | - | Paint colour. Value is validated against the configured option list. | `Black` | | `data.vehicle.colour_name` | string | - | Manufacturer colour name. | `Sapphire Black` | | `data.vehicle.fuel` | string | - | Fuel type. Value is validated against the configured option list. | `Petrol` | | `data.vehicle.transmission` | string | - | Transmission type. Value is validated against the configured option list. | `Automatic` | | `data.vehicle.drivetrain` | string | - | Drivetrain. Applies to cars and bikes. Value is validated against the configured option list. | `RWD` | | `data.vehicle.seats` | integer or null | - | Number of seats. | `5` | | `data.vehicle.doors` | integer or null | - | Number of doors. | `5` | | `data.vehicle.wheelbase` | string | - | Wheelbase. Applies to vans. | `LWB` | | `data.vehicle.cab_type` | string | - | Cab type. Applies to vans and trucks. | `Double Cab` | | `data.vehicle.mileage` | integer or null | - | Odometer reading in miles. | `38450` | | `data.vehicle.registered` | string (date) or null | - | First registration date (YYYY-MM-DD). | `2020-03-01` | | `data.vehicle.category` | string | - | Vehicle category. Applies to farm, plant and trucks. | `Tractor` | | `data.vehicle.driver_position` | string | - | Driver position (steering side). | `RHD` | | `data.vehicle.interior_upholstery` | string | - | Interior upholstery material. | `Leather` | | `data.vehicle.interior_colour` | string | - | Interior colour. | `Black` | | `data.vehicle.exterior_finish` | string | - | Exterior paint finish. | `Metallic` | | `data.vehicle.group` | string | - | Vehicle grouping label (free text, for your own categorisation). | `Demo Fleet` | | `data.vehicle.bedroom_layout` | string or null | - | Bedroom layout. Applies to caravans and motorhomes. Value is validated against the configured option list. | `Fixed island bed` | | `data.vehicle.end_layout` | string or null | - | End layout. Applies to caravans and motorhomes. Value is validated against the configured option list. | `End washroom` | | `data.vehicle.bedroom` | integer or null | - | Number of bedrooms. Applies to caravans and motorhomes. | `2` | | `data.vehicle.berth` | integer or null | - | Number of berths. Applies to caravans and motorhomes. | `4` | | `data.vehicle.seat_belt` | integer or null | - | Number of belted seats. Applies to caravans and motorhomes. | `4` | | `data.vehicle.wheelchair` | string or null | - | Wheelchair accessible (Yes/No). Applies to caravans and motorhomes. Value is validated against the configured option list. | `No` | | `data.option` | object | - | | | | `data.option.option` | array 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_custom` | array of string | - | Custom (dealer-added) option names. | `["12 Month Warranty"]` | | `data.option.attention` | string | - | Short attention grabber shown on listings. | `Full Service History` | | `data.option.description` | string | - | Plain-text advert description. | `One owner from new, full BMW service history.` | | `data.option.website` | string | - | HTML advert body shown on the website. | `One owner from new.
` | | `data.history` | object | - | | | | `data.history.previous_owner` | integer or null | - | Number of previous owners. | `1` | | `data.history.keys` | integer or null | - | Number of keys supplied. | `2` | | `data.history.v5` | string | - | Whether a V5C logbook is present (Yes/No). | `Yes` | | `data.history.year` | integer or null | - | Year of manufacture. | `2020` | | `data.history.condition` | string | - | Overall condition. | `Used` | | `data.history.condition_interior` | string | - | Interior condition. | `Good` | | `data.history.condition_exterior` | string | - | Exterior condition. | `Good` | | `data.history.condition_tyre` | string | - | Tyre condition. | `Good` | | `data.history.service_history` | string | - | Service history type. | `Full` | | `data.history.service_last` | string (date) or null | - | Date of last service (YYYY-MM-DD). | `2025-09-01` | | `data.history.service_miles` | integer or null | - | Mileage at last service. | `36000` | | `data.history.mot_expiry` | string (date) or null | - | MOT expiry date (YYYY-MM-DD). | `2026-03-01` | | `data.history.mot_year` | string | - | Whether 12 months' MOT is included (Yes/No). | `Yes` | | `data.history.mot_insurance` | string | - | Whether MOT insurance is included (Yes/No). | `No` | | `data.history.warranty_expiry` | string (date) or null | - | Warranty expiry date (YYYY-MM-DD). | `2026-03-01` | | `data.history.warranty_month` | integer or null | - | Remaining warranty in months. | `12` | | `data.history.warranty_battery_month` | integer or null | - | Remaining battery warranty in months (EVs). | `60` | | `data.history.service_note` | string | - | Free-text service history note. | `Serviced at 12k and 24k miles.` | | `data.stock` | object | - | | | | `data.stock.reference` | string | - | Free-text stock reference. | `REF-1024` | | `data.stock.number` | string | - | Stock number. | `STK1024` | | `data.stock.location` | string | - | Business location. Accepts a location id on write; published as the location name. | `Main Forecourt` | | `data.stock.notes` | string | - | Internal notes (not shown publicly). | `Awaiting valet.` | | `data.stock.vin` | string | - | Vehicle identification number (uppercased alphanumeric). | `WBA8E9105HK000000` | | `data.stock.engine_number` | string | - | Engine number. | `B47D20A` | | `data.stock.key_number` | string | - | Key/security number. | `K12345` | | `data.stock.origin` | string | - | Where the vehicle was sourced from. | `Part Exchange` | | `data.stock.vat` | string | - | VAT scheme display value (see vat_scheme for the normalised value). | `Inc VAT` | | `data.stock.vat_pricing` | string | - | How VAT is reflected in the price. | `Inc. VAT` | | `data.stock.due_in_date` | string (date) or null | - | Date the vehicle is due into stock (YYYY-MM-DD). | `2026-06-20` | | `data.stock.forecourt_date` | string (date) or null | - | Date the vehicle went on the forecourt (YYYY-MM-DD). | `2026-06-12` | | `data.stock.price_website` | number or null | - | Website price as a fixed 2dp decimal string. | `12500.00` | | `data.stock.price_channel` | number or null | - | Channel price (published to sales channels) as a fixed 2dp decimal string. | `13495.00` | | `data.stock.price_reserve` | number or null | - | Reserve/minimum price (2dp decimal string). | `12000.00` | | `data.stock.price_auction_start` | number or null | - | Auction starting price (2dp decimal string). | `10000.00` | | `data.stock.price_auction_reserve` | number or null | - | Auction reserve price (2dp decimal string). | `11000.00` | | `data.stock.price_auction_buy_now` | number or null | - | Auction Buy Now price (2dp decimal string). | `13000.00` | | `data.stock.price_auction_duration` | string | - | Auction duration. | `7 Days` | | `data.stock.price_auction_dealerway_type` | string | - | 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_rrp` | number or null | - | Manufacturer RRP (2dp decimal string). | `24995.00` | | `data.stock.funding_provider` | string | - | Funding/finance provider name. Requires vehicle-pricing:read to read. | `Close Brothers` | | `data.stock.funding_provider_id` | integer or null | - | Funding provider contact id. Requires vehicle-pricing:read to read. | `42` | | `data.stock.funding_provider_total` | number or null | - | Outstanding funding amount (2dp decimal string). Requires vehicle-pricing:read to read. | `8000.00` | | `data.stock.stock_quantity` | integer or null | - | Quantity available (for new/multi-stock vehicles). | `1` | | `data.stock.stock_variation` | object | - | Stock variation data (new vehicle configurator variants). | | | `data.stock.purchase_cost_data` | array of object | - | Additional purchase costs (transport, valeting, repairs, ...). Writing rows recomputes the read-only purchase_cost/value totals. Read requires vehicle-pricing:read. | | | `data.setting` | object | - | | | | `data.setting.featured` | enum | - | Whether the vehicle is featured. Accepts the strings "Yes" or "No". | `Yes` | | `data.setting.poa` | enum | - | Price on application (hides the price). Accepts the strings "Yes" or "No". | `No` | | `data.spec` | object | - | | | | `data.spec.performance` | object | - | top_speed, zero_sixty. | `{"top_speed":155,"zero_sixty":5.8}` | | `data.spec.engine` | object | - | make, cylinders, bhp, ps, nm, gears... | `{"make":"BMW","cylinders":4,"capacity":1998,"bhp":181,"ps":184,"nm":300,"gears":8}` | | `data.spec.battery` | object | - | charge_time, range, kwh, health. | `{"range":239,"kwh":58,"charge_time":"8h 15m","health":100}` | | `data.spec.other` | object | - | axles, country, sector. | `{"axles":2,"country":"GB","sector":"Retail"}` | | `data.spec.insurance` | object | - | group, code. | `{"group":"21E","code":"21E"}` | | `data.spec.fuel` | object | - | mpg_*, emission_*, ulez, caz. | `{"mpg_combined":48.7,"emission_co2":132,"ulez":true,"caz":true}` | | `data.spec.size` | object | - | length, width, height, weights, boot. | `{"length":4709,"width":2073,"height":1442,"wheelbase":2851,"kerb_weight":1545,"boot_seats_up":480}` | ```json { "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": "One owner from new.
" }, "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** | Status | Description | | --- | --- | | `200` OK | Vehicle updated | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "One owner from new.
", "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle deleted | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `type` | string | Yes | How 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` | | `identifier` | string | Yes | The vehicle registration number (when type is a country) or the VIN (when type is "VIN"). Case-insensitive; spaces are ignored. | `EO68NRJ` | | `mot` | boolean | - | Include MOT history in the result. Defaults to true. | | | `features` | boolean | - | Include factory feature/option data. Defaults to true. | | | `basic_check` | boolean | - | Include a basic provider vehicle check. Defaults to true. | | | `factory_fitted` | boolean | - | Include factory-fitted specification data. Defaults to true. | | | `full_check` | boolean | - | Run a full provider check (more detailed; may incur a provider cost). Defaults to false. | | ```json { "type": "UK", "identifier": "EO68NRJ", "mot": false, "features": false, "basic_check": false, "factory_fitted": false, "full_check": false } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle lookup result | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `type` | enum | - | What to recognise: registration, vin, or auto to detect which. Defaults to auto. | `auto` | | `country` | string | - | Country code for the registration format (e.g. UK; GB is treated as UK). Defaults to the business country. | `UK` | | `image` | string | - | 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...` | | `identifier` | string | - | A known registration or VIN to validate and normalise instead of reading from an image. | `EO68NRJ` | ```json { "type": "auto", "country": "UK", "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...", "identifier": "EO68NRJ" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle recognition result | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `type` | query | enum | - | Filter by type. | | | `make` | query | string | - | Filter by make. | | | `model` | query | string | - | Filter by model. | | | `generation` | query | string | - | Filter by generation. | | | `derivative` | query | string | - | Filter by derivative. | | | `list` | query | enum | - | Filter by list. | | | `country` | query | string | - | Filter by country. | | | `cursor` | query | string | - | Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle taxonomy values | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle pricing and valuation data | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `trim` | query | string | - | Filter by trim. | | | `engine_min` | query | number | - | Filter by engine min. | | | `engine_max` | query | number | - | Filter by engine max. | | | `fuel` | query | string | - | Filter by fuel. | | | `transmission` | query | string | - | Filter by transmission. | | | `drivetrain` | query | string | - | Filter by drivetrain. | | | `doors` | query | integer | - | Filter by doors. | | | `mileage_min` | query | integer | - | Filter by mileage min. | | | `mileage_max` | query | integer | - | Filter by mileage max. | | | `year_min` | query | integer | - | Filter by year min. | | | `year_max` | query | integer | - | Filter by year max. | | | `condition` | query | string | - | Filter by condition. | | | `postcode` | query | string | - | Filter by postcode. | | | `distance` | query | integer | - | Filter by distance. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle competitor pricing data | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `status` | enum | Yes | Target status. | `deleted` | ```json { "status": "deleted" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Change Vehicle Status | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "One owner from new.
", "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `date` | string | - | Handover/completion date (YYYY-MM-DD or Unix timestamp). Defaults to now. | `2026-06-13` | | `by` | array of integer | - | Staff user ids who handled the handover (see GET /reference/staff-users). | `[7]` | | `channel` | string | - | Sale channel label. | `Showroom` | | `finance_end` | string | - | Finance agreement end date (YYYY-MM-DD). | `2029-06-13` | | `checklist` | array of string | - | Handover checklist items handed over; each must be one of the business handover checklist options. | `["Logbook (V5C2)","Spare Key"]` | | `commissions` | array of object | - | Commission rows recorded against the sale. | | ```json { "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** | Status | Description | | --- | --- | | `200` OK | Mark a Sold Vehicle Complete | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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": "One owner from new.
", "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `target` | enum | - | What to generate: the long advert description (default) or the short attention grabber. | | | `apply` | boolean | - | 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). | | | `length` | integer | - | Maximum character length for the attention grabber (20-120, defaults to 30). Only applies when target is attention. | | | `options` | array of string | - | Optional list of selling points / feature hints to steer the generated copy. | | ```json { "target": "description", "apply": false, "length": 0, "options": [ "" ] } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Generated vehicle advert text | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle media list | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `file` | string | - | Base64 image/video data (optionally a data: URL). | | | `filename` | string | - | Original filename (used for display and to infer the extension). | `front.jpg` | | `extension` | enum | - | File extension when not derivable from the filename. | `jpg` | | `type` | enum | - | 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` | | `caption` | string | - | Image caption / alt text. | | | `group` | string | - | Optional media group label for organising images. | | | `youtube_url` | string | - | 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_id` | string | - | A YouTube video id to attach directly. | `dQw4w9WgXcQ` | ```json { "file": "", "filename": "front.jpg", "extension": "jpg", "type": "photo", "caption": "", "group": "", "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "youtube_id": "dQw4w9WgXcQ" } ``` **Responses** | Status | Description | | --- | --- | | `201` Created | Vehicle media attached | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `media_id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `caption` | string | - | Image caption / alt text. Empty string clears it. | | | `group` | string | - | Media group label. Empty string clears it. | | | `options` | object | - | 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.watermark` | boolean | - | Apply the business watermark. | | | `options.brand_first` | object | - | Primary brand logo overlay. position: top_left, top, top_right, bottom_left, bottom, bottom_right. | | | `options.brand_first.enable` | boolean | - | Whether the overlay is shown. | | | `options.brand_first.position` | enum | - | Overlay position on the image. | | | `options.brand_second` | object | - | Secondary brand logo overlay. | | | `options.brand_second.enable` | boolean | - | Whether the overlay is shown. | | | `options.brand_second.position` | enum | - | Overlay position on the image. | | | `options.ribbon` | object | - | Corner ribbon. position: top_left, top_right, bottom_left, bottom_right. | | | `options.ribbon.enable` | boolean | - | Whether the overlay is shown. | | | `options.ribbon.position` | string | - | Overlay position on the image (see the parent description for allowed values). | | | `options.ribbon.color` | string | - | Background hex colour. | | | `options.ribbon.text_color` | string | - | Text hex colour. | | | `options.ribbon.text` | string | - | Overlay text. | | | `options.banner` | object | - | Full-width banner. position: top, bottom. | | | `options.banner.enable` | boolean | - | Whether the overlay is shown. | | | `options.banner.position` | string | - | Overlay position on the image (see the parent description for allowed values). | | | `options.banner.color` | string | - | Background hex colour. | | | `options.banner.text_color` | string | - | Text hex colour. | | | `options.banner.text` | string | - | Overlay text. | | | `options.background` | string or null | - | Configured background filename (from /my media backgrounds) to composite behind a cut-out of the vehicle, or null to remove. | | | `options.feature_position` | string | - | Website feature placement for this image. | | ```json { "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** | Status | Description | | --- | --- | | `200` OK | Edit Vehicle Media | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `media_id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Vehicle media deleted | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | List Vehicle Test Drives | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `contact` | integer | - | Contact id of the driver (optional). | `110166` | | `license_number` | string | - | Driving licence number (required unless the stock type skips licence checks). | `SMITH901234AB9CD` | | `license_code` | string | - | Licence check code. | `Ab12 3Cd4 5Ef6` | | `ni` | string | - | National insurance number. | `QQ123456C` | | `dob` | string (date) | - | Date of birth (YYYY-MM-DD). | `1990-05-12` | | `license_checked` | string (date) | - | Date the licence was checked (YYYY-MM-DD). | `2026-06-12` | | `license_checked_by` | string | - | Business user id who checked the licence. | `3` | | `return_date` | string (date) | - | Intended return date (YYYY-MM-DD). | `2026-06-20` | | `return_time` | string | - | Intended return time (HH:MM). Defaults to 23:59 when a return date is given without a time. | `17:30` | | `fuel` | integer | - | Fuel level at handover (0-100%). | `75` | | `note` | string | - | Free-text note recorded against the drive. | `Lunchtime test drive.` | | `condition` | string | - | Id of a vehicle condition report to attach. | | | `location` | integer | - | Business location id for the handover. | `1` | | `consent` | boolean | - | Driver consent (required except for stock types that skip consent). | `true` | ```json { "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** | Status | Description | | --- | --- | | `200` OK | Start a Vehicle Test Drive | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | End the Active Test Drive | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `signature` | string | Yes | Signature image as a base64 data URL (data:image/...). | `data:image/png;base64,iVBORw0KGgo...` | | `name` | string | Yes | Printed name of the signatory. | `JOHN SMITH` | ```json { "signature": "data:image/png;base64,iVBORw0KGgo...", "name": "JOHN SMITH" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | E-Sign the Active Test Drive | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Email the Test Drive Terms | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `file` | string | Yes | Base64 file data (optionally a data: URL). | | | `filename` | string | - | Original filename (used for display and to infer the extension). | `drive-front.jpg` | | `extension` | enum | - | File extension when not derivable from the filename. | `jpg` | ```json { "file": "", "filename": "drive-front.jpg", "extension": "jpg" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Attach a Test Drive Photo | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | List Vehicle Documents | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `file` | string | Yes | Base64 file data (optionally a data: URL). | `data:application/pdf;base64,JVBERi0xLjQK...` | | `filename` | string | - | Original filename (used for display and to infer the extension). | `service-history.pdf` | | `extension` | enum | - | File extension when not derivable from the filename. | `pdf` | | `description` | string | - | Document description (required when public). | `Full service history` | | `public` | boolean | - | Whether the document is shown on the public website vehicle page. Defaults to false. | `false` | ```json { "file": "data:application/pdf;base64,JVBERi0xLjQK...", "filename": "service-history.pdf", "extension": "pdf", "description": "Full service history", "public": false } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Upload a Vehicle Document | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `document_id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Download a Vehicle Document | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `document_id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `description` | string | - | Document description (required when public). | `Full service history` | | `public` | boolean | - | A description is required when setting public to true. | | ```json { "description": "Full service history", "public": false } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Update a Vehicle Document | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `document_id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Delete a Vehicle Document | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | List Vehicle Tags | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `tags` | array of string | Yes | The 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}]` | ```json { "tags": [ { "name": "MOT", "checked": true }, { "name": "Valet", "checked": false } ] } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Set Vehicle Tags | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | List Vehicle Sales Channels | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `channels` | array 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"]` | | `options` | object | - | Per-vehicle publishing options, grouped per platform. Only the supplied platforms/fields are changed. | | | `options.autotrader` | object | - | AutoTrader publishing options. | | | `options.autotrader.advert` | boolean | - | Publish the AutoTrader retail advert. | `true` | | `options.autotrader.advertiser` | boolean | - | Include on the AutoTrader advertiser page. | | | `options.autotrader.profile` | boolean | - | Include on the AutoTrader profile. | | | `options.autotrader.locator` | boolean | - | Include in the AutoTrader locator. | | | `options.autotrader.demo` | boolean | - | Mark as ex-demonstrator. | `false` | | `options.autotrader.poa` | boolean | - | Price on application (hide price on AutoTrader). | | | `options.autotrader.exclude` | boolean | - | Exclude from the advert. | | | `options.autotrader.overwrite` | boolean | - | Allow MotorDesk to overwrite third-party changes. | | | `options.autotrader.discrepancy` | boolean | - | Ignore AutoTrader discrepancy warnings. | | | `options.dealerway` | object | - | Dealerway publishing options. | | | `options.dealerway.location` | string | - | Dealerway location id (from the business's configured Dealerway locations). | | ```json { "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** | Status | Description | | --- | --- | | `200` OK | Publish Vehicle to Sales Channels | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Get Vehicle Reservation | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `customer` | integer | Yes | Customer (contact) id to reserve for. | `60123` | | `method` | enum | Yes | Deposit payment method. "No Payment" reserves without a deposit/invoice. | `Bank Transfer` | | `deposit` | number | - | Deposit amount (gross). Defaults to the vehicle's reserve price, then the business reserve deposit. Forced to 0 for "No Payment". | `500` | | `date` | string | - | Reservation date (YYYY-MM-DD or Unix timestamp). Defaults to today. | `2026-06-13` | | `transaction` | string | - | Payment reference recorded on the deposit invoice. | `TXN-8841` | | `create_invoice` | boolean | - | 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` | ```json { "customer": 60123, "method": "Bank Transfer", "deposit": 500, "date": "2026-06-13", "transaction": "TXN-8841", "create_invoice": true } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Reserve a Vehicle | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Cancel a Vehicle Reservation | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Request an Appraisal Offer | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `offer` | number | Yes | Offer amount (greater than zero). | `8500` | | `max_offer` | number | - | Optional ceiling the offer can be raised to on acceptance; must be >= offer. | `9000` | | `expiry` | string | Yes | Offer expiry date (YYYY-MM-DD), today or later. | `2026-06-30` | | `appraised_by` | integer | Yes | Staff user id who appraised the vehicle (see GET /reference/staff-users). | `7` | | `comments` | string | - | Optional appraisal comments. | `Minor kerbing to alloys.` | ```json { "offer": 8500, "max_offer": 9000, "expiry": "2026-06-30", "appraised_by": 7, "comments": "Minor kerbing to alloys." } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Confirm an Appraisal Offer | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `agreed_amount` | number | Yes | Final agreed purchase amount. Must be between the confirmed offer and any max offer. | `8750` | ```json { "agreed_amount": 8750 } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Accept an Appraisal Offer | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Decline an Appraisal Offer | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Reopen an Appraisal | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | List Vehicle Jobs | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `board` | string | Yes | The job board to apply, identified by its numeric id or its tag (see GET /reference/job-boards). | `prep-sale` | ```json { "board": "prep-sale" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Apply a Job Board to a Vehicle | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Get a Vehicle Job | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Remove a Vehicle Job | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `name` | string | Yes | Stage name. | `Mechanical Work` | | `complete` | boolean | - | Whether the stage is complete. Defaults to false (not complete). | `false` | | `priority` | boolean | - | Flag the stage as high priority. | | | `issue` | boolean | - | Flag the stage as having an issue. | | | `users` | array of integer | - | Assigned staff user ids (see GET /reference/staff-users). | `[12]` | | `providers` | array of integer | - | Assigned service-provider (customer) ids. | | | `provider_notify` | boolean | - | Whether assigned providers are notified. Defaults to true. | | | `due_in` | integer or null | - | Days until the stage is due (sets a deadline timestamp), or null for no deadline. | `3` | ```json { "name": "Mechanical Work", "complete": false, "priority": false, "issue": false, "users": [ 12 ], "providers": [ 0 ], "provider_notify": false, "due_in": 3 } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Add a Job Stage | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `order` | array of integer | Yes | The current stage indices in their new order. Must be a complete permutation of 0..N-1. | `[2,0,1]` | ```json { "order": [ 2, 0, 1 ] } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Reorder Job Stages | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `name` | string | - | Stage name. | `Mechanical Work` | | `complete` | boolean | - | Mark the stage complete (true) or not complete (false). Completing a stage clears its issue and priority flags. | `true` | | `priority` | boolean | - | High-priority flag (cleared automatically when the stage completes). | | | `issue` | boolean | - | Issue/alert flag (cleared automatically when the stage completes). | | | `users` | array of integer | - | Assigned staff user ids (see GET /reference/staff-users). Replaces the current set. | | | `providers` | array of integer | - | Assigned external service-provider (contact) ids. Replaces the current set. | | | `provider_notify` | boolean | - | Whether assigned providers are notified. | | | `due_in` | integer or null | - | Days until due, or null to clear the deadline. | | ```json { "name": "Mechanical Work", "complete": true, "priority": false, "issue": false, "users": [ 0 ], "providers": [ 0 ], "provider_notify": false, "due_in": 0 } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Update a Job Stage | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Remove a Job Stage | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `name` | string | Yes | Task name. | `Replace brake pads` | | `status` | integer | - | 0 pending (default), 10 done. | `0` | | `instruction` | string | - | Optional task instructions. | | ```json { "name": "Replace brake pads", "status": 0, "instruction": "" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Add a Stage Task | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | | `task` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `status` | integer | - | 0 pending, 10 done. | | | `name` | string | - | Task name. | | | `instruction` | string | - | Task instructions. | | ```json { "status": 0, "name": "", "instruction": "" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Update a Stage Task | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | | `task` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Remove a Stage Task | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `note` | string | Yes | Note text. | `Waiting on parts from supplier.` | | `privacy` | boolean | - | Whether the note is private to its author. Defaults to false. | | | `user` | integer | - | Author staff user id (see GET /reference/staff-users). Defaults to the system user. | | ```json { "note": "Waiting on parts from supplier.", "privacy": false, "user": 0 } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Add a Stage Note | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | | `note` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Remove a Stage Note | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `hour` | integer | - | Hours worked. Defaults to 0. | `1` | | `minute` | integer | - | Minutes worked (0-59). Defaults to 0. | `30` | | `total` | integer | - | Explicit total minutes, overriding hour*60+minute. | | | `user` | integer | - | Staff user id the time is logged against. Defaults to the system user. | | | `time` | integer | - | Unix timestamp of the entry. Defaults to now. | | ```json { "hour": 1, "minute": 30, "total": 0, "user": 0, "time": 0 } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Add a Stage Clocking Entry | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | | `entry` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Remove a Stage Clocking Entry | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `file` | string | Yes | Base64 file data (optionally a data: URL). | `data:application/pdf;base64,JVBERi0xLjQK...` | | `filename` | string | - | Original filename (used for display and to infer the extension). | `inspection.pdf` | | `extension` | enum | - | File extension when not derivable from the filename. | `pdf` | ```json { "file": "data:application/pdf;base64,JVBERi0xLjQK...", "filename": "inspection.pdf", "extension": "pdf" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Upload a Stage Document | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | | `document_id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Remove a Stage Document | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | **Request body** | Attribute | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `file` | string | Yes | Base64 file data (optionally a data: URL). | | | `filename` | string | - | Original filename (used for display and to infer the extension). | `parts-invoice.pdf` | | `extension` | enum | - | File extension when not derivable from the filename. | `pdf` | ```json { "file": "", "filename": "parts-invoice.pdf", "extension": "pdf" } ``` **Responses** | Status | Description | | --- | --- | | `200` OK | Upload a Stage Purchase Invoice | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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)** | Parameter | In | Type | Required | Description | Example | | --- | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Resource identifier in the path. | | | `job_id` | path | string | Yes | Resource identifier in the path. | | | `stage` | path | string | Yes | Resource identifier in the path. | | | `purchase_id` | path | string | Yes | Resource identifier in the path. | | **Responses** | Status | Description | | --- | --- | | `200` OK | Remove a Stage Purchase | Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope. ```json { "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 } ] } } ```