{ "openapi": "3.0.3", "info": { "title": "Full Vehicle Check API", "version": "1.0.0", "description": "The complete picture in a single request: DVLA details, full MOT history, a current valuation and the provenance risk check \u2014 merged into one normalized response.\n\nCheaper than calling each product separately, and one round-trip for your users." }, "servers": [ { "url": "https://vehiclematic.com/products/full-vehicle-check/api/live", "description": "Live" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Lookups", "description": "Look up Full Vehicle Check data by UK registration." } ], "paths": { "/{vrm}": { "get": { "tags": [ "Lookups" ], "operationId": "lookup", "summary": "Look up by registration", "description": "Returns Full Vehicle Check for a single UK registration (VRM). Costs \u00a33.25 per lookup on Tier 1, down to \u00a32.45 on the largest top-up tier.", "parameters": [ { "name": "vrm", "in": "path", "required": true, "description": "UK vehicle registration mark.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{1,8}$", "example": "AB12CDE" } }, { "name": "format", "in": "query", "required": false, "description": "Response format. Defaults to JSON.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Successful lookup.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "vrm": { "type": "string" }, "registration_number": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "colour": { "type": "string" }, "fuel_type": { "type": "string" }, "engine_capacity": { "type": "integer" }, "year_of_manufacture": { "type": "integer" }, "month_of_first_registration": { "type": "string" }, "co2_emissions": { "type": "integer" }, "tax_status": { "type": "string" }, "tax_due_date": { "type": "string" }, "mot_status": { "type": "string" }, "mot_expiry_date": { "type": "string" }, "wheelplan": { "type": "string" }, "export_marker": { "type": "boolean" }, "mot_history": { "type": "array", "items": { "type": "object", "properties": { "test_date": { "type": "string" }, "result": { "type": "string" }, "odometer": { "type": "integer" }, "odometer_unit": { "type": "string" }, "expiry_date": { "type": "string" }, "advisories": { "type": "array", "items": { "type": "string" } } } } }, "valuation": { "type": "object", "properties": { "trade": { "type": "integer" }, "retail": { "type": "integer" }, "private": { "type": "integer" }, "currency": { "type": "string" } } }, "provenance": { "type": "object", "properties": { "write_off": { "type": "boolean" }, "write_off_category": { "type": "string" }, "outstanding_finance": { "type": "boolean" }, "stolen": { "type": "boolean" }, "scrapped": { "type": "boolean" }, "exported": { "type": "boolean" } } } } }, "credit_balance": { "type": "integer" } } }, "example": { "data": { "vrm": "AB12CDE", "registration_number": "AB12CDE", "make": "FORD", "model": "FIESTA", "colour": "BLUE", "fuel_type": "PETROL", "engine_capacity": 1499, "year_of_manufacture": 2019, "month_of_first_registration": "2019-03", "co2_emissions": 119, "tax_status": "Taxed", "tax_due_date": "2026-09-01", "mot_status": "Valid", "mot_expiry_date": "2026-03-14", "wheelplan": "2 AXLE RIGID BODY", "export_marker": false, "mot_history": [ { "test_date": "2025-03-12", "result": "PASSED", "odometer": 48210, "odometer_unit": "mi", "expiry_date": "2026-03-14", "advisories": [ "Nearside front tyre worn close to the legal limit" ] }, { "test_date": "2024-03-05", "result": "FAILED", "odometer": 36940, "odometer_unit": "mi", "expiry_date": null, "advisories": [ "Offside rear brake disc worn" ] } ], "valuation": { "trade": 6450, "retail": 8195, "private": 7300, "currency": "GBP" }, "provenance": { "write_off": false, "write_off_category": null, "outstanding_finance": false, "stolen": false, "scrapped": false, "exported": false } }, "credit_balance": 499 } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "error": true, "message": "Insufficient credits.", "credit_balance": 0 } } } }, "403": { "description": "This API key is not authorised for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "error": true, "message": "This API key is not authorised for this product." } } } }, "422": { "description": "Missing or invalid registration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "error": true, "message": "A vrm parameter is required." } } } } } } }, "/lookup": { "post": { "tags": [ "Lookups" ], "operationId": "bulkLookup", "summary": "Bulk lookup", "description": "Look up many registrations in one request (up to 50). Each result is charged at your per-lookup tier price. Processing stops when the balance is exhausted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vrms" ], "properties": { "vrms": { "type": "array", "items": { "type": "string", "example": "AB12CDE" }, "maxItems": 50, "description": "Registrations to look up." } } }, "example": { "vrms": [ "AB12CDE", "XY19ABC" ] } } } }, "responses": { "200": { "description": "Results, one per registration, in request order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "vrm": { "type": "string" }, "registration_number": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "colour": { "type": "string" }, "fuel_type": { "type": "string" }, "engine_capacity": { "type": "integer" }, "year_of_manufacture": { "type": "integer" }, "month_of_first_registration": { "type": "string" }, "co2_emissions": { "type": "integer" }, "tax_status": { "type": "string" }, "tax_due_date": { "type": "string" }, "mot_status": { "type": "string" }, "mot_expiry_date": { "type": "string" }, "wheelplan": { "type": "string" }, "export_marker": { "type": "boolean" }, "mot_history": { "type": "array", "items": { "type": "object", "properties": { "test_date": { "type": "string" }, "result": { "type": "string" }, "odometer": { "type": "integer" }, "odometer_unit": { "type": "string" }, "expiry_date": { "type": "string" }, "advisories": { "type": "array", "items": { "type": "string" } } } } }, "valuation": { "type": "object", "properties": { "trade": { "type": "integer" }, "retail": { "type": "integer" }, "private": { "type": "integer" }, "currency": { "type": "string" } } }, "provenance": { "type": "object", "properties": { "write_off": { "type": "boolean" }, "write_off_category": { "type": "string" }, "outstanding_finance": { "type": "boolean" }, "stolen": { "type": "boolean" }, "scrapped": { "type": "boolean" }, "exported": { "type": "boolean" } } } } } }, "requested": { "type": "integer" }, "returned": { "type": "integer" }, "credit_balance": { "type": "integer" } } }, "example": { "data": [ { "vrm": "AB12CDE", "registration_number": "AB12CDE", "make": "FORD", "model": "FIESTA", "colour": "BLUE", "fuel_type": "PETROL", "engine_capacity": 1499, "year_of_manufacture": 2019, "month_of_first_registration": "2019-03", "co2_emissions": 119, "tax_status": "Taxed", "tax_due_date": "2026-09-01", "mot_status": "Valid", "mot_expiry_date": "2026-03-14", "wheelplan": "2 AXLE RIGID BODY", "export_marker": false, "mot_history": [ { "test_date": "2025-03-12", "result": "PASSED", "odometer": 48210, "odometer_unit": "mi", "expiry_date": "2026-03-14", "advisories": [ "Nearside front tyre worn close to the legal limit" ] }, { "test_date": "2024-03-05", "result": "FAILED", "odometer": 36940, "odometer_unit": "mi", "expiry_date": null, "advisories": [ "Offside rear brake disc worn" ] } ], "valuation": { "trade": 6450, "retail": 8195, "private": 7300, "currency": "GBP" }, "provenance": { "write_off": false, "write_off_category": null, "outstanding_finance": false, "stolen": false, "scrapped": false, "exported": false } } ], "requested": 1, "returned": 1, "credit_balance": 499 } } } }, "422": { "description": "Too many registrations (max 50).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "error": true, "message": "A maximum of 50 registrations may be looked up per request." } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-VEHICLEMATIC-KEY", "description": "Your API key. Create one on the API access page in your portal." } } } }