API
Sign Up

Vehicle history check API: outstanding finance, stolen and write-off records

Last updated: 9 November 2026

POST a registration or VIN to /api/v1/vehicle/provenance and you get the car's provenance check as JSON: outstanding finance agreements, the police stolen record, insurer theft records, insurance write-off records with the category, and a list of alerts. It costs £2.99 a call on Pay As You Go, down to £2.20 on Enterprise. Sandbox keys are free and answer for the published test registrations (GET /v1/sandbox/vrms, no key needed), so you can build the whole integration before paying for a call.

Unlike every other endpoint, the provenance answer keeps every field: null means "not held for this check", never "no", and false or 0 means the record was checked and is clear.

Keeper history, plate changes, colour changes, import and export and scrapped markers come from the decode endpoint, and MOT mileage from the tax and MOT endpoint, so a full history report is usually these three calls together.

Get a free sandbox keyTry it in the test consoleAll prices

Prices per call

Prices in force today, per call, by package. Errors are not charged except where the API reference says so. Live keys only: sandbox calls are free.

EndpointPay As You GoStarterProEnterprise
Provenance check
POST /api/v1/vehicle/provenance
Outstanding finance, police stolen record, insurer theft and write-off records, with alerts.
Daily cap per account: 25 / 100 / 250 / 500
£2.99£2.75£2.50£2.20
Vehicle decode
POST /api/v1/vehicle/decode
Keepers, plate changes, colour history, import, export and scrapped markers.
Daily cap per account: 300 / 1,000 / 3,000 / 10,000
16p10p8p6p
Tax and MOT
POST /api/v1/vehicle/tax-mot
MOT history with mileage at every test.
5p4p3p2p

Pay As You Go has no monthly fee (top up from £10). On Starter, Pro, Enterprise the monthly fee comes back as plan credit to spend on calls, expiring at the end of each monthly billing period. Package limits per second, minute and day are on the pricing page.

Example request and answer

Every endpoint is a JSON POST under https://www.dealerpricing.co.uk/api with your key in the X-API-Key header. This request uses a sandbox test value, so it is free with a sandbox key.

curl -X POST https://www.dealerpricing.co.uk/api/v1/vehicle/provenance \
  -H "X-API-Key: your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{"vrm":"RO21PAD"}'

The answer (long lists shortened; fields not held for a vehicle are left out):

{
  "success": true,
  "data": {
    "provenance": {
      "vrm": "RO21PAD",
      "check_date": "2026-11-06T10:15:00.000Z",
      "vehicle": {
        "vin": "LSJWP4396SZ244868"
      },
      "finance": {
        "has_outstanding_finance": true,
        "finance_records": 1,
        "finance_details": [
          {
            "agreement_date": "2026-05-01",
            "agreement_type": "PCP",
            "agreement_number": "REDACTED",
            "agreement_term_months": 49,
            "finance_company": "BLACK HORSE LTD",
            "contact_number": "REDACTED",
            "vehicle_description": "MG MOTOR UK MG3 HATCHBACK",
            "is_stock_funding": false
          }
        ]
      },
      "stolen": {
        "is_stolen": false,
        "police_marked_stolen": false,
        "insurer_theft_recorded": false,
        "police": {
          "marked_stolen": false,
          "date_reported_stolen": null,
          "police_force": null,
          "record_status": null,
          "record_added_at": null,
          "vrm": null,
          "vin": null
        },
        "insurer_theft_records": []
      },
      "write_off": {
        "is_write_off": true,
        "category": "B",
        "date": "2026-04-27",
        "categories": [
          "B"
        ],
        "write_off_records": [
          {
            "category": "B",
            "status": "CAT B BODY CRUSHED",
            "loss_date": "2026-04-27",
            "entry_date": "2026-04-27",
            "insurer": "FIRST CENTRAL UNDERWRITING LIM",
            "insurer_branch": "00",
            "insurer_code": "487",
            "claim_number": "REDACTED",
            "contact_number": "03330432022",
            "theft_indicator": "66",
            "theft_indicator_literal": "NOT STOLEN",
            "loss_type": "0"
          }
        ]
      },
      "alerts": {
        "has_alerts": true,
        "alert_count": 2,
        "alert_list": [
          "Outstanding finance recorded",
          "Insurance write-off (Category B)"
        ]
      },
      "raw": {}
    }
  },
  "meta": {
    "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01",
    "cost_pence": 299,
    "balance_pence": 701,
    "is_sandbox": false
  }
}

What you get

provenance.finance.has_outstanding_finance
Outstanding finance, with the number of records
provenance.finance.finance_details[].agreement_type
Each agreement: type, date, term, finance company and whether it is stock funding
provenance.stolen.is_stolen
Stolen: police_marked_stolen and insurer_theft_recorded
provenance.stolen.police.date_reported_stolen
Police record: date reported, force and record status
provenance.write_off.is_write_off
Write-off, with the category and date
provenance.write_off.write_off_records[].status
Each write-off record: category, status, loss date and insurer
provenance.alerts.alert_list
Plain-English alerts, with has_alerts and alert_count

Every field, with its type and meaning, is in the API reference.

What developers use it for

  • Check a car for finance, theft and write-off before you buy it for stock.
  • Add a history check to your own branded vehicle report.
  • Screen part exchanges automatically.

Questions

What does the vehicle history check API cover?

Outstanding finance agreements, the police stolen record, insurer theft records and insurance write-off records (with the category), plus a list of alerts. Keepers, plate changes, import and export, scrapped markers and MOT mileage come from the decode and tax and MOT endpoints.

How much does a history check cost through the API?

Pay As You Go £2.99, Starter £2.75, Pro £2.50, Enterprise £2.20 a check. A vehicle that is not found is not charged. On the monthly packages the whole fee comes back as plan credit to spend on calls. It expires at the end of each monthly billing period.

Is this an HPI check API?

No. HPI is another company's brand of vehicle history check. This is DealerPricing's own provenance check, which covers finance, stolen and write-off records, so it can be used as an alternative in your own software and reports.

What does null mean in the answer?

null means the item was not held for this check. false or 0 means it was checked and is clear. The provenance answer is the only one that keeps null fields, so you can tell the two apart.

Can I check by VIN?

Yes. Send vrm or vin. When both are sent, the VIN is used.

Is there a daily limit?

Yes, per account: Pay As You Go 25, Starter 100, Pro 250, Enterprise 500 checks a day, reset at midnight UK time.

Can I test it for free?

Yes. Sandbox keys are free. RO21PAD is a test registration with a Category B write-off and a finance record, and the full sandbox list is at GET /v1/sandbox/vrms.

Documentation and next steps