API Documentation

Tax & MOT

Two government sources answer this endpoint: DVLA (tax status, MOT status and the vehicle details) and DVSA (MOT test history and its own record of the vehicle). data.sources shows what each one answered: found, not_found or unavailable.

• DVLA holds no record for some vehicles, often classic and historic vehicles, or registrations that have been moved to another vehicle or put on retention. The vehicle is then identified from DVSA: vehicle.source is dvsa, the make, model, colour, fuel, engine size and first-registration date come from the MOT record, and tax and mot are omitted because DVLA is the only source for them.
• No MOT tests can be normal: vehicles over 40 years old can be exempt from the MOT, a new vehicle has its first test at three years, and MOT records online go back to 2005. mot_history.total_tests is then 0.
• If neither source identifies the vehicle you get 404 VEHICLE_NOT_FOUND and are not charged.
• A call is charged at the endpoint price whenever either source returns data, even if the other could not be reached. For example, if DVLA is temporarily unavailable but DVSA knows the vehicle, you get the vehicle details and MOT history with sources.dvla set to unavailable and no tax block.
• If neither source returns data and one of them could not be reached (an error or a timeout), you get 502 UPSTREAM_ERROR and are not charged, so you can retry.

{
  "vrm": "EBY776J",
  "sources": { "dvla": "not_found", "mot": "found" },
  "vehicle": {
    "make": "ASTON MARTIN",
    "model": "DB6",
    "colour": "BLUE",
    "year_of_manufacture": 1971,
    "first_registration_date": "1971-08-01",
    "engine_capacity": 4200,
    "fuel_type": "PETROL",
    "source": "dvsa"
  },
  "mot_history": { "total_tests": 20, "tests": [ ... ] }
}

Market data

/v1/market/active, /v1/market/sold, /v1/market/insights and /v1/pricing/insights look at cars like the one you send: live adverts from UK dealer websites, and adverts that have recently sold.

Request fields

• vrm (required): the registration.
• rows (active and sold listings): how many listings to return. Default 50, maximum 200.
• match (active and sold listings, optional): which optional filters to use - see below.
• price (pricing insights, optional): your asking price in pounds, to see where it sits in the market.

Which cars are compared

• Always matched: make, model, year, trim (the trims that match the car) and number of doors.
• Matched unless you say otherwise: gearbox (transmission) and body type (body_type). To turn one off, send match with the ones you want to keep, for example "match": "transmission" keeps the gearbox and drops body type. Without match, both apply.
• Fuel type, engine size and drive are not matched yet. If you list them in match, the response names them in match_not_applied.
• match_criteria in the response lists what was matched for your request.
• The search is never widened for you. If only a few cars match, you get those few.

Listings and totals

• Listings come cheapest first, and only adverts that show a price are included.
• total_found is how many matching adverts there are, not how many were returned. When there are more than we fetch, it is worked out from the share of fetched adverts that matched, and total_estimated is true.
• The insights count live supply the same way: supply.active_listings with supply.estimated, and market_overview.active_supply with active_supply_estimated.
• Sold figures in the insights (sold in the last 90 days, days to sell, sold prices) cover every sold advert for the same make, model, trims and year. Price figures leave out adverts with no price.
• The summary in sold listings covers only the cars in that response, which are the cheapest. For sold prices across the whole market, use the insights.
• With price, pricing insights ranks your price against every matching advert with a price. compared_with says how many, and estimated is true when that number is estimated.

curl -X POST https://www.dealerpricing.co.uk/api/v1/market/active \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"vrm": "SA22TLZ", "rows": 100}'

{
  "success": true,
  "data": {
    "vrm": "SA22TLZ",
    "total_found": 87,
    "total_estimated": true,
    "listings_returned": 61,
    "match_criteria": "make,model,year,variant,transmission,body_type,doors",
    "listings": [
      { "price": 9495, "miles": 18250, "year": 2022, "variant": "Life Tsi",
        "transmission": "Manual", "days_on_market": 12, ... }
    ]
  },
  "meta": { "request_id": "...", "cost_pence": 15, "balance_pence": 985, "is_sandbox": false }
}

Charging

A registration our vehicle data cannot identify returns 404 VEHICLE_NOT_FOUND and is not charged. If one of our data sources fails you get 502 UPSTREAM_ERROR, also not charged, and you can retry.

What changed in October 2026

• Listings responses could hold no more than 10 cars. They now return up to rows (maximum 200).
• total_found and the supply figures were counts of returned cars. They are now market totals, so supply levels, the market rating and price positions change.
• Gearbox matching now works: a manual car is no longer compared with automatics, or the other way round.
• Adverts without a price are no longer listed first.
• match_criteria used to repeat a default list; it now shows what was really matched.
• A registration we cannot identify used to return an empty, charged answer. It is now a free 404.
• Sandbox market data is taken again, the new way, the first time each sandbox registration is asked for.

Service history (asynchronous)

A digital service history comes from the vehicle's manufacturer, and that request is not answered instantly: most complete within a few minutes, around one in ten takes over two hours, and a request is abandoned after four days. So POST /v1/vehicle/service-history accepts the request and answers 202; you then either poll the status URL or give us a callback_url and we call you when it is done. Registration only - the provider has no VIN lookup. Once completed you receive the extracted records and, when the manufacturer supplied one, a link to the PDF (pdf_url).

1. Request

curl -X POST https://www.dealerpricing.co.uk/api/v1/vehicle/service-history \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"vrm": "SA22TLZ", "callback_url": "https://example.com/hooks/dealerpricing"}'

HTTP/1.1 202 Accepted
{
  "success": true,
  "data": {
    "request_id": "6c1f4e2a-...",
    "vrm": "SA22TLZ",
    "status": "pending",
    "message": "Request accepted. The manufacturer is being asked ...",
    "requested_at": "2026-09-08T09:00:00.000Z",
    "check_after_seconds": 30,
    "status_url": "https://www.dealerpricing.co.uk/api/v1/vehicle/service-history/6c1f4e2a-...",
    "callback_url": "https://example.com/hooks/dealerpricing",
    "cost_pence": 200,
    "refunded_pence": 0
  },
  "meta": { "request_id": "...", "cost_pence": 200, "balance_pence": 1800, "is_sandbox": false }
}

Every request runs a fresh search of the manufacturer network, so you always get the latest records. If a search for that plate is already in progress we add your request to it rather than asking twice. Posting the same plate again while your request is open returns the open request (202) and is not charged, although your balance must still cover the price to make the call - polling belongs on the status endpoint below. As everywhere in this API, fields with no value (completed_at, error, service_history while pending) are omitted.

2. Poll the status (free)

curl https://www.dealerpricing.co.uk/api/v1/vehicle/service-history/6c1f4e2a-... \
  -H "X-API-Key: your_api_key_here"

{
  "success": true,
  "data": {
    "request_id": "6c1f4e2a-...",
    "vrm": "SA22TLZ",
    "status": "completed",
    "completed_at": "2026-09-08T09:04:12.000Z",
    "service_history": {
      "record_count": 2,
      "services": [
        { "date": "2024-03-11", "date_raw": "11/03/2024", "type": "Service / Repair",
          "mileage": 18420, "mileage_raw": "18,420 mi", "workshop": "OEM data",
          "notes": "Scheduled Service Completed 2 Years (20000 ml) ..." },
        { "date": "2022-03-04", "date_raw": "04/03/2022", "type": "Service / Repair",
          "mileage": 13, "mileage_raw": "13 mi", "workshop": "OEM data", "notes": "Pre-Delivery Inspection" }
      ],
      "retrieved_at": "2026-09-08T09:04:12.000Z"
    },
    "pdf_url": "https://www.dealerpricing.co.uk/api/service-history/pdf/9b2d...?t=...",
    "pdf_url_expires_in_seconds": 604800,
    "readable_until": "2026-09-15T09:04:12.000Z",
    ...
  }
}

status moves through pending (the manufacturer is being asked) → processing (records found, being extracted) → completed, or ends as failed. Wait at least check_after_seconds between polls. Status checks do not cost anything and do not count towards your balance: reading a request you have already paid for never runs a new search. A completed request includes pdf_url when the manufacturer supplied a PDF. The link opens only that vehicle's PDF and stops working after at most 7 days (pdf_url_expires_in_seconds); call the status endpoint again for a new link, free of charge. A finished request (completed or failed) can be read for 7 days after it finished, shown as readable_until. After that the status endpoint answers 410 REQUEST_EXPIRED, any PDF link stops working, and a new request (a new, charged search) is needed. Save the records and the PDF on your side if you need them for longer.

3. Or receive a callback

Pass an https callback_url and we POST the finished request to it once - the same JSON as the status endpoint, wrapped as below. Respond with any 2xx within 10 seconds; otherwise we retry after 1, 10 and 60 minutes. Callbacks are a notification you can trust only after confirming with the status endpoint using your API key, so never act on the body alone.

POST https://example.com/hooks/dealerpricing
X-DealerPricing-Event: service_history.completed
X-DealerPricing-Request-Id: 6c1f4e2a-...

{ "event": "service_history.completed", "request_id": "6c1f4e2a-...", "sent_at": "...", "data": { ...status response... } }

Charging

• The endpoint price is taken when the request is accepted (cost_pence).
• It is refunded in full when the search finds no records (record_count: 0, including manufacturers outside the coverage list) and when the request fails because of a fault (status failed: the provider or our pipeline could not complete it, or it was abandoned after four days). refunded_pence shows the refund. Searches that return records are charged.
• A request is charged at the price in force when it is accepted; any refund gives back exactly that amount.
• Each new request is a fresh search and is charged; status checks and new PDF links for a request you already made are free for 7 days after it finished.
• Up to 25 requests may be in progress on an account at once (429 beyond that).

Sandbox

Sandbox keys go through the same lifecycle so you can build the polling or callback handling properly: 202 pending first, then completed about 20 seconds later with frozen records and, for plates that have one, a pdf_url to a sample manufacturer PDF so you can test the download. Sandbox requests are free. Only the plates listed under Service history available answer; other sandbox plates return 404.