{ "info": { "_postman_id": "5d1f0c3e-7a42-4b8e-9c61-2f0e8d4b7a10", "name": "DealerPricing Developer API", "description": "DealerPricing Developer API.\n\nBefore your first request: open this collection, go to Variables and paste your SANDBOX key (it starts dp_sandbox_) into the Current value of `api_key`. Sandbox keys are free and answer only for the published test registrations (see \"Sandbox registrations\" below). The value stays on your machine; never share an exported collection that contains a key.\n\n`base_url` is the live API. Live keys (dp_live_) are charged at your package prices.\n\nReference: https://www.dealerpricing.co.uk/developer/reference\nErrors: https://www.dealerpricing.co.uk/developer/errors\nChangelog: https://www.dealerpricing.co.uk/developer/changelog", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "version": "1.2.0" }, "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key", "type": "string" }, { "key": "value", "value": "{{api_key}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://www.dealerpricing.co.uk/api", "type": "string" }, { "key": "api_key", "value": "", "type": "string", "description": "Paste your sandbox key (dp_sandbox_...) here. Left empty on purpose." } ], "item": [ { "name": "Vehicle data", "item": [ { "name": "Vehicle decode", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/vehicle/decode", "host": [ "{{base_url}}" ], "path": [ "v1", "vehicle", "decode" ] }, "description": "The vehicle's identity and registration record: make, model, engine, power, keepers, plate changes, colour history, import and export, scrapped status and vehicle tax rates. Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22TLZ\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Specification", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/vehicle/spec", "host": [ "{{base_url}}" ], "path": [ "v1", "vehicle", "spec" ] }, "description": "Manufacturer specification: engine, performance, transmission, dimensions, economy, practicality, safety ratings and factory-fitted equipment. Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22TLZ\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Valuation", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/vehicle/valuation", "host": [ "{{base_url}}" ], "path": [ "v1", "vehicle", "valuation" ] }, "description": "Retail, trade, private, part exchange and auction values in pounds. Send `mileage` for a mileage-adjusted figure; without it the source's standard mileage is used. Sandbox valuations are frozen and ignore `mileage` (mileage_used shows the mileage the figure was produced at). Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22TLZ\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Provenance", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/vehicle/provenance", "host": [ "{{base_url}}" ], "path": [ "v1", "vehicle", "provenance" ] }, "description": "Outstanding finance, police stolen record, insurer theft and write-off records, with alerts. Unlike every other endpoint, provenance keeps every field: `null` means \"not held for this check\", never \"no\"; `false` or `0` means the record was checked and is clear. Keeper history, plate changes, colour and import or export come from /v1/vehicle/decode; mileage and MOT from /v1/vehicle/tax-mot. Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"RO21PAD\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Tax and MOT", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/vehicle/tax-mot", "host": [ "{{base_url}}" ], "path": [ "v1", "vehicle", "tax-mot" ] }, "description": "Vehicle tax status, MOT status and full MOT test history from the two free government sources. `sources` says what each one answered. When the vehicle register holds no record (common for classic vehicles and plates on retention) the vehicle is identified from the MOT record and `tax` and `mot` are omitted. Charged whenever either source returns data; 404 VEHICLE_NOT_FOUND (not charged) when neither knows the vehicle; 502 SOURCE_UNAVAILABLE (version 1: UPSTREAM_ERROR; not charged, retry) when neither returns data and one could not be reached.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22TLZ\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Service history", "item": [ { "name": "Service history: start a request", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/vehicle/service-history", "host": [ "{{base_url}}" ], "path": [ "v1", "vehicle", "service-history" ] }, "description": "Digital service records from the manufacturer network. Asynchronous: the answer is usually `202` with status `pending`; poll `status_url` (free) or pass an https `callback_url`. Every request runs a fresh search. A request for the same vehicle made in the last 10 minutes, or still in progress, is shared, and when that search has already finished the answer is `200` with the records. Posting the same vehicle again while your request is open returns it (`202`) without a new charge, but your balance must still cover the price. Up to 25 requests may be open per account (429 beyond that).\n\nCharging: the price is taken when the request is accepted, refunded in full when the search finds no records (including manufacturers outside coverage) or fails because of a fault. Covered manufacturers: Audi, BMW, Cupra, Ford, Jaguar, Land Rover, Lexus, Mazda, Mercedes-Benz, MG, MINI, Nissan, Porsche, Renault, Rolls-Royce, SEAT, Skoda, Smart, Toyota and Volkswagen.\n\nSandbox: free; `202 pending` first, then `completed` about 20 seconds later with stored records. SK22AOM answers with a generic sample report: made-up records marked `sample: true` with a `sample_notice` (one of them kept in kilometres), and a sample PDF. RE22MOA ends with no records (`record_count: 0`, `outcome: no_records`) and RO22AXH ends as `failed` (`outcome: failed`, `error_code: SOURCE_UNAVAILABLE`), so you can test both. Sandbox requests are free, so nothing is charged or refunded. Only registrations in the \"Service history available\" sandbox group answer, and sandbox answers carry `meta.data_captured_at`.\n\nRecords: `mileage_unit` says whether `mileage` is in miles or kilometres (or unknown). `workshop` is usually not supplied by the manufacturer network. With version 2 of the error codes (see DP-Error-Codes) the \"OEM data\" workshop placeholder is omitted and a 0 mileage on a record that is not the delivery record is omitted (not recorded); `mileage_raw` is always sent as the record shows it. For Mercedes-Benz the mileage of each visit comes from the manufacturer's report, in its own unit.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SK22AOM\",\n \"callback_url\": \"https://example.com/hooks/dealerpricing\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Service history: request status", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/vehicle/service-history/:request_id", "host": [ "{{base_url}}" ], "path": [ "v1", "vehicle", "service-history", ":request_id" ], "variable": [ { "key": "request_id", "value": "6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11", "description": "The request_id from the start request." } ] }, "description": "The current state of a service history request made on your account, and once completed the records and a fresh `pdf_url` when a manufacturer PDF is stored. Free, never runs a new search. Wait at least `check_after_seconds` between polls. A finished request can be read for 7 days (`readable_until`); after that the answer is 410 REQUEST_EXPIRED. POST to the same URL works the same way." }, "response": [] } ] }, { "name": "Market data", "item": [ { "name": "Active listings", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/market/active", "host": [ "{{base_url}}" ], "path": [ "v1", "market", "active" ] }, "description": "Similar vehicles for sale now on UK dealer websites, cheapest first, adverts with a price only. Always matched: make, model, year (the registration year when the car was registered the year after it was built, else the build year), matching trims and doors. Gearbox (`transmission`), body type (`body_type`) and engine size within 0.2 litres (`engine_size`) are matched unless you send `match` without them. The search is never widened. A search that finds no adverts is a successful answer and is charged. Fields we do not hold for an advert or a car are left out (adverts differ in what they say, and figures need enough sold cars), never sent as null or a placeholder. The schema shows version 2 answers; fields that differ in version 1 say how. Sandbox answers carry meta.data_captured_at, when the stored test data was captured. Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22LZH\",\n \"rows\": 1\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Sold listings", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/market/sold", "host": [ "{{base_url}}" ], "path": [ "v1", "market", "sold" ] }, "description": "Similar vehicles recently sold, cheapest first, with a summary of the listings returned. Same matching rules as /v1/market/active, with the trims taken from recently sold adverts. \"Sold\" means the advert ended and did not reappear; the price is the last asking price. A search that finds no adverts is a successful answer and is charged. Fields we do not hold for an advert or a car are left out (adverts differ in what they say, and figures need enough sold cars), never sent as null or a placeholder. The schema shows version 2 answers; fields that differ in version 1 say how. Sandbox answers carry meta.data_captured_at, when the stored test data was captured. Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22LZH\",\n \"rows\": 1\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Market insights", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/market/insights", "host": [ "{{base_url}}" ], "path": [ "v1", "market", "insights" ] }, "description": "Supply (live adverts, matched as for /v1/market/active), demand (sold in the last 90 days, days to sell), sold prices across the whole market and a market rating out of 10. Sold figures are matched like the live adverts (gearbox, body and engine included) and count adverts with a price only. With no sold data there is no rating. Fields we do not hold for an advert or a car are left out (adverts differ in what they say, and figures need enough sold cars), never sent as null or a placeholder. The schema shows version 2 answers; fields that differ in version 1 say how. Sandbox answers carry meta.data_captured_at, when the stored test data was captured. Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22LZH\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Analysis", "item": [ { "name": "Pricing insights", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/pricing/insights", "host": [ "{{base_url}}" ], "path": [ "v1", "pricing", "insights" ] }, "description": "The vehicle summary, market overview, sold prices, a recommended price range and, when you send `price`, where your asking price sits against every matching advert with a price. Matching and sold figures as for /v1/market/insights. Fields we do not hold for an advert or a car are left out (adverts differ in what they say, and figures need enough sold cars), never sent as null or a placeholder. The schema shows version 2 answers; fields that differ in version 1 say how. Sandbox answers carry meta.data_captured_at, when the stored test data was captured. Not charged when the answer is an error (404, 502 and so on): the price taken up front is refunded before the response is sent.", "body": { "mode": "raw", "raw": "{\n \"vrm\": \"SA22LZH\",\n \"price\": 14500\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Sandbox", "item": [ { "name": "Sandbox registrations", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/sandbox/vrms", "host": [ "{{base_url}}" ], "path": [ "v1", "sandbox", "vrms" ] }, "description": "Every registration a sandbox key can query, with the scenario it exercises and the markers its record carries. Public: no API key needed. Sandbox data may not be accurate and is for testing only.", "auth": { "type": "noauth" } }, "response": [] } ] }, { "name": "Reference", "item": [ { "name": "This OpenAPI description", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/openapi.json", "host": [ "{{base_url}}" ], "path": [ "v1", "openapi.json" ] }, "description": "This document, as JSON. Public: no API key needed. Also at /developer/openapi.json.", "auth": { "type": "noauth" } }, "response": [] } ] } ] }