{ "openapi": "3.1.0", "info": { "title": "DealerPricing Developer API", "version": "1.2.0", "summary": "UK vehicle data, valuations, provenance, MOT, service history and live market data.", "description": "REST API for UK vehicle data. Every endpoint is a JSON POST (the status and sandbox list endpoints also answer GET) under the base URL below.\n\nAuthentication: send your key in the `X-API-Key` header. Live keys start `dp_live_`, sandbox keys `dp_sandbox_`. Create keys on the Keys page of the developer portal. Never put a key in browser code or a public repository.\n\nSandbox keys are free and answer only for the published test registrations (GET /v1/sandbox/vrms). Sandbox data may not be accurate and is for testing only. Sandbox limits: 2/s, 30/min, 300/day per key and 1,000/day across all sandbox keys on an account.\n\nLive keys follow your package limits across all live keys on the account (Pay As You Go: 2/s, 60/min, 500/day; Starter: 5/s, 100/min, 2,000/day; Pro: 10/s, 300/min, 5,000/day; Enterprise: 20/s, 600/min, 15,000/day); some endpoints also have a daily cap. Daily limits reset at midnight UK time.\n\nCharging: live calls are charged on success at your package price. Errors are not charged (the price taken up front is refunded before the response). Every answer carries meta.cost_pence and meta.balance_pence.\n\nErrors: every error carries a machine-readable `code`, its `type` (whose side the fault is on), `retryable`, `charged` and a `doc_url`. Version 2 codes are the default for new accounts and, from 1 February 2027, for everyone; accounts that had a live key before 5 November 2026 keep version 1 until then (version 1 answers also carry `next_code`, version 2 answers `legacy_code` until 2 May 2027). Choose per request with the `DP-Error-Codes` header (1 or 2) or for the account in the developer portal.\n\nTemporary source failures are retried automatically before we answer, and never at your cost: a request that still fails is not charged and answers 502 SOURCE_UNAVAILABLE (retryable), or 503 SOURCE_LIMIT_REACHED when a source will not answer us again until its daily reset.\n\nWebhooks: account events (balance, keys, plan, service history, limits, account, announcements) are sent to your HTTPS endpoints, signed with the `DP-Signature` header, as listed under webhooks below. Service history callbacks are signed the same way.\n\nNulls: every endpoint omits fields it does not hold, except provenance, which keeps them as null (\"not held for this check\").\n\nChanges: https://www.dealerpricing.co.uk/developer/changelog. Error codes: https://www.dealerpricing.co.uk/developer/errors. Reference: https://www.dealerpricing.co.uk/developer/reference.", "termsOfService": "https://www.dealerpricing.co.uk/developer/terms", "contact": { "name": "DealerPricing developer support", "email": "support@dealerpricing.co.uk", "url": "https://www.dealerpricing.co.uk/developer/reference" }, "x-updated": "2026-11-06" }, "externalDocs": { "description": "Developer reference", "url": "https://www.dealerpricing.co.uk/developer/reference" }, "servers": [ { "url": "https://www.dealerpricing.co.uk/api", "description": "Production (live and sandbox keys)" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Vehicle data", "description": "Identity, specification, valuation, provenance, tax and MOT." }, { "name": "Service history", "description": "Asynchronous digital service history from the manufacturer network." }, { "name": "Market data", "description": "Live and sold adverts for similar vehicles from UK dealer websites." }, { "name": "Analysis", "description": "Pricing analysis built on the market data." }, { "name": "Sandbox", "description": "The free test data set." }, { "name": "Reference", "description": "This description." }, { "name": "Webhooks", "description": "Events we send to your endpoints, signed with the DP-Signature header." } ], "paths": { "/v1/vehicle/decode": { "post": { "operationId": "vehicleDecode", "tags": [ "Vehicle data" ], "summary": "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nResponse versions: this is the version 2 shape (the default for new accounts, and for everyone from 1 February 2027). Version 1 also sends insurance_group, acceleration_0_62_mph, import_export.import_date and tax.first_year_six_months_gbp (never filled), and sends registration_date and date_of_manufacture as timestamps (registration_date falls back to the first date abroad for an import). The version 1 shape is published as components.schemas.VehicleDecodeVersion1. Choose with the `DP-Error-Codes` header or the account setting, as for error codes.\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "vrm": { "type": "string", "description": "Registration." }, "make": { "type": "string" }, "model": { "type": "string" }, "model_description": { "type": "string" }, "variant": { "type": "string" }, "series": { "type": "string" }, "year": { "type": "integer", "description": "Year of manufacture." }, "registration_date": { "type": "string", "format": "date", "description": "Date first registered in the UK. Left out for an import with no UK date: registration.first_registered holds the first date abroad." }, "date_of_manufacture": { "type": "string", "format": "date" }, "colour": { "type": "string" }, "fuel_type": { "type": "string" }, "powertrain_type": { "type": "string" }, "transmission": { "type": "string" }, "gears": { "type": "integer" }, "drive_type": { "type": "string" }, "body_type": { "type": "string" }, "wheelplan": { "type": "string" }, "engine_capacity_cc": { "type": "integer" }, "engine_capacity_litres": { "type": "number" }, "engine_number": { "type": "string" }, "vin": { "type": "string" }, "doors": { "type": "integer" }, "seats": { "type": "integer" }, "co2_emissions": { "type": "number", "description": "g/km: the manufacturer figure. The figure on the UK vehicle register is tax.co2_g_per_km and can differ." }, "euro_status": { "type": "string" }, "power_bhp": { "type": "number" }, "power_kw": { "type": "number" }, "torque_nm": { "type": "number" }, "top_speed_mph": { "type": "number" }, "acceleration_0_60_mph": { "type": "number", "description": "Seconds." }, "fuel_consumption_combined": { "type": "number", "description": "mpg." }, "fuel_consumption_urban": { "type": "number", "description": "mpg." }, "fuel_consumption_extra_urban": { "type": "number", "description": "mpg." }, "gross_weight_kg": { "type": "number" }, "kerb_weight_kg": { "type": "number" }, "mass_in_service_kg": { "type": "number" }, "previous_keepers": { "type": "integer", "description": "Previous keepers: the highest count in the keeper history, and 0 when the record holds a keeper history with no changes. Left out when the record holds no keeper history." }, "colour_changes": { "type": "integer" }, "registration": { "type": "object", "properties": { "first_registered": { "type": "string", "format": "date", "description": "First registered anywhere (for an import, the first date abroad)." }, "first_registered_uk": { "type": "string", "format": "date" }, "used_before_first_registration": { "type": "boolean" }, "cherished_transfer_marker": { "type": "boolean" } }, "additionalProperties": false }, "keeper_history": { "type": "array", "items": { "type": "object", "properties": { "previous_keepers": { "type": "integer", "description": "The number of previous keepers at this change." }, "keeper_start_date": { "type": "string", "format": "date" }, "previous_keeper_disposal_date": { "type": "string", "format": "date" } }, "additionalProperties": false }, "description": "One row per keeper change, latest first. An empty list is a real answer." }, "v5c_issue_dates": { "type": "array", "items": { "type": "string", "format": "date" }, "description": "The date each registration document (V5C) was issued." }, "plate_changes": { "type": "array", "items": { "type": "object", "properties": { "previous_vrm": { "type": "string" }, "current_vrm": { "type": "string" }, "date_of_transaction": { "type": "string", "format": "date" }, "date_of_receipt": { "type": "string", "format": "date" }, "transfer_type": { "type": "string" } }, "additionalProperties": false }, "description": "An empty list is a real answer: the record holds no plate changes." }, "colour_history": { "type": "object", "properties": { "current": { "type": "string" }, "original": { "type": "string" }, "previous": { "type": "string" }, "changes": { "type": "integer" }, "last_change_date": { "type": "string", "format": "date" } }, "additionalProperties": false }, "import_export": { "type": "object", "properties": { "is_imported": { "type": "boolean" }, "imported_from_ni": { "type": "boolean" }, "imported_from_outside_eu": { "type": "boolean" }, "is_exported": { "type": "boolean" }, "export_date": { "type": "string", "format": "date" } }, "additionalProperties": false }, "scrapped": { "type": "object", "properties": { "is_scrapped": { "type": "boolean" }, "is_unscrapped": { "type": "boolean" }, "scrap_date": { "type": "string", "format": "date" }, "certificate_of_destruction": { "type": "boolean" } }, "additionalProperties": false }, "tax": { "type": "object", "properties": { "co2_g_per_km": { "type": "number", "description": "The figure on the UK vehicle register." }, "co2_band": { "type": "string" }, "tax_band": { "type": "string" }, "first_year_twelve_months_gbp": { "type": "number", "description": "The first-year rate for the vehicle's band. Filled for vehicles long past their first year too: it is the band's rate, not proof the vehicle paid it." }, "standard_six_months_gbp": { "type": "number" }, "standard_twelve_months_gbp": { "type": "number" }, "premium_vehicle_six_months_gbp": { "type": "number", "description": "The rate a vehicle in this band pays IF it cost over £40,000 new. Filled for every vehicle registered from April 2017: it is not proof the vehicle pays it." }, "premium_vehicle_twelve_months_gbp": { "type": "number", "description": "As premium_vehicle_six_months_gbp." } }, "additionalProperties": false, "description": "Vehicle excise duty as registered. Rates are in pounds." }, "dvla": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "body_type": { "type": "string" }, "fuel_type": { "type": "string" }, "wheelplan": { "type": "string" }, "engine_capacity_cc": { "type": "integer" }, "power_kw": { "type": "number" }, "seats": { "type": "integer" }, "gross_weight_kg": { "type": "number" }, "mass_in_service_kg": { "type": "number" }, "power_to_weight_ratio": { "type": "number" }, "max_braked_trailer_mass_kg": { "type": "number" }, "max_unbraked_trailer_mass_kg": { "type": "number" } }, "additionalProperties": false, "description": "The values exactly as held on the UK vehicle register. The top-level fields prefer manufacturer model data when it is held, so make, model, body_type, power_kw and seats can be written differently here." }, "power_ps": { "type": "number", "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "torque_lb_ft": { "type": "number" }, "top_speed_kph": { "type": "number" }, "acceleration_0_100_kph": { "type": "number", "description": "Seconds (0 to 100 km/h, the same test as 0 to 62 mph)." }, "fuel_consumption_combined_l_100km": { "type": "number" }, "fuel_consumption_urban_l_100km": { "type": "number" }, "fuel_consumption_extra_urban_l_100km": { "type": "number" }, "country_of_origin": { "type": "string" }, "model_introduction_date": { "type": "string", "format": "date", "description": "When this model was introduced." }, "model_start_date": { "type": "string", "format": "date", "description": "First build date of this model version." }, "model_end_date": { "type": "string", "format": "date", "description": "Last build date of this model version (left out while it is still built)." }, "classification": { "type": "object", "properties": { "type_approval_category": { "type": "string", "description": "For example M1 (car) or N1 (light goods vehicle)." }, "vehicle_class": { "type": "string" }, "taxation_class": { "type": "string" }, "market_sector_code": { "type": "string" } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "engine": { "type": "object", "properties": { "code": { "type": "string", "description": "The manufacturer engine code." }, "manufacturer": { "type": "string" }, "cylinders": { "type": "integer" }, "cylinder_arrangement": { "type": "string" }, "aspiration": { "type": "string" }, "valves_per_cylinder": { "type": "integer" }, "valve_gear": { "type": "string" }, "bore_mm": { "type": "number" }, "stroke_mm": { "type": "number" }, "fuel_delivery": { "type": "string" }, "location": { "type": "string" } }, "additionalProperties": false, "description": "Combustion engine details. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "dimensions": { "type": "object", "properties": { "length_mm": { "type": "number" }, "width_mm": { "type": "number" }, "height_mm": { "type": "number" }, "wheelbase_mm": { "type": "number" }, "load_length_mm": { "type": "number", "description": "Vans." } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "weights": { "type": "object", "properties": { "gross_combined_weight_kg": { "type": "number" }, "gross_train_weight_kg": { "type": "number" }, "payload_kg": { "type": "number" }, "unladen_weight_kg": { "type": "number" } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "body": { "type": "object", "properties": { "body_shape": { "type": "string" }, "cab_type": { "type": "string", "description": "Vans and pick-ups." }, "wheelbase_type": { "type": "string" }, "axles": { "type": "integer" }, "fuel_tank_capacity_litres": { "type": "number" }, "load_volume_litres": { "type": "number", "description": "Load space of a van." }, "platform_name": { "type": "string" }, "platform_shared_across_models": { "type": "boolean" } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "safety": { "type": "object", "properties": { "ncap_star_rating": { "type": "number" }, "ncap_adult_percent": { "type": "number" }, "ncap_child_percent": { "type": "number" }, "ncap_pedestrian_percent": { "type": "number" }, "ncap_safety_assist_percent": { "type": "number" } }, "additionalProperties": false, "description": "Euro NCAP ratings. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "warranty": { "type": "object", "properties": { "manufacturer_warranty_months": { "type": "integer" }, "manufacturer_warranty_miles": { "type": "integer" } }, "additionalProperties": false, "description": "The manufacturer's new-vehicle warranty. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "supports_over_the_air_updates": { "type": "boolean" }, "drag_coefficient": { "type": "number" }, "ev": { "type": "object", "properties": { "powertrain_type": { "type": "string", "description": "For example BEV or PHEV." }, "batteries": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "total_capacity_kwh": { "type": "number" }, "usable_capacity_kwh": { "type": "number" }, "chemistry": { "type": "string" }, "voltage": { "type": "number" }, "location": { "type": "string" }, "warranty_months": { "type": "integer" }, "warranty_miles": { "type": "integer" } }, "additionalProperties": false } }, "range_tests": { "type": "array", "items": { "type": "object", "properties": { "test_type": { "type": "string", "description": "For example WLTP." }, "combined_range_miles": { "type": "number" }, "combined_range_km": { "type": "number" }, "city_range_miles": { "type": "number" }, "city_range_km": { "type": "number" } }, "additionalProperties": false } }, "real_range_miles": { "type": "number", "description": "Expected real-world range." }, "real_range_km": { "type": "number" }, "zero_emission_miles": { "type": "number", "description": "Electric-only range (plug-in hybrids)." }, "miles_per_charge_hour": { "type": "number" }, "wh_per_mile": { "type": "number" }, "max_charge_input_kw": { "type": "number" }, "number_of_charge_ports": { "type": "integer" }, "charge_ports": { "type": "array", "items": { "type": "object", "properties": { "port_type": { "type": "string" }, "location": { "type": "string" }, "max_charge_kw": { "type": "number" }, "is_standard": { "type": "boolean" }, "charge_times_10_to_80_percent": { "type": "array", "items": { "type": "object", "properties": { "charger_kw": { "type": "number" }, "minutes": { "type": "number" } }, "additionalProperties": false }, "description": "Average time to charge from 10% to 80% on a charger of this power." } }, "additionalProperties": false } }, "motors": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "location": { "type": "string" }, "axle_driven": { "type": "string" }, "power_kw": { "type": "number" }, "max_torque_nm": { "type": "number" }, "max_power_rpm": { "type": "number" }, "manufacturer": { "type": "string" }, "model": { "type": "string" }, "regenerative_braking": { "type": "boolean" } }, "additionalProperties": false } }, "tesla_supercharger_compatible": { "type": "boolean" } }, "additionalProperties": false, "description": "Electric and plug-in hybrid vehicles only. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "raw": { "type": "object", "additionalProperties": true, "description": "The source record as received, with supplier bookkeeping removed. Its layout can change without notice: rely on the documented fields instead." } }, "required": [ "vrm" ], "additionalProperties": false, "description": "The vehicle. Fields and groups not held for this vehicle are omitted." } }, "required": [ "vehicle" ], "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "vehicle": { "vrm": "SA22TLZ", "make": "Volkswagen", "model": "Polo", "model_description": "Polo Life TSi", "variant": "Life TSI", "series": "AW/BZ", "year": 2022, "registration_date": "2022-04-23", "date_of_manufacture": "2022-04-23", "colour": "BLUE", "fuel_type": "PETROL", "powertrain_type": "ICE", "transmission": "Manual", "gears": 5, "drive_type": "4x2", "body_type": "Hatchback", "wheelplan": "2 AXLE RIGID BODY", "engine_capacity_cc": 999, "engine_capacity_litres": 1, "engine_number": "DLAC899781", "vin": "WVWZZZAWZNU040975", "doors": 5, "seats": 5, "co2_emissions": 106, "euro_status": "6d", "power_bhp": 93.7, "power_kw": 70, "torque_nm": 175, "top_speed_mph": 116, "fuel_consumption_combined": 54.3, "gross_weight_kg": 1620, "kerb_weight_kg": 1097, "mass_in_service_kg": 1219, "previous_keepers": 0, "colour_changes": 0, "registration": { "first_registered": "2022-04-23", "first_registered_uk": "2022-04-23", "used_before_first_registration": false, "cherished_transfer_marker": false }, "keeper_history": [], "v5c_issue_dates": [ "2022-04-23" ], "plate_changes": [], "colour_history": { "current": "BLUE", "original": "BLUE", "changes": 0 }, "import_export": { "is_imported": false, "imported_from_ni": false, "imported_from_outside_eu": false, "is_exported": false }, "scrapped": { "is_scrapped": false, "is_unscrapped": false, "certificate_of_destruction": false }, "tax": { "co2_g_per_km": 118, "first_year_twelve_months_gbp": 455, "standard_six_months_gbp": 110, "standard_twelve_months_gbp": 200, "premium_vehicle_six_months_gbp": 352, "premium_vehicle_twelve_months_gbp": 640 }, "dvla": { "make": "VOLKSWAGEN", "model": "POLO LIFE TSI", "body_type": "5 DOOR HATCHBACK", "fuel_type": "PETROL", "wheelplan": "2 AXLE RIGID BODY", "engine_capacity_cc": 999, "power_kw": 70, "seats": 5, "gross_weight_kg": 1620, "mass_in_service_kg": 1219, "power_to_weight_ratio": 0, "max_braked_trailer_mass_kg": 1000, "max_unbraked_trailer_mass_kg": 580 }, "power_ps": 95, "torque_lb_ft": 129.2, "top_speed_kph": 187, "acceleration_0_100_kph": 10.8, "fuel_consumption_combined_l_100km": 5.2, "country_of_origin": "South Africa", "model_introduction_date": "2021-07-05", "model_start_date": "2021-10-13", "classification": { "type_approval_category": "M1", "vehicle_class": "Car", "taxation_class": "Car", "market_sector_code": "AA" }, "engine": { "code": "1.0 95PS EU6", "manufacturer": "Volkswagen Cars", "cylinders": 3, "cylinder_arrangement": "Inline", "aspiration": "Turbocharged", "valves_per_cylinder": 4, "valve_gear": "DOHC", "bore_mm": 74, "stroke_mm": 76, "location": "Front" }, "dimensions": { "length_mm": 4074, "width_mm": 1751, "height_mm": 1451, "wheelbase_mm": 2552 }, "weights": { "gross_combined_weight_kg": 1620, "gross_train_weight_kg": 2620 }, "body": { "wheelbase_type": "Short Wheelbase", "axles": 2, "fuel_tank_capacity_litres": 40, "platform_name": "MQB A0", "platform_shared_across_models": true }, "safety": { "ncap_star_rating": 5, "ncap_adult_percent": 96, "ncap_child_percent": 85, "ncap_pedestrian_percent": 76, "ncap_safety_assist_percent": 59 }, "warranty": { "manufacturer_warranty_months": 36, "manufacturer_warranty_miles": 60000 }, "raw": {} } }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 16, "balance_pence": 984, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "vin": { "type": "string", "example": "WAUZZZFY8N2062771", "description": "Vehicle identification number. 5 to 17 letters and digits, no I, O or Q." } }, "anyOf": [ { "required": [ "vrm" ] }, { "required": [ "vin" ] } ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used." }, "examples": { "registration": { "summary": "By registration", "value": { "vrm": "SA22TLZ" } }, "vin": { "summary": "By VIN", "value": { "vin": "WAUZZZFY8N2062771" } } } } } }, "x-price-pence": { "packages": { "payg": 16, "starter": 10, "pro": 8, "enterprise": 6 } } } }, "/v1/vehicle/spec": { "post": { "operationId": "vehicleSpec", "tags": [ "Vehicle data" ], "summary": "Specification", "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nResponse versions: this is the version 2 shape (the default for new accounts, and for everyone from 1 February 2027). Version 1 also sends the engine, performance, transmission, dimensions, economy, practicality, safety and insurance groups and vehicle.variant, series, body_type and powertrain_type. They are empty on live answers (the specification source does not send them) but filled in version 1 sandbox answers. vehicle.year is text in version 1. The version 1 shape is published as components.schemas.VehicleSpecVersion1. Choose with the `DP-Error-Codes` header or the account setting, as for error codes.\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "specification": { "type": "object", "properties": { "vrm": { "type": "string", "description": "Registration (or the VIN when the request was made by VIN)." }, "vehicle": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string", "description": "The full model description, the same as model_description." }, "model_description": { "type": "string" }, "year": { "type": "integer", "description": "Year of manufacture." } }, "additionalProperties": false }, "factory_equipment": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of items." }, "items": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "fitment": { "type": "string", "description": "Standard, Option or Free." }, "type": { "type": "string" }, "price": { "type": [ "string", "number" ], "description": "Pounds. On options only; can be negative (a credit option)." }, "contents": { "type": "array", "items": { "type": "string" }, "description": "What an option pack contains, one line per item." } }, "additionalProperties": false } } }, "required": [ "count", "items" ], "additionalProperties": false, "description": "Equipment fitted at the factory for this model." }, "raw": { "type": "object", "additionalProperties": true, "description": "The source record as received, with supplier bookkeeping removed. Its layout can change without notice: rely on the documented fields instead." } }, "required": [ "vrm" ], "additionalProperties": false, "description": "The specification: the vehicle and its factory equipment. Engine, performance, dimensions, economy, safety and the rest of the model data are on /v1/vehicle/decode." } }, "required": [ "specification" ], "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "specification": { "vrm": "SA22TLZ", "vehicle": { "make": "Volkswagen", "model": "Polo Life TSi", "model_description": "Polo Life TSi", "year": 2022 }, "factory_equipment": { "count": 64, "items": [ { "category": "Audio and Communications", "name": "Satellite Navigation", "description": "Discover Navigation Pro", "fitment": "Option", "type": "Item", "price": 1415 }, { "category": "Audio and Communications", "name": "Satellite Navigation", "description": "Discovr Navigation System", "fitment": "Option", "type": "Item", "price": 570 }, { "category": "Exterior Features", "name": "Front Foglights", "description": "Front Fog Light + Cornering Function", "fitment": "Option", "type": "Package", "price": 210, "contents": [ "Front Fog Light + Cornering Function" ] } ] }, "raw": {} } }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 22, "balance_pence": 978, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "vin": { "type": "string", "example": "WAUZZZFY8N2062771", "description": "Vehicle identification number. 5 to 17 letters and digits, no I, O or Q." } }, "anyOf": [ { "required": [ "vrm" ] }, { "required": [ "vin" ] } ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used." }, "examples": { "registration": { "summary": "By registration", "value": { "vrm": "SA22TLZ" } } } } } }, "x-price-pence": { "packages": { "payg": 22, "starter": 20, "pro": 18, "enterprise": 15 } } } }, "/v1/vehicle/valuation": { "post": { "operationId": "vehicleValuation", "tags": [ "Vehicle data" ], "summary": "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nResponse versions: this is the version 2 shape (the default for new accounts, and for everyone from 1 February 2027). Version 1 also sends condition_adjustments, mileage_adjustment and vehicle_summary make, model, variant, year, fuel_type and transmission (never filled), and sends valuation_date and vehicle_summary.first_registered as timestamps. The version 1 shape is published as components.schemas.VehicleValuationVersion1. Choose with the `DP-Error-Codes` header or the account setting, as for error codes.\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "valuation": { "type": "object", "properties": { "vrm": { "type": "string", "description": "Registration (or the VIN when the request was made by VIN)." }, "mileage_used": { "type": "integer", "description": "The mileage the figures were produced at, as the source reports it (your mileage only when it reports none)." }, "currency": { "type": "string", "const": "GBP" }, "valuations": { "type": "object", "properties": { "retail": { "type": "number" }, "trade": { "type": "number" }, "private": { "type": "number" }, "part_exchange": { "type": "number" }, "auction": { "type": "number" } }, "additionalProperties": false, "description": "Headline figures in pounds." }, "figures": { "type": "object", "properties": { "on_the_road": { "type": "number", "description": "The price when new, not today's value." }, "dealer_forecourt": { "type": "number" }, "trade_retail": { "type": "number" }, "trade_average": { "type": "number" }, "trade_poor": { "type": "number" }, "private_clean": { "type": "number" }, "private_average": { "type": "number" }, "part_exchange": { "type": "number" }, "auction": { "type": "number" } }, "additionalProperties": false, "description": "Every figure held, in pounds." }, "valuation_date": { "type": "string", "format": "date", "description": "The UK day the valuation was produced." }, "valued_at": { "type": "string", "format": "date-time", "description": "The exact time the valuation was produced." }, "valuation_book": { "type": "string", "description": "The source's own label for the valuation set it used (for example \"Direct\"). For reference only." }, "vehicle_summary": { "type": "object", "properties": { "description": { "type": "string" }, "first_registered": { "type": "string", "format": "date" } }, "additionalProperties": false }, "raw": { "type": "object", "additionalProperties": true, "description": "The source record as received, with supplier bookkeeping removed. Its layout can change without notice: rely on the documented fields instead." } }, "required": [ "vrm", "currency" ], "additionalProperties": false, "description": "The valuation. Fields not held are omitted." } }, "required": [ "valuation" ], "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "valuation": { "vrm": "SA22TLZ", "mileage_used": 14424, "currency": "GBP", "valuations": { "retail": 15186, "trade": 12680, "private": 13360, "part_exchange": 13303, "auction": 13286 }, "figures": { "on_the_road": 19225, "dealer_forecourt": 15186, "trade_retail": 14596, "trade_average": 12680, "trade_poor": 11769, "private_clean": 13512, "private_average": 13360, "part_exchange": 13303, "auction": 13286 }, "valuation_date": "2026-09-06", "valued_at": "2026-09-06T21:11:19.4516511Z", "valuation_book": "Direct", "vehicle_summary": { "description": "Volkswagen Polo Life TSi Life TSI [Petrol / Manual]", "first_registered": "2022-04-23" }, "raw": {} } }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 25, "balance_pence": 975, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "vin": { "type": "string", "example": "WAUZZZFY8N2062771", "description": "Vehicle identification number. 5 to 17 letters and digits, no I, O or Q." }, "mileage": { "type": "integer", "minimum": 1, "example": 30000, "description": "Current mileage in miles. Optional." } }, "anyOf": [ { "required": [ "vrm" ] }, { "required": [ "vin" ] } ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used." }, "examples": { "registration": { "summary": "By registration", "value": { "vrm": "SA22TLZ" } } } } } }, "x-price-pence": { "packages": { "payg": 25, "starter": 21, "pro": 19, "enterprise": 16 } } } }, "/v1/vehicle/provenance": { "post": { "operationId": "vehicleProvenance", "tags": [ "Vehicle data" ], "summary": "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nResponse versions: this is the version 2 shape (the default for new accounts, and for everyone from 1 February 2027). Version 1 also sends the vehicle record groups (vehicle make, model, variant, year and colour, registration, ownership, plate_changes, colour, import_export, scrapped) and mileage, all always null on this check; the flat police fields stolen.police_recorded, stolen_date, police_force, record_status and record_added_date; and dates as the source writes them (timestamps), with the day corrected where the source wrote a UK midnight as 23:00 the day before. The version 1 shape is published as components.schemas.VehicleProvenanceVersion1. Choose with the `DP-Error-Codes` header or the account setting, as for error codes.\n\nNull fields are kept on this endpoint (null = not held for this check).", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "provenance": { "type": "object", "properties": { "vrm": { "type": [ "string", "null" ] }, "check_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When this check ran." }, "vehicle": { "type": [ "object", "null" ], "properties": { "vin": { "type": [ "string", "null" ] } }, "required": [ "vin" ], "additionalProperties": false }, "finance": { "type": [ "object", "null" ], "properties": { "has_outstanding_finance": { "type": [ "boolean", "null" ], "description": "true: finance recorded. false: the finance register was checked and holds none. null: not held for this check." }, "finance_records": { "type": [ "integer", "null" ] }, "finance_details": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "agreement_date": { "type": "string", "format": "date" }, "agreement_type": { "type": "string" }, "agreement_number": { "type": "string" }, "agreement_term_months": { "type": [ "string", "number" ] }, "finance_company": { "type": "string" }, "contact_number": { "type": "string", "description": "The finance company's phone number." }, "vehicle_description": { "type": "string" }, "is_stock_funding": { "type": "boolean", "description": "true for a UNIT STOCKING agreement: a dealer's stock funding, not a keeper's finance agreement." } }, "additionalProperties": false } } }, "required": [ "has_outstanding_finance", "finance_records", "finance_details" ], "additionalProperties": false }, "stolen": { "type": [ "object", "null" ], "properties": { "is_stolen": { "type": [ "boolean", "null" ], "description": "true when at least one source holds a stolen marker (the police record or an insurer theft record); false only when both were checked and are clear. Read police_marked_stolen and insurer_theft_recorded to see which: an insurer theft record can be for a vehicle that was later recovered." }, "police_marked_stolen": { "type": [ "boolean", "null" ], "description": "The police record on its own: true when it marks the vehicle as stolen. null when it could not be checked." }, "insurer_theft_recorded": { "type": [ "boolean", "null" ], "description": "The insurer register on its own: true when it holds a theft record. null when it could not be checked." }, "police": { "type": [ "object", "null" ], "properties": { "marked_stolen": { "type": [ "boolean", "null" ], "description": "true: the police record marks the vehicle as stolen." }, "date_reported_stolen": { "type": [ "string", "null" ], "format": "date" }, "police_force": { "type": [ "string", "null" ] }, "record_status": { "type": [ "string", "null" ], "description": "The current status on the police record." }, "record_added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the police record was created." }, "vrm": { "type": [ "string", "null" ], "description": "The registration on the police record." }, "vin": { "type": [ "string", "null" ], "description": "The VIN on the police record." } }, "required": [ "marked_stolen", "date_reported_stolen", "police_force", "record_status", "record_added_at", "vrm", "vin" ], "additionalProperties": false, "description": "The police record in full. null when the police record could not be checked." }, "insurer_theft_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Write-off category (A, B, S, N, or the older C and D) or the theft category." }, "status": { "type": "string", "description": "The register's description, for example \"CAT S STRUCTURAL DAMAGE\"." }, "loss_date": { "type": "string", "format": "date", "description": "Date of the loss." }, "entry_date": { "type": "string", "format": "date", "description": "When the record was added to the insurers' register." }, "insurer": { "type": "string" }, "insurer_branch": { "type": "string" }, "insurer_code": { "type": "string" }, "claim_number": { "type": "string" }, "contact_number": { "type": "string", "description": "The insurer's phone number." }, "theft_indicator": { "type": [ "string", "number" ], "description": "The register's own theft marker code, as received. Use theft_indicator_literal to read it." }, "theft_indicator_literal": { "type": "string", "description": "\"STOLEN\" or \"NOT STOLEN\"." }, "loss_type": { "type": "string", "description": "The register's loss type code, as received (\"0\" on every record seen so far)." }, "removed_date": { "type": "string", "format": "date", "description": "When the record was taken off the register, if it was." } }, "additionalProperties": false, "description": "One insurer register record with every field the register gives. Fields the register leaves empty are omitted." }, "description": "Every insurer register theft record, with all its fields." } }, "required": [ "is_stolen", "police_marked_stolen", "insurer_theft_recorded", "police", "insurer_theft_records" ], "additionalProperties": false }, "write_off": { "type": [ "object", "null" ], "properties": { "is_write_off": { "type": [ "boolean", "null" ] }, "category": { "type": [ "string", "null" ], "description": "The category of the most recent write-off record (latest loss date, else latest entry date). Every record is in write_off_records; every category held is in categories." }, "date": { "type": [ "string", "null" ], "format": "date", "description": "Loss date of the most recent record (its entry date when it has no loss date)." }, "categories": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Every write-off category held, each once, from the newest record." }, "write_off_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Write-off category (A, B, S, N, or the older C and D) or the theft category." }, "status": { "type": "string", "description": "The register's description, for example \"CAT S STRUCTURAL DAMAGE\"." }, "loss_date": { "type": "string", "format": "date", "description": "Date of the loss." }, "entry_date": { "type": "string", "format": "date", "description": "When the record was added to the insurers' register." }, "insurer": { "type": "string" }, "insurer_branch": { "type": "string" }, "insurer_code": { "type": "string" }, "claim_number": { "type": "string" }, "contact_number": { "type": "string", "description": "The insurer's phone number." }, "theft_indicator": { "type": [ "string", "number" ], "description": "The register's own theft marker code, as received. Use theft_indicator_literal to read it." }, "theft_indicator_literal": { "type": "string", "description": "\"STOLEN\" or \"NOT STOLEN\"." }, "loss_type": { "type": "string", "description": "The register's loss type code, as received (\"0\" on every record seen so far)." }, "removed_date": { "type": "string", "format": "date", "description": "When the record was taken off the register, if it was." } }, "additionalProperties": false, "description": "One insurer register record with every field the register gives. Fields the register leaves empty are omitted." }, "description": "Every write-off record, newest first, with all its fields." } }, "required": [ "is_write_off", "category", "date", "categories", "write_off_records" ], "additionalProperties": false }, "alerts": { "type": [ "object", "null" ], "properties": { "has_alerts": { "type": [ "boolean", "null" ], "description": "true when any alert below is known; false only when finance, stolen and write-off were all checked and are clear; otherwise null." }, "alert_count": { "type": [ "integer", "null" ] }, "alert_list": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Plain-language alerts. Stolen alerts name their source: \"Police record: marked as stolen\", \"Insurer register: theft record\". Match on the fields above, not on this text." } }, "required": [ "has_alerts", "alert_count", "alert_list" ], "additionalProperties": false }, "raw": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The police, insurer, finance and vehicle code records as received, with supplier bookkeeping removed. Nulls inside are removed. Layout can change without notice." } }, "required": [ "vrm", "check_date", "vehicle", "finance", "stolen", "write_off", "alerts", "raw" ], "additionalProperties": false, "description": "Provenance keeps every field: null means \"not held for this check\", never \"no\". false or 0 is a real answer. Rows inside lists omit null fields as elsewhere. Keepers, plate changes, colour, import and export and scrapping are on /v1/vehicle/decode; mileage and MOT on /v1/vehicle/tax-mot." } }, "required": [ "provenance" ], "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "vin": { "type": "string", "example": "WAUZZZFY8N2062771", "description": "Vehicle identification number. 5 to 17 letters and digits, no I, O or Q." } }, "anyOf": [ { "required": [ "vrm" ] }, { "required": [ "vin" ] } ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored) or `vin` (5 to 17 letters and digits, no I, O or Q). When both are sent, the VIN is used." }, "examples": { "registration": { "summary": "Write-off and finance (sandbox)", "value": { "vrm": "RO21PAD" } } } } } }, "x-price-pence": { "packages": { "payg": 299, "starter": 275, "pro": 250, "enterprise": 220 } } } }, "/v1/vehicle/tax-mot": { "post": { "operationId": "vehicleTaxMot", "tags": [ "Vehicle data" ], "summary": "Tax and 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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "vrm": { "type": "string" }, "sources": { "type": "object", "properties": { "dvla": { "type": "string", "enum": [ "found", "not_found", "unavailable" ] }, "mot": { "type": "string", "enum": [ "found", "not_found", "unavailable" ] } }, "required": [ "dvla", "mot" ], "additionalProperties": false, "description": "What each government source answered: `dvla` is the vehicle register (tax status, MOT status, vehicle details), `mot` the MOT history service." }, "tax": { "type": "object", "properties": { "status": { "type": "string" }, "due_date": { "type": "string", "format": "date" } }, "additionalProperties": false, "description": "Omitted when the vehicle register holds no record." }, "mot": { "type": "object", "properties": { "status": { "type": "string" }, "expiry_date": { "type": "string", "format": "date" } }, "additionalProperties": false, "description": "Omitted when the vehicle register holds no record." }, "vehicle": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "colour": { "type": "string" }, "year_of_manufacture": { "type": "integer" }, "first_registration_date": { "type": "string", "description": "From the MOT history: the date of first registration, or when it does not hold one, the date of first use (these can differ for imports). See month_of_first_registration for the month on the vehicle register." }, "engine_capacity": { "type": "integer", "description": "cc." }, "co2_emissions": { "type": "number", "description": "g/km as on the vehicle register. 0 is sent for electric vehicles; for other fuels a 0 on the register means no figure is held, and the field is left out." }, "fuel_type": { "type": "string" }, "marked_for_export": { "type": "boolean" }, "type_approval": { "type": "string" }, "wheelplan": { "type": "string" }, "euro_status": { "type": "string" }, "date_of_last_v5c_issued": { "type": "string", "format": "date" }, "month_of_first_registration": { "type": "string", "description": "YYYY-MM, from the vehicle register." }, "month_of_first_uk_registration": { "type": "string", "description": "YYYY-MM: when the vehicle was first registered in the UK, sent only when it differs from the first registration (usually an import)." }, "revenue_weight": { "type": "integer", "description": "kg, from the vehicle register (mostly goods vehicles)." }, "real_driving_emissions": { "type": "string", "description": "Real driving emissions standard, from the vehicle register (diesel company car tax)." }, "art_end_date": { "type": "string", "format": "date", "description": "When the additional rate of vehicle tax (expensive car supplement) ends." }, "has_outstanding_recall": { "type": "string", "enum": [ "Yes", "No", "Unknown" ], "description": "Outstanding safety recall, exactly as the MOT history service says it. \"Unknown\" is common: it is not \"No\". Left out when the MOT history holds no record." }, "manufacture_date": { "type": "string", "format": "date", "description": "From the MOT history." }, "source": { "type": "string", "enum": [ "dvla", "dvsa" ], "description": "Where the vehicle block came from: `dvla` (the vehicle register) or `dvsa` (the MOT history record, used when the register holds no record, common for classic vehicles and plates on retention)." } }, "additionalProperties": false }, "mot_history": { "type": "object", "properties": { "total_tests": { "type": "integer" }, "first_test_due_date": { "type": "string", "format": "date", "description": "When the first MOT is due, for a vehicle too new to have had one." }, "tests": { "type": "array", "items": { "type": "object", "properties": { "test_date": { "type": "string", "description": "A full timestamp: when the test was completed." }, "expiry_date": { "type": "string", "description": "YYYY-MM-DD. Left out for a failed test." }, "result": { "type": "string", "description": "PASSED or FAILED." }, "odometer_value": { "type": [ "string", "number" ], "description": "The reading as text (for example \"55995\"). Left out when the odometer could not be read: see odometer_result_type." }, "odometer_unit": { "type": "string", "description": "\"MI\" or \"KM\"." }, "mot_test_number": { "type": "string", "description": "The MOT test certificate number: check a test on GOV.UK or remove duplicates with it." }, "odometer_result_type": { "type": "string", "description": "READ, UNREADABLE or NO_ODOMETER: why a reading may be missing." }, "defects": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" }, "dangerous": { "type": "boolean" } }, "additionalProperties": false } } }, "additionalProperties": false } } }, "additionalProperties": false, "description": "Omitted when the MOT history service holds no record. total_tests 0 can be normal (new or exempt vehicles)." } }, "required": [ "vrm", "sources" ], "additionalProperties": false, "description": "Tax status, MOT status and MOT history from the two free government sources." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "vrm": "SA22TLZ", "sources": { "dvla": "found", "mot": "found" }, "tax": { "status": "Taxed", "due_date": "2027-04-01" }, "mot": { "status": "Valid", "expiry_date": "2027-04-23" }, "vehicle": { "make": "VOLKSWAGEN", "model": "POLO LIFE TSI", "colour": "BLUE", "year_of_manufacture": 2022, "first_registration_date": "2022-04-23", "engine_capacity": 999, "co2_emissions": 118, "fuel_type": "PETROL", "marked_for_export": false, "type_approval": "M1", "wheelplan": "2 AXLE RIGID BODY", "euro_status": "EURO 6 AP", "date_of_last_v5c_issued": "2022-04-23", "month_of_first_registration": "2022-04", "revenue_weight": 1620, "has_outstanding_recall": "Unknown", "manufacture_date": "2022-04-23", "source": "dvla" }, "mot_history": { "total_tests": 3, "tests": [ { "test_date": "2026-04-24T09:16:59.000Z", "expiry_date": "2027-04-23", "result": "PASSED", "odometer_value": "10088", "odometer_unit": "MI", "mot_test_number": "976134633448", "odometer_result_type": "READ", "defects": [] }, { "test_date": "2025-04-08T08:11:26.000Z", "expiry_date": "2026-04-22", "result": "PASSED", "odometer_value": "7909", "odometer_unit": "MI", "mot_test_number": "211085358720", "odometer_result_type": "READ", "defects": [] }, { "test_date": "2025-04-08T08:11:25.000Z", "result": "FAILED", "odometer_value": "7909", "odometer_unit": "MI", "mot_test_number": "736735947582", "odometer_result_type": "READ", "defects": [ { "type": "PRS", "text": "Headlamp aim too high (4.1.2 (a))", "dangerous": false } ] } ] } }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 5, "balance_pence": 995, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." } }, "required": [ "vrm" ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs." }, "examples": { "registration": { "summary": "By registration", "value": { "vrm": "SA22TLZ" } } } } } }, "x-price-pence": { "packages": { "payg": 5, "starter": 4, "pro": 3, "enterprise": 2 } } } }, "/v1/vehicle/service-history": { "post": { "operationId": "serviceHistoryRequest", "tags": [ "Service history" ], "summary": "Service history: start a request", "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.\n\nSend `vrm`, or `vin` (the full 17 characters, no I, O or Q), or both. With both, the registration is searched and the VIN is stored on the request and returned in every answer.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Id of this service history request (UUID). Use it with the status endpoint." }, "vrm": { "type": "string", "description": "Omitted for a request made by VIN only." }, "vin": { "type": "string", "description": "Sent only when the request carried a VIN." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "message": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "check_after_seconds": { "type": "integer", "description": "While open: wait at least this long before polling again." }, "status_url": { "type": "string", "format": "uri", "description": "Absolute URL of the status endpoint for this request." }, "callback_url": { "type": "string", "format": "uri" }, "cost_pence": { "type": "integer", "description": "What was charged when the request was accepted." }, "refunded_pence": { "type": "integer", "description": "What was given back (a search with no records, or a fault)." }, "error": { "type": "string", "description": "Failed requests: a fixed message for the error_code. Match on error_code, not on this text." }, "outcome": { "type": "string", "enum": [ "records", "no_records", "failed" ], "description": "Finished requests: records found, no records (refunded in full, not an error) or failed (refunded). refunded_pence shows the refund." }, "error_code": { "type": "string", "enum": [ "SOURCE_UNAVAILABLE", "INTERNAL_ERROR" ], "description": "Failed requests: the version 2 error code for why." }, "service_history": { "type": "object", "properties": { "record_count": { "type": "integer" }, "services": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Record date when it could be read." }, "date_raw": { "type": "string", "description": "The date as the manufacturer wrote it." }, "type": { "type": "string", "description": "Almost always \"Service / Repair\": the work done is described in notes." }, "mileage": { "type": "integer", "description": "Mileage as a number, in the unit given by mileage_unit (check it before comparing with MOT miles). Version 2: omitted when the record shows 0 and is not the delivery record (the mileage was not recorded)." }, "mileage_raw": { "type": "string", "description": "The mileage as the record shows it, for example \"7,265 mi\", \"18,424 km\" or \"0\"." }, "mileage_unit": { "type": "string", "enum": [ "mi", "km", "unknown" ], "description": "The unit of mileage, read from mileage_raw: \"mi\", \"km\", or \"unknown\" when the record shows no unit. About a third of records show no unit. Mercedes-Benz: the mileage and unit of each visit are taken from the manufacturer report; a visit that cannot be matched to it has no mileage (unknown) rather than a figure that may be wrong." }, "workshop": { "type": "string", "description": "Where the work was done: for Mercedes-Benz (and smart) the servicing workshop name and address as printed in the manufacturer report, for example \"Example Motors Limited, 1 Sample Street, Exampleton\". For other makes usually not supplied: version 1 then sends the placeholder text \"OEM data\" (or an empty string); version 2 omits the field." }, "notes": { "type": "string", "description": "The work done, as the manufacturer recorded it. Sometimes in another language." } }, "additionalProperties": false } }, "message": { "type": "string", "description": "Why there are no records, when there are none." }, "retrieved_at": { "type": "string", "format": "date-time" }, "sample": { "type": "boolean", "description": "Sandbox only: true when these are made-up sample records, not the records of a real vehicle. Never sent by live keys." }, "sample_notice": { "type": "string", "description": "Sandbox only: sent with sample: true, says the records are sample data." } }, "required": [ "record_count", "services" ], "additionalProperties": false, "description": "Present once completed." }, "pdf_url": { "type": "string", "format": "uri", "description": "Completed requests with a stored manufacturer PDF: a signed link to it, valid for pdf_url_expires_in_seconds. Each status call returns a new link, free." }, "pdf_url_expires_in_seconds": { "type": "integer" }, "readable_until": { "type": "string", "format": "date-time", "description": "Finished requests: after this time the status endpoint answers 410 REQUEST_EXPIRED." } }, "required": [ "request_id", "status", "message", "status_url", "requested_at" ], "additionalProperties": false, "description": "A service history request. On the status and start endpoints fields with no value are omitted; callbacks and service_history webhook events send the same fields with null instead." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "request_id": "6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11", "vrm": "SK22AOM", "status": "pending", "message": "Request accepted. The manufacturer is being asked for this vehicle's digital service records - most complete within a few minutes, some take hours. Poll status_url or wait for your callback.", "requested_at": "2026-11-05T09:00:00.000Z", "check_after_seconds": 30, "status_url": "https://www.dealerpricing.co.uk/api/v1/vehicle/service-history/6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11", "callback_url": "https://example.com/hooks/dealerpricing", "cost_pence": 200, "refunded_pence": 0 }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 200, "balance_pence": 800, "is_sandbox": false } } } } }, "202": { "description": "Accepted: not finished yet. Poll status_url or wait for the callback.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Id of this service history request (UUID). Use it with the status endpoint." }, "vrm": { "type": "string", "description": "Omitted for a request made by VIN only." }, "vin": { "type": "string", "description": "Sent only when the request carried a VIN." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "message": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "check_after_seconds": { "type": "integer", "description": "While open: wait at least this long before polling again." }, "status_url": { "type": "string", "format": "uri", "description": "Absolute URL of the status endpoint for this request." }, "callback_url": { "type": "string", "format": "uri" }, "cost_pence": { "type": "integer", "description": "What was charged when the request was accepted." }, "refunded_pence": { "type": "integer", "description": "What was given back (a search with no records, or a fault)." }, "error": { "type": "string", "description": "Failed requests: a fixed message for the error_code. Match on error_code, not on this text." }, "outcome": { "type": "string", "enum": [ "records", "no_records", "failed" ], "description": "Finished requests: records found, no records (refunded in full, not an error) or failed (refunded). refunded_pence shows the refund." }, "error_code": { "type": "string", "enum": [ "SOURCE_UNAVAILABLE", "INTERNAL_ERROR" ], "description": "Failed requests: the version 2 error code for why." }, "service_history": { "type": "object", "properties": { "record_count": { "type": "integer" }, "services": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Record date when it could be read." }, "date_raw": { "type": "string", "description": "The date as the manufacturer wrote it." }, "type": { "type": "string", "description": "Almost always \"Service / Repair\": the work done is described in notes." }, "mileage": { "type": "integer", "description": "Mileage as a number, in the unit given by mileage_unit (check it before comparing with MOT miles). Version 2: omitted when the record shows 0 and is not the delivery record (the mileage was not recorded)." }, "mileage_raw": { "type": "string", "description": "The mileage as the record shows it, for example \"7,265 mi\", \"18,424 km\" or \"0\"." }, "mileage_unit": { "type": "string", "enum": [ "mi", "km", "unknown" ], "description": "The unit of mileage, read from mileage_raw: \"mi\", \"km\", or \"unknown\" when the record shows no unit. About a third of records show no unit. Mercedes-Benz: the mileage and unit of each visit are taken from the manufacturer report; a visit that cannot be matched to it has no mileage (unknown) rather than a figure that may be wrong." }, "workshop": { "type": "string", "description": "Where the work was done: for Mercedes-Benz (and smart) the servicing workshop name and address as printed in the manufacturer report, for example \"Example Motors Limited, 1 Sample Street, Exampleton\". For other makes usually not supplied: version 1 then sends the placeholder text \"OEM data\" (or an empty string); version 2 omits the field." }, "notes": { "type": "string", "description": "The work done, as the manufacturer recorded it. Sometimes in another language." } }, "additionalProperties": false } }, "message": { "type": "string", "description": "Why there are no records, when there are none." }, "retrieved_at": { "type": "string", "format": "date-time" }, "sample": { "type": "boolean", "description": "Sandbox only: true when these are made-up sample records, not the records of a real vehicle. Never sent by live keys." }, "sample_notice": { "type": "string", "description": "Sandbox only: sent with sample: true, says the records are sample data." } }, "required": [ "record_count", "services" ], "additionalProperties": false, "description": "Present once completed." }, "pdf_url": { "type": "string", "format": "uri", "description": "Completed requests with a stored manufacturer PDF: a signed link to it, valid for pdf_url_expires_in_seconds. Each status call returns a new link, free." }, "pdf_url_expires_in_seconds": { "type": "integer" }, "readable_until": { "type": "string", "format": "date-time", "description": "Finished requests: after this time the status endpoint answers 410 REQUEST_EXPIRED." } }, "required": [ "request_id", "status", "message", "status_url", "requested_at" ], "additionalProperties": false, "description": "A service history request. On the status and start endpoints fields with no value are omitted; callbacks and service_history webhook events send the same fields with null instead." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "request_id": "6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11", "vrm": "SK22AOM", "status": "pending", "message": "Request accepted. The manufacturer is being asked for this vehicle's digital service records - most complete within a few minutes, some take hours. Poll status_url or wait for your callback.", "requested_at": "2026-11-05T09:00:00.000Z", "check_after_seconds": 30, "status_url": "https://www.dealerpricing.co.uk/api/v1/vehicle/service-history/6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11", "callback_url": "https://example.com/hooks/dealerpricing", "cost_pence": 200, "refunded_pence": 0 }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 200, "balance_pence": 800, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "vin": { "type": "string", "minLength": 17, "maxLength": 17, "example": "WAUZZZFY8N2062771", "description": "Full 17 character VIN, no I, O or Q." }, "callback_url": { "type": "string", "format": "uri", "example": "https://example.com/hooks/dealerpricing", "description": "Optional. An https URL we POST the finished request to (same JSON as the status endpoint, wrapped in event, request_id, sent_at, data). Retried after 1, 10 and 60 minutes. Treat a callback as a notification and confirm with the status endpoint before acting. 500 characters maximum." } }, "anyOf": [ { "required": [ "vrm" ] }, { "required": [ "vin" ] } ], "description": "Send `vrm`, or `vin` (the full 17 characters, no I, O or Q), or both. With both, the registration is searched and the VIN is stored on the request and returned in every answer." }, "examples": { "registration": { "summary": "By registration with a callback", "value": { "vrm": "SK22AOM", "callback_url": "https://example.com/hooks/dealerpricing" } }, "vin": { "summary": "By VIN", "value": { "vin": "WAUZZZFY8N2062771" } } } } } }, "x-price-pence": { "packages": { "payg": 200, "starter": 170, "pro": 140, "enterprise": 100 }, "from": "2026-12-01T00:00:00Z", "upcoming": { "payg": 400, "starter": 300, "pro": 200, "enterprise": 100 } } } }, "/v1/vehicle/service-history/{request_id}": { "get": { "operationId": "serviceHistoryStatus", "tags": [ "Service history" ], "summary": "Service history: request status", "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.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Id of this service history request (UUID). Use it with the status endpoint." }, "vrm": { "type": "string", "description": "Omitted for a request made by VIN only." }, "vin": { "type": "string", "description": "Sent only when the request carried a VIN." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "message": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "check_after_seconds": { "type": "integer", "description": "While open: wait at least this long before polling again." }, "status_url": { "type": "string", "format": "uri", "description": "Absolute URL of the status endpoint for this request." }, "callback_url": { "type": "string", "format": "uri" }, "cost_pence": { "type": "integer", "description": "What was charged when the request was accepted." }, "refunded_pence": { "type": "integer", "description": "What was given back (a search with no records, or a fault)." }, "error": { "type": "string", "description": "Failed requests: a fixed message for the error_code. Match on error_code, not on this text." }, "outcome": { "type": "string", "enum": [ "records", "no_records", "failed" ], "description": "Finished requests: records found, no records (refunded in full, not an error) or failed (refunded). refunded_pence shows the refund." }, "error_code": { "type": "string", "enum": [ "SOURCE_UNAVAILABLE", "INTERNAL_ERROR" ], "description": "Failed requests: the version 2 error code for why." }, "service_history": { "type": "object", "properties": { "record_count": { "type": "integer" }, "services": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Record date when it could be read." }, "date_raw": { "type": "string", "description": "The date as the manufacturer wrote it." }, "type": { "type": "string", "description": "Almost always \"Service / Repair\": the work done is described in notes." }, "mileage": { "type": "integer", "description": "Mileage as a number, in the unit given by mileage_unit (check it before comparing with MOT miles). Version 2: omitted when the record shows 0 and is not the delivery record (the mileage was not recorded)." }, "mileage_raw": { "type": "string", "description": "The mileage as the record shows it, for example \"7,265 mi\", \"18,424 km\" or \"0\"." }, "mileage_unit": { "type": "string", "enum": [ "mi", "km", "unknown" ], "description": "The unit of mileage, read from mileage_raw: \"mi\", \"km\", or \"unknown\" when the record shows no unit. About a third of records show no unit. Mercedes-Benz: the mileage and unit of each visit are taken from the manufacturer report; a visit that cannot be matched to it has no mileage (unknown) rather than a figure that may be wrong." }, "workshop": { "type": "string", "description": "Where the work was done: for Mercedes-Benz (and smart) the servicing workshop name and address as printed in the manufacturer report, for example \"Example Motors Limited, 1 Sample Street, Exampleton\". For other makes usually not supplied: version 1 then sends the placeholder text \"OEM data\" (or an empty string); version 2 omits the field." }, "notes": { "type": "string", "description": "The work done, as the manufacturer recorded it. Sometimes in another language." } }, "additionalProperties": false } }, "message": { "type": "string", "description": "Why there are no records, when there are none." }, "retrieved_at": { "type": "string", "format": "date-time" }, "sample": { "type": "boolean", "description": "Sandbox only: true when these are made-up sample records, not the records of a real vehicle. Never sent by live keys." }, "sample_notice": { "type": "string", "description": "Sandbox only: sent with sample: true, says the records are sample data." } }, "required": [ "record_count", "services" ], "additionalProperties": false, "description": "Present once completed." }, "pdf_url": { "type": "string", "format": "uri", "description": "Completed requests with a stored manufacturer PDF: a signed link to it, valid for pdf_url_expires_in_seconds. Each status call returns a new link, free." }, "pdf_url_expires_in_seconds": { "type": "integer" }, "readable_until": { "type": "string", "format": "date-time", "description": "Finished requests: after this time the status endpoint answers 410 REQUEST_EXPIRED." } }, "required": [ "request_id", "status", "message", "status_url", "requested_at" ], "additionalProperties": false, "description": "A service history request. On the status and start endpoints fields with no value are omitted; callbacks and service_history webhook events send the same fields with null instead." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "request_id": "6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11", "vrm": "SK22AOM", "status": "completed", "message": "Service history retrieved. Sample data for testing. These are not the records of this or any real vehicle.", "requested_at": "2026-11-05T09:00:00.000Z", "completed_at": "2026-11-05T09:00:20.000Z", "status_url": "https://www.dealerpricing.co.uk/api/v1/vehicle/service-history/6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11", "cost_pence": 0, "refunded_pence": 0, "outcome": "records", "service_history": { "record_count": 7, "services": [ { "date": "2022-04-21", "date_raw": "21/04/2022", "type": "Service / Repair", "mileage": 12, "mileage_raw": "12 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Pre-delivery inspection" }, { "date": "2023-03-14", "date_raw": "14/03/2023", "type": "Service / Repair", "mileage": 9214, "mileage_raw": "9,214 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Oil change service" }, { "date": "2024-02-02", "date_raw": "02/02/2024", "type": "Service / Repair", "mileage": 18905, "mileage_raw": "18,905 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Inspection with oil change" }, { "date": "2024-07-15", "date_raw": "15/07/2024", "type": "Service / Repair", "mileage": 33600, "mileage_raw": "33,600 km", "mileage_unit": "km", "workshop": "Example Garage Europe, Exampleville", "notes": "Puncture repair" }, { "date": "2024-09-11", "date_raw": "11/09/2024", "type": "Service / Repair", "mileage": 23410, "mileage_raw": "23,410 mi", "mileage_unit": "mi", "workshop": "Example Autos Service Centre, Exampleton", "notes": "Brake fluid change" }, { "date": "2025-03-28", "date_raw": "28/03/2025", "type": "Service / Repair", "mileage": 29876, "mileage_raw": "29,876 mi", "mileage_unit": "mi", "workshop": "Example Autos Service Centre, Exampleton", "notes": "Oil change service" }, { "date": "2026-03-06", "date_raw": "06/03/2026", "type": "Service / Repair", "mileage": 38120, "mileage_raw": "38,120 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Inspection with oil change and pollen filter" } ], "retrieved_at": "2026-11-05T09:00:20.000Z", "sample": true, "sample_notice": "Sample data for testing. These are not the records of this or any real vehicle." }, "pdf_url": "https://www.dealerpricing.co.uk/api/service-history/pdf/5a3b1e00-5a3b-4e00-8000-000000000001?t=1765000000.EXAMPLE", "pdf_url_expires_in_seconds": 604800, "readable_until": "2026-11-12T09:00:20.000Z" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 0, "balance_pence": 1000, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" }, { "name": "request_id", "in": "path", "required": true, "description": "The request_id from the start request.", "schema": { "type": "string", "format": "uuid" }, "example": "6c1f4e2a-9b0d-4c3e-8f21-0a7d5b9e3c11" } ] } }, "/v1/market/active": { "post": { "operationId": "marketActive", "tags": [ "Market data" ], "summary": "Active listings", "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "vrm": { "type": "string" }, "total_found": { "type": "integer", "description": "How many matching adverts there are on the market (not how many were returned)." }, "total_estimated": { "type": "boolean", "description": "true when total_found was worked out from the share of fetched adverts that matched." }, "listings_returned": { "type": "integer" }, "match_criteria": { "type": "string", "description": "Comma list of what was actually matched, for example \"make,model,year,variant,transmission,body_type,doors,engine_size\"." }, "match_not_applied": { "type": "array", "items": { "type": "string" }, "description": "Fields you listed in `match` that are not matched in this version (for example fuel_type)." }, "listings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Our listing id: lst_ and 32 letters and digits. The same advert keeps the same id. Version 1: a different 64 character id; do not mix the two." }, "vrm": { "type": "string" }, "price": { "type": "integer", "description": "Asking price in pounds." }, "miles": { "type": "integer", "description": "Advertised mileage in miles." }, "year": { "type": "integer", "description": "Year of first registration, as the advert gives it." }, "make": { "type": "string" }, "model": { "type": "string" }, "variant": { "type": "string", "description": "Trim as the advert names it." }, "fuel_type": { "type": "string" }, "transmission": { "type": "string", "description": "Manual, Automatic, Semi Automatic or CVT." }, "drivetrain": { "type": "string", "description": "For example 4x2 or 4x4." }, "body_type": { "type": "string" }, "engine_size": { "type": "number", "description": "Litres, one decimal place (for example 1.5)." }, "power_bhp": { "type": "integer", "description": "Engine power in bhp, when the advert says." }, "euro_status": { "type": "string", "description": "Emissions standard, when the advert says." }, "ulez_compliant": { "type": "boolean", "description": "Sent only when the advert says." }, "colour": { "type": "string" }, "doors": { "type": "integer" }, "owners": { "type": "integer", "description": "Previous keepers, when the advert says." }, "first_registered": { "type": "string", "format": "date", "description": "Date of first registration, when the advert says. Version 1: an ISO 8601 date-time in UTC." }, "write_off_category": { "type": "string", "description": "Insurance write-off category shown on the advert (for example S or N). Left out when the advert shows none." }, "previous_price": { "type": "integer", "description": "An earlier advertised price for this car, in pounds, when one was seen." }, "previous_price_date": { "type": "string", "format": "date", "description": "When previous_price was seen. Version 1: an ISO 8601 date-time in UTC." }, "price_change_pct": { "type": "number", "description": "Change from previous_price to the current price, in per cent (negative = reduced)." }, "days_at_dealer": { "type": "integer", "description": "Days the car has been advertised by this dealer." }, "days_on_market": { "type": "integer", "description": "Days in the current advertising stretch." }, "dealer": { "type": "object", "properties": { "name": { "type": "string", "description": "Business name. For a dealer group this is the group name." }, "type": { "type": "string", "description": "franchise or independent, when the advert says." }, "location": { "type": "string", "description": "Town or city where the car is: the branch for a dealer group, else the dealer's address." }, "postcode": { "type": "string", "description": "Postcode where the car is (same rule as location)." }, "latitude": { "type": "number", "description": "Where the car is, when known." }, "longitude": { "type": "number", "description": "Where the car is, when known." } }, "additionalProperties": false, "description": "The seller. Contact details are never sent." }, "listing_url": { "type": "string", "format": "uri", "description": "The advert on the dealer's website." }, "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Up to 5 photo links (photo links only)." }, "first_seen": { "type": "string", "format": "date", "description": "When the advert first appeared. Version 1: an ISO 8601 date-time in UTC." }, "last_seen": { "type": "string", "format": "date", "description": "When the advert was last seen. Version 1: an ISO 8601 date-time in UTC." } }, "additionalProperties": false, "description": "A live advert. Fields we do not hold for an advert are left out." }, "description": "Cheapest first. Adverts with a price only." } }, "required": [ "vrm", "total_found", "total_estimated", "listings_returned", "match_criteria", "listings" ], "additionalProperties": false, "description": "Similar vehicles for sale now." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "vrm": "SA22LZH", "total_found": 31, "total_estimated": false, "listings_returned": 1, "match_criteria": "make,model,year,variant,transmission,body_type,doors,engine_size", "listings": [ { "id": "lst_049e1f30bcd3e3be940917dc0e5f244c", "price": 10358, "miles": 92014, "year": 2022, "make": "KIA", "model": "ProCeed", "variant": "Pro Ceed Gt-line Isg", "fuel_type": "Petrol", "transmission": "Manual", "drivetrain": "4x2", "body_type": "Estate", "engine_size": 1.5, "colour": "Grey", "doors": 5, "days_on_market": 116, "dealer": { "name": "CARSA LIMITED", "location": "Southampton", "postcode": "SO31 7FL" }, "last_seen": "2026-10-17" } ] }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 15, "balance_pence": 985, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "rows": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "example": 50, "description": "How many listings to return. Default 50, maximum 200." }, "match": { "description": "Optional. Comma list (or array) of the optional filters to keep: `transmission`, `body_type`, `engine_size`. Without it all three apply. Other names are reported in match_not_applied.", "oneOf": [ { "type": "string", "example": "transmission" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "vrm" ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs." }, "examples": { "registration": { "summary": "One listing", "value": { "vrm": "SA22LZH", "rows": 1 } } } } } }, "x-price-pence": { "packages": { "payg": 15, "starter": 12, "pro": 10, "enterprise": 5 } } } }, "/v1/market/sold": { "post": { "operationId": "marketSold", "tags": [ "Market data" ], "summary": "Sold listings", "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "vrm": { "type": "string" }, "total_found": { "type": "integer", "description": "How many matching adverts there are on the market (not how many were returned)." }, "total_estimated": { "type": "boolean", "description": "true when total_found was worked out from the share of fetched adverts that matched." }, "listings_returned": { "type": "integer" }, "match_criteria": { "type": "string", "description": "Comma list of what was actually matched, for example \"make,model,year,variant,transmission,body_type,doors,engine_size\"." }, "match_not_applied": { "type": "array", "items": { "type": "string" }, "description": "Fields you listed in `match` that are not matched in this version (for example fuel_type)." }, "returned_listings_summary": { "type": "object", "properties": { "count": { "type": "integer" }, "price_stats": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "average": { "type": "integer" }, "median": { "type": "integer" } }, "additionalProperties": false }, "days_to_sell_stats": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "average": { "type": "integer" }, "median": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Covers only the listings in this response (the cheapest), not the market. Use the insights endpoints for whole-market sold figures. Version 1: named summary, and its median is the upper of the two middle values when the count is even." }, "listings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Our listing id: lst_ and 32 letters and digits. The same advert keeps the same id. Version 1: a different 64 character id; do not mix the two." }, "vrm": { "type": "string" }, "sold_price": { "type": "integer", "description": "The last asking price in pounds (not a confirmed sale price)." }, "miles": { "type": "integer", "description": "Advertised mileage in miles." }, "year": { "type": "integer", "description": "Year of first registration, as the advert gives it." }, "make": { "type": "string" }, "model": { "type": "string" }, "variant": { "type": "string", "description": "Trim as the advert names it." }, "fuel_type": { "type": "string" }, "transmission": { "type": "string", "description": "Manual, Automatic, Semi Automatic or CVT." }, "drivetrain": { "type": "string", "description": "For example 4x2 or 4x4." }, "body_type": { "type": "string" }, "engine_size": { "type": "number", "description": "Litres, one decimal place (for example 1.5)." }, "power_bhp": { "type": "integer", "description": "Engine power in bhp, when the advert says." }, "euro_status": { "type": "string", "description": "Emissions standard, when the advert says." }, "ulez_compliant": { "type": "boolean", "description": "Sent only when the advert says." }, "colour": { "type": "string" }, "doors": { "type": "integer" }, "owners": { "type": "integer", "description": "Previous keepers, when the advert says." }, "first_registered": { "type": "string", "format": "date", "description": "Date of first registration, when the advert says. Version 1: an ISO 8601 date-time in UTC." }, "write_off_category": { "type": "string", "description": "Insurance write-off category shown on the advert (for example S or N). Left out when the advert shows none." }, "previous_price": { "type": "integer", "description": "An earlier advertised price for this car, in pounds, when one was seen." }, "previous_price_date": { "type": "string", "format": "date", "description": "When previous_price was seen. Version 1: an ISO 8601 date-time in UTC." }, "price_change_pct": { "type": "number", "description": "Change from previous_price to the current price, in per cent (negative = reduced)." }, "days_at_dealer": { "type": "integer", "description": "Days the car has been advertised by this dealer." }, "days_to_sell": { "type": "integer", "description": "Days in the last advertising stretch before the advert ended." }, "dealer": { "type": "object", "properties": { "name": { "type": "string", "description": "Business name. For a dealer group this is the group name." }, "type": { "type": "string", "description": "franchise or independent, when the advert says." }, "location": { "type": "string", "description": "Town or city where the car is: the branch for a dealer group, else the dealer's address." }, "postcode": { "type": "string", "description": "Postcode where the car is (same rule as location)." }, "latitude": { "type": "number", "description": "Where the car is, when known." }, "longitude": { "type": "number", "description": "Where the car is, when known." } }, "additionalProperties": false, "description": "The seller. Contact details are never sent." }, "first_listed": { "type": "string", "format": "date", "description": "When the advert first appeared. Version 1: an ISO 8601 date-time in UTC." }, "sold_date": { "type": "string", "format": "date", "description": "The last day the advert was seen. A car counts as sold when its advert ended and did not reappear. Version 1: an ISO 8601 date-time in UTC." } }, "additionalProperties": false, "description": "A sold advert (no photos or links: the advert has ended). Fields we do not hold are left out." }, "description": "Cheapest first. Adverts with a price only." } }, "required": [ "vrm", "total_found", "total_estimated", "listings_returned", "match_criteria", "returned_listings_summary", "listings" ], "additionalProperties": false, "description": "Similar vehicles recently sold." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "vrm": "SA22LZH", "total_found": 60, "total_estimated": false, "listings_returned": 1, "match_criteria": "make,model,year,variant,transmission,body_type,doors,engine_size", "returned_listings_summary": { "count": 1, "price_stats": { "min": 9995, "max": 9995, "average": 9995, "median": 9995 }, "days_to_sell_stats": { "min": 79, "max": 79, "average": 79, "median": 79 } }, "listings": [ { "id": "lst_824f293e01ae03fecd9128985ed5db22", "sold_price": 9995, "miles": 94980, "year": 2022, "make": "KIA", "model": "Proceed", "variant": "Pro Ceed Gt-line Isg", "fuel_type": "Petrol", "transmission": "Manual", "drivetrain": "4x2", "body_type": "Estate", "engine_size": 1.5, "colour": "Grey", "doors": 5, "days_to_sell": 79, "dealer": { "name": "Beehive Cars", "location": "Bolton", "postcode": "BL6 6DT" }, "sold_date": "2026-07-26" } ] }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 15, "balance_pence": 985, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "rows": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "example": 50, "description": "How many listings to return. Default 50, maximum 200." }, "match": { "description": "Optional. Comma list (or array) of the optional filters to keep: `transmission`, `body_type`, `engine_size`. Without it all three apply.", "oneOf": [ { "type": "string", "example": "transmission" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "vrm" ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs." }, "examples": { "registration": { "summary": "One sold listing", "value": { "vrm": "SA22LZH", "rows": 1 } } } } } }, "x-price-pence": { "packages": { "payg": 15, "starter": 12, "pro": 10, "enterprise": 5 } } } }, "/v1/market/insights": { "post": { "operationId": "marketInsights", "tags": [ "Market data" ], "summary": "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "insights": { "type": "object", "properties": { "vrm": { "type": "string" }, "supply": { "type": "object", "properties": { "active_listings": { "type": "integer" }, "estimated": { "type": "boolean" }, "level": { "type": "string", "enum": [ "VERY_LOW", "LOW", "MODERATE", "HIGH", "VERY_HIGH", "UNKNOWN" ] }, "description": { "type": "string" } }, "additionalProperties": false }, "demand": { "type": "object", "properties": { "sold_last_90_days": { "type": "integer", "description": "Sold adverts with a price that match the car." }, "sold_with_price": { "type": "integer", "description": "How many sold prices the price figures are based on." }, "median_days_to_sell": { "type": "integer" }, "mean_days_to_sell": { "type": "integer" }, "fast_sale_days": { "type": "integer", "description": "A quarter of the sold cars sold within this many days." }, "slow_sale_days": { "type": "integer", "description": "Three quarters of the sold cars sold within this many days." }, "level": { "type": "string", "enum": [ "VERY_LOW", "LOW", "MODERATE", "HIGH", "VERY_HIGH", "UNKNOWN" ], "description": "UNKNOWN when there is no sold data, or fewer than 5 sold cars. Version 1: the fewer-than-5 rule does not apply." }, "description": { "type": "string" } }, "additionalProperties": false, "description": "Sold figures cover the last 90 days, matched like the live adverts (make, model, trims, year, gearbox, body and engine; doors cannot be matched on sold adverts), adverts with a price only. Prices are last asking prices in whole pounds." }, "pricing": { "type": "object", "properties": { "sold_price_min": { "type": "integer" }, "sold_price_max": { "type": "integer" }, "sold_price_mean": { "type": "integer" }, "sold_price_median": { "type": "integer" }, "percentile_25": { "type": "integer" }, "percentile_75": { "type": "integer" }, "percentile_90": { "type": "integer" } }, "additionalProperties": false, "description": "Sold prices across the whole market for the same car, in whole pounds." }, "market_rating": { "type": "object", "properties": { "score": { "type": "number", "description": "0 to 10. Left out when there is too little sold data to rate the market (no days to sell, or in version 2 fewer than 5 sold cars)." }, "max_score": { "type": "integer" }, "interpretation": { "type": "string", "description": "Strong market, Average market, Challenging market, or Insufficient data when there is no score." } }, "additionalProperties": false }, "recommendations": { "type": "array", "items": { "type": "string" } } }, "required": [ "vrm" ], "additionalProperties": false, "description": "Fields we do not hold for this car are left out." } }, "required": [ "insights" ], "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "insights": { "vrm": "SA22LZH", "supply": { "active_listings": 31, "estimated": false, "level": "LOW", "description": "Limited availability" }, "demand": { "sold_last_90_days": 68, "sold_with_price": 67, "median_days_to_sell": 20, "mean_days_to_sell": 30, "fast_sale_days": 10, "slow_sale_days": 43, "level": "HIGH", "description": "Vehicles sell quickly" }, "pricing": { "sold_price_min": 9995, "sold_price_max": 17999, "sold_price_mean": 14410, "sold_price_median": 14395, "percentile_25": 13898, "percentile_75": 15224, "percentile_90": 16537 }, "market_rating": { "score": 8.3, "max_score": 10, "interpretation": "Strong market" }, "recommendations": [ "High demand with limited supply - good time to sell" ] } }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 10, "balance_pence": 990, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." } }, "required": [ "vrm" ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs." }, "examples": { "registration": { "summary": "By registration", "value": { "vrm": "SA22LZH" } } } } } }, "x-price-pence": { "packages": { "payg": 10, "starter": 8, "pro": 6, "enterprise": 4 } } } }, "/v1/pricing/insights": { "post": { "operationId": "pricingInsights", "tags": [ "Analysis" ], "summary": "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.\n\nSend `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs.\n\nSandbox keys answer only for the published test registrations (GET /v1/sandbox/vrms); any other vehicle is 404 SANDBOX_VEHICLE_NOT_AVAILABLE (version 1: SANDBOX_VRM_NOT_ALLOWED).\n\nFields with no value are omitted from the answer.", "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit-Second": { "$ref": "#/components/headers/X-RateLimit-Limit-Second" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/X-RateLimit-Limit-Minute" }, "X-RateLimit-Limit-Day": { "$ref": "#/components/headers/X-RateLimit-Limit-Day" }, "X-RateLimit-Remaining-Second": { "$ref": "#/components/headers/X-RateLimit-Remaining-Second" }, "X-RateLimit-Remaining-Minute": { "$ref": "#/components/headers/X-RateLimit-Remaining-Minute" }, "X-RateLimit-Remaining-Day": { "$ref": "#/components/headers/X-RateLimit-Remaining-Day" }, "X-RateLimit-Reset-Second": { "$ref": "#/components/headers/X-RateLimit-Reset-Second" }, "X-RateLimit-Reset-Minute": { "$ref": "#/components/headers/X-RateLimit-Reset-Minute" }, "X-RateLimit-Reset-Day": { "$ref": "#/components/headers/X-RateLimit-Reset-Day" }, "X-Package-Limit-Second": { "$ref": "#/components/headers/X-Package-Limit-Second" }, "X-Package-Limit-Minute": { "$ref": "#/components/headers/X-Package-Limit-Minute" }, "X-Package-Limit-Day": { "$ref": "#/components/headers/X-Package-Limit-Day" }, "X-Package-Remaining-Day": { "$ref": "#/components/headers/X-Package-Remaining-Day" }, "X-Endpoint-Limit-Day": { "$ref": "#/components/headers/X-Endpoint-Limit-Day" }, "X-Endpoint-Remaining-Day": { "$ref": "#/components/headers/X-Endpoint-Remaining-Day" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "insights": { "type": "object", "properties": { "vrm": { "type": "string" }, "vehicle": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "variant": { "type": "string" }, "year": { "type": "integer", "description": "Year of manufacture." }, "fuel_type": { "type": "string" }, "transmission": { "type": "string" } }, "additionalProperties": false }, "market_overview": { "type": "object", "properties": { "active_supply": { "type": "integer" }, "active_supply_estimated": { "type": "boolean" }, "sold_last_90_days": { "type": "integer", "description": "Sold adverts with a price that match the car." }, "median_days_to_sell": { "type": "integer" }, "supply_level": { "type": "string", "enum": [ "VERY_LOW", "LOW", "MODERATE", "HIGH", "VERY_HIGH", "UNKNOWN" ], "description": "The same bands as /v1/market/insights. Version 1: LOW, MODERATE or HIGH (under 50, under 150, 150 or more)." }, "demand_level": { "type": "string", "enum": [ "VERY_LOW", "LOW", "MODERATE", "HIGH", "VERY_HIGH", "UNKNOWN" ], "description": "The same bands as /v1/market/insights (UNKNOWN with fewer than 5 sold cars). Version 1: LOW, MODERATE, HIGH or UNKNOWN." } }, "additionalProperties": false, "description": "Sold figures cover the last 90 days, matched like the live adverts (make, model, trims, year, gearbox, body and engine; doors cannot be matched on sold adverts), adverts with a price only. Prices are last asking prices in whole pounds." }, "pricing_analysis": { "type": "object", "properties": { "asking_price": { "type": "integer", "description": "Your price, when sent." }, "market_position": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "VERY_LOW", "LOW", "AVERAGE", "HIGH", "VERY_HIGH", "UNKNOWN" ] }, "percentile": { "type": "integer", "description": "Share of matching adverts priced below yours. Left out when position is UNKNOWN (no adverts with a price to compare with)." }, "comparison": { "type": "string" }, "compared_with": { "type": "integer", "description": "How many adverts with a price your price was ranked against." }, "estimated": { "type": "boolean", "description": "true when compared_with is an estimate." } }, "additionalProperties": false, "description": "Sent when `price` was sent." }, "sold_prices": { "type": "object", "properties": { "count": { "type": "integer", "description": "How many sold prices these figures are based on." }, "min": { "type": "integer" }, "max": { "type": "integer" }, "average": { "type": "integer" }, "median": { "type": "integer" }, "percentile_25": { "type": "integer" }, "percentile_75": { "type": "integer" } }, "additionalProperties": false, "description": "Sold prices in whole pounds." }, "lowest_active_prices": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "integer" }, "miles": { "type": "integer" }, "year": { "type": "integer" }, "days_on_market": { "type": "integer" }, "dealer": { "type": "string", "description": "Left out when the advert gives no name." }, "location": { "type": "string", "description": "Where the car is (the branch for a dealer group)." } }, "additionalProperties": false }, "description": "The five cheapest matching adverts." }, "recommended_price_range": { "type": "object", "properties": { "competitive": { "type": "integer" }, "market": { "type": "integer" }, "premium": { "type": "integer" } }, "additionalProperties": false, "description": "From sold prices: competitive = lower quartile, market = median, premium = upper quartile. Left out when we hold too few sold prices. Version 1: the median less 5%, the median, the median plus 5%." } }, "additionalProperties": false }, "selling_estimate": { "type": "object", "properties": { "expected_days": { "type": "integer" }, "fast_sale_days": { "type": "integer" }, "slow_sale_days": { "type": "integer" }, "factors": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "recommendations": { "type": "array", "items": { "type": "string" } } }, "required": [ "vrm" ], "additionalProperties": false, "description": "Fields we do not hold for this car are left out." } }, "required": [ "insights" ], "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "example": { "success": true, "data": { "insights": { "vrm": "SA22LZH", "vehicle": { "make": "Kia", "model": "Proceed", "variant": "GT-Line ISG", "year": 2022, "fuel_type": "PETROL", "transmission": "Manual" }, "market_overview": { "active_supply": 31, "active_supply_estimated": false, "sold_last_90_days": 68, "median_days_to_sell": 20, "supply_level": "LOW", "demand_level": "HIGH" }, "pricing_analysis": { "asking_price": 14500, "market_position": { "position": "AVERAGE", "percentile": 65, "comparison": "Priced competitively with market", "compared_with": 31, "estimated": false }, "sold_prices": { "count": 67, "min": 9995, "max": 17999, "average": 14410, "median": 14395, "percentile_25": 13898, "percentile_75": 15224 }, "lowest_active_prices": [ { "price": 10358, "miles": 92014, "year": 2022, "days_on_market": 116, "dealer": "CARSA LIMITED", "location": "Southampton" }, { "price": 10590, "miles": 92779, "year": 2022, "days_on_market": 42, "dealer": "Dani Motors", "location": "Luton" }, { "price": 11795, "miles": 65000, "year": 2022, "days_on_market": 36, "dealer": "Gcs Thrapston", "location": "Thrapston" }, { "price": 12100, "miles": 58085, "year": 2022, "days_on_market": 44, "dealer": "Hilton Garage", "location": "Derby" }, { "price": 12190, "miles": 63509, "year": 2022, "days_on_market": 93, "dealer": "Westbrook Car Sales", "location": "Peterborough" } ], "recommended_price_range": { "competitive": 13898, "market": 14395, "premium": 15224 } }, "selling_estimate": { "expected_days": 20, "fast_sale_days": 10, "slow_sale_days": 43, "factors": [ "High demand market" ] }, "recommendations": [ "Price is in line with market", "Strong demand - vehicles selling quickly" ] } }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "cost_pence": 10, "balance_pence": 990, "is_sandbox": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "parameters": [ { "$ref": "#/components/parameters/ErrorCodesVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vrm": { "type": "string", "example": "SA22TLZ", "description": "UK registration. 2 to 8 letters and digits after spaces are removed." }, "price": { "type": "integer", "minimum": 1, "example": 31500, "description": "Optional. Your asking price in pounds." } }, "required": [ "vrm" ], "description": "Send `vrm` (UK registration, 2 to 8 letters and digits, spaces ignored). A `vin` is refused with 400 VIN_NOT_SUPPORTED (version 1: INVALID_REQUEST): use an endpoint that accepts VINs." }, "examples": { "registration": { "summary": "With an asking price", "value": { "vrm": "SA22LZH", "price": 14500 } } } } } }, "x-price-pence": { "packages": { "payg": 10, "starter": 8, "pro": 6, "enterprise": 4 } } } }, "/v1/sandbox/vrms": { "get": { "operationId": "sandboxVrms", "tags": [ "Sandbox" ], "summary": "Sandbox registrations", "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.", "responses": { "200": { "description": "Success.", "headers": { "Cache-Control": { "description": "Public, cacheable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "notice": { "type": "string" }, "vrms": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "vrm", "scenario", "categories", "markers" ], "properties": { "vrm": { "type": "string" }, "vin": { "type": [ "string", "null" ] }, "scenario": { "type": "string", "enum": [ "stolen-police", "stolen-insurer", "write-off", "scrapped", "finance", "plate-change", "electric", "hybrid", "general" ], "description": "The main case this registration exercises." }, "categories": { "type": "array", "items": { "type": "string" } }, "markers": { "type": "array", "items": { "type": "string" }, "description": "Everything this record carries, for example \"write-off (Cat B)\", \"finance\", \"service history\"." }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "year": { "type": [ "integer", "null" ] }, "fuel_type": { "type": [ "string", "null" ] } } } } }, "required": [ "count", "notice", "vrms" ], "additionalProperties": false } } }, "example": { "success": true, "data": { "count": 177, "notice": "Sandbox data may not be accurate and is for testing purposes only. It must not be shown to end users or used in production.", "vrms": [ { "vrm": "RO21PAD", "vin": "LSJWP4396SZ244868", "scenario": "write-off", "categories": [ "General" ], "markers": [ "write-off (Cat B)", "finance", "scrapped", "plate change", "hybrid", "valuation", "spec" ], "make": "MG", "model": "3 TROPHY HEV AUTO", "year": 2025, "fuel_type": "HYBRID ELECTRIC" } ] } } } } } }, "security": [] } }, "/v1/openapi.json": { "get": { "operationId": "openApiDescription", "tags": [ "Reference" ], "summary": "This OpenAPI description", "description": "This document, as JSON. Public: no API key needed. Also at /developer/openapi.json.", "responses": { "200": { "description": "Success.", "headers": { "Cache-Control": { "description": "Public, cacheable.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.1 document." }, "example": { "openapi": "3.1.0" } } } } }, "security": [] } } }, "webhooks": { "balance.low": { "post": { "operationId": "webhook_balance_low", "tags": [ "Webhooks" ], "summary": "Your prepaid balance has dropped below your low balance level.", "description": "Once each time a charged live request takes the balance below the level. It is sent again only after a top-up brings the balance back above the level. The level is the low balance alert level on your Billing page; if that alert is off, the level you set on the endpoint (default £10) is used.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "balance.low" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "balance.low", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "balance_pence": 840, "threshold_pence": 1000, "currency": "GBP" } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "balance.topped_up": { "post": { "operationId": "webhook_balance_topped_up", "tags": [ "Webhooks" ], "summary": "A top-up has been paid and added to your balance.", "description": "When a top-up payment is confirmed and credited.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "balance.topped_up" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "balance.topped_up", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "amount_pence": 5000, "balance_pence": 5840, "currency": "GBP" } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "key.created": { "post": { "operationId": "webhook_key_created", "tags": [ "Webhooks" ], "summary": "An API key was created on your account.", "description": "When a live or sandbox key is created. The key itself is never sent: only its name, mode and last four characters.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "key.created" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "key.created", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "key": { "name": "Production server", "mode": "live", "last4": "9e80", "created_at": "2026-11-05T09:00:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "key.revoked": { "post": { "operationId": "webhook_key_revoked", "tags": [ "Webhooks" ], "summary": "An API key on your account was revoked.", "description": "When a key is revoked. Requests with that key are refused from that moment.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "key.revoked" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "key.revoked", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "key": { "name": "Old staging key", "mode": "sandbox", "last4": "41c2", "revoked_at": "2026-11-05T09:30:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "plan.changed": { "post": { "operationId": "webhook_plan_changed", "tags": [ "Webhooks" ], "summary": "Your API plan changed and the new per-call prices apply now.", "description": "When a subscription starts, a paid upgrade lands, a scheduled downgrade takes effect at renewal, or the subscription ends and the account returns to Pay As You Go.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "plan.changed" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "plan.changed", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "from_plan": "payg", "from_plan_name": "Pay As You Go", "to_plan": "starter", "to_plan_name": "Starter", "reason": "subscription_started" } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "plan.change_scheduled": { "post": { "operationId": "webhook_plan_change_scheduled", "tags": [ "Webhooks" ], "summary": "A plan change has been booked for the end of the current period.", "description": "When you schedule a downgrade or a cancellation, or remove one you scheduled earlier.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "plan.change_scheduled" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "plan.change_scheduled", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "from_plan": "pro", "from_plan_name": "Pro", "to_plan": "starter", "to_plan_name": "Starter", "kind": "downgrade", "effective_date": "2026-12-06" } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "subscription.payment_failed": { "post": { "operationId": "webhook_subscription_payment_failed", "tags": [ "Webhooks" ], "summary": "A subscription renewal payment did not go through.", "description": "When a renewal charge is declined or overdue. At most once a day per subscription.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "subscription.payment_failed" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "subscription.payment_failed", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "plan": "starter", "plan_name": "Starter", "message": "Your subscription renewal payment failed. Update your card on the Billing page to keep your plan." } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "service_history.completed": { "post": { "operationId": "webhook_service_history_completed", "tags": [ "Webhooks" ], "summary": "A service history request finished. Same body as the request callback.", "description": "When a service history request completes (with or without records). The data object is exactly the body we POST to the request's callback_url.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "service_history.completed" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "service_history.completed", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "event": "service_history.completed", "request_id": "7d5c2a9e-3f1b-4c6d-9a8e-1b2c3d4e5f60", "sent_at": "2026-11-05T10:12:01.000Z", "data": { "request_id": "7d5c2a9e-3f1b-4c6d-9a8e-1b2c3d4e5f60", "vrm": "SK22AOM", "status": "completed", "message": "Service history retrieved. Sample data for testing. These are not the records of this or any real vehicle.", "requested_at": "2026-11-05T10:11:40.000Z", "completed_at": "2026-11-05T10:12:00.000Z", "check_after_seconds": null, "status_url": "https://www.dealerpricing.co.uk/api/v1/vehicle/service-history/7d5c2a9e-3f1b-4c6d-9a8e-1b2c3d4e5f60", "callback_url": "https://example.com/hooks/service-history", "cost_pence": 0, "refunded_pence": 0, "error": null, "outcome": "records", "error_code": null, "service_history": { "record_count": 7, "services": [ { "date": "2022-04-21", "date_raw": "21/04/2022", "type": "Service / Repair", "mileage": 12, "mileage_raw": "12 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Pre-delivery inspection" }, { "date": "2023-03-14", "date_raw": "14/03/2023", "type": "Service / Repair", "mileage": 9214, "mileage_raw": "9,214 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Oil change service" }, { "date": "2024-02-02", "date_raw": "02/02/2024", "type": "Service / Repair", "mileage": 18905, "mileage_raw": "18,905 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Inspection with oil change" }, { "date": "2024-07-15", "date_raw": "15/07/2024", "type": "Service / Repair", "mileage": 33600, "mileage_raw": "33,600 km", "mileage_unit": "km", "workshop": "Example Garage Europe, Exampleville", "notes": "Puncture repair" }, { "date": "2024-09-11", "date_raw": "11/09/2024", "type": "Service / Repair", "mileage": 23410, "mileage_raw": "23,410 mi", "mileage_unit": "mi", "workshop": "Example Autos Service Centre, Exampleton", "notes": "Brake fluid change" }, { "date": "2025-03-28", "date_raw": "28/03/2025", "type": "Service / Repair", "mileage": 29876, "mileage_raw": "29,876 mi", "mileage_unit": "mi", "workshop": "Example Autos Service Centre, Exampleton", "notes": "Oil change service" }, { "date": "2026-03-06", "date_raw": "06/03/2026", "type": "Service / Repair", "mileage": 38120, "mileage_raw": "38,120 mi", "mileage_unit": "mi", "workshop": "Sample Motors (Main Dealer), Exampleton", "notes": "Inspection with oil change and pollen filter" } ], "message": null, "retrieved_at": "2026-11-05T10:12:00.000Z", "sample": true, "sample_notice": "Sample data for testing. These are not the records of this or any real vehicle." }, "pdf_url": "https://www.dealerpricing.co.uk/api/service-history/pdf/5a3b1e00-5a3b-4e00-8000-000000000001?t=1765000000.EXAMPLE", "pdf_url_expires_in_seconds": 604800, "readable_until": "2026-11-12T10:12:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "service_history.failed": { "post": { "operationId": "webhook_service_history_failed", "tags": [ "Webhooks" ], "summary": "A service history request failed and was refunded. Same body as the request callback.", "description": "When a service history request fails. The data object is exactly the body we POST to the request's callback_url.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "service_history.failed" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "service_history.failed", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "event": "service_history.failed", "request_id": "7d5c2a9e-3f1b-4c6d-9a8e-1b2c3d4e5f60", "sent_at": "2026-11-05T10:12:01.000Z", "data": { "request_id": "7d5c2a9e-3f1b-4c6d-9a8e-1b2c3d4e5f60", "vrm": "SK22AOM", "status": "failed", "message": "The service history could not be retrieved because of a fault. This request has been refunded in full.", "requested_at": "2026-11-05T10:11:40.000Z", "completed_at": "2026-11-05T10:12:00.000Z", "check_after_seconds": null, "status_url": "https://www.dealerpricing.co.uk/api/v1/vehicle/service-history/7d5c2a9e-3f1b-4c6d-9a8e-1b2c3d4e5f60", "callback_url": "https://example.com/hooks/service-history", "cost_pence": 200, "refunded_pence": 200, "error": "The service history could not be retrieved because the manufacturer network had a temporary fault. You can make a new request.", "outcome": "failed", "error_code": "SOURCE_UNAVAILABLE", "service_history": null, "pdf_url": null, "pdf_url_expires_in_seconds": null, "readable_until": "2026-11-12T10:12:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "limit.daily_cap_reached": { "post": { "operationId": "webhook_limit_daily_cap_reached", "tags": [ "Webhooks" ], "summary": "A daily limit on your plan was reached; further live requests are refused until midnight UK time.", "description": "The first time in a UK day that a live request is refused for the plan's daily limit or an endpoint's daily cap. Once per limit per day.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "limit.daily_cap_reached" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "limit.daily_cap_reached", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "limit": "endpoint_daily_cap", "endpoint": "provenance", "daily_cap": 500, "plan": "starter", "plan_name": "Starter", "resets_at": "2026-11-06T00:00:00.000Z" } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "account.email_changed": { "post": { "operationId": "webhook_account_email_changed", "tags": [ "Webhooks" ], "summary": "The sign-in email address of your developer account changed.", "description": "When the account email address changes: straight away for an account that is not verified yet, otherwise when the new address is confirmed.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "account.email_changed" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "account.email_changed", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "email": "new-address@example.com", "previous_email": "old-address@example.com", "changed_at": "2026-11-05T11:00:00.000Z" } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } }, "api.notice": { "post": { "operationId": "webhook_api_notice", "tags": [ "Webhooks" ], "summary": "An announcement about the API, for example a change to error codes.", "description": "When DealerPricing publishes a notice to API customers.\n\nEvery event (and every service history callback) is a JSON POST signed with your account's signing secret (create it on the Webhooks page of the developer portal). The DP-Signature header is `t=,v1=`: v1 is the HMAC-SHA256, keyed with your whole signing secret, of `.`.\n\nVerify it against the raw body before parsing, compare in constant time and reject a t more than 300 seconds from your clock. For 24 hours after you roll the secret the header carries two v1 values (new and old secret); accept either.\n\nAnswer any 2xx within 10 seconds. Anything else is retried after 5, 15, 30, 120, 360, 1440 minutes, with the same DP-Event-Id: use it to ignore duplicates.", "security": [], "parameters": [ { "name": "DP-Signature", "in": "header", "required": true, "description": "Signature: t=,v1=.\">.", "schema": { "type": "string" } }, { "name": "DP-Event-Id", "in": "header", "required": true, "description": "The event id (the same on every retry).", "schema": { "type": "string" } }, { "name": "DP-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string", "enum": [ "api.notice" ] } }, { "name": "DP-Delivery-Attempt", "in": "header", "required": true, "description": "Delivery attempt number, from 1.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f", "type": "api.notice", "created": "2026-11-05T10:15:02.000Z", "livemode": true, "data": { "title": "Clearer error codes", "message": "From 1 February 2027 every account gets the version 2 error codes. Until then you can switch early.", "url": "https://www.dealerpricing.co.uk/developer/errors", "effective_date": "2027-02-01" } } } } }, "responses": { "2XX": { "description": "Received. Any 2xx within 10 seconds counts as delivered." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your live (dp_live_...) or sandbox (dp_sandbox_...) key." } }, "headers": { "X-Request-Id": { "description": "Id of this request (also in the body). (Every response.)", "schema": { "type": "string" } }, "X-RateLimit-Limit-Second": { "description": "This key's per-second limit. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Minute": { "description": "This key's per-minute limit. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "This key's daily limit (UK calendar day). (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Second": { "description": "Requests left this second on this key. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests left this minute on this key. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left today on this key. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Second": { "description": "Seconds until the per-second window resets. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Seconds until the per-minute window resets. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Seconds until midnight UK time. (After the key is accepted.)", "schema": { "type": "integer" } }, "X-Package-Limit-Second": { "description": "Your package's per-second limit across all live keys. (Live keys.)", "schema": { "type": "integer" } }, "X-Package-Limit-Minute": { "description": "Your package's per-minute limit across all live keys. (Live keys.)", "schema": { "type": "integer" } }, "X-Package-Limit-Day": { "description": "Your package's daily limit across all live keys. (Live keys.)", "schema": { "type": "integer" } }, "X-Package-Remaining-Day": { "description": "Requests left today on your package. (Live keys.)", "schema": { "type": "integer" } }, "X-Endpoint-Limit-Day": { "description": "Your daily cap for this endpoint. (Live keys, capped endpoints.)", "schema": { "type": "integer" } }, "X-Endpoint-Remaining-Day": { "description": "Requests left today on this endpoint. (Live keys, capped endpoints.)", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying. (429 responses.)", "schema": { "type": "integer" } }, "DP-Error-Codes": { "description": "The error code version used for this answer: 1 or 2. (Every response from a keyed endpoint.)", "schema": { "type": "string", "enum": [ "1", "2" ] } } }, "parameters": { "ErrorCodesVersion": { "name": "DP-Error-Codes", "in": "header", "required": false, "description": "Optional. 1 or 2: the error code version for this request, overriding your account setting. From 1 February 2027 version 2 is the default for everyone; version 1 can still be asked for until 2 May 2027.", "schema": { "type": "string", "enum": [ "1", "2" ] } } }, "schemas": { "Meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_3f9a1c0d2b7e4a5f6c8d9e01", "description": "Id of this request. Also sent in the X-Request-Id header. Quote it when you contact support." }, "cost_pence": { "type": "integer", "description": "What this request cost, in pence. 0 for sandbox keys, free endpoints and requests that were refunded." }, "balance_pence": { "type": "integer", "description": "Your topped-up balance after this request, in pence." }, "plan_credit_pence": { "type": "integer", "description": "Plan credit left after this request, in pence. Sent only to accounts on a monthly package that hold plan credit." }, "from_plan_credit_pence": { "type": "integer", "description": "How much of cost_pence was paid from plan credit (the rest came from the balance). Sent with plan_credit_pence." }, "is_sandbox": { "type": "boolean", "description": "True when the request used a sandbox key." }, "sandbox": { "type": "boolean", "const": true, "description": "Sandbox keys only." }, "notice": { "type": "string", "description": "Sandbox keys only: sandbox data may not be accurate and is for testing only, never for end users or production decisions." }, "data_captured_at": { "type": "string", "format": "date-time", "description": "Sandbox keys only: when the stored test data was captured." }, "records_generated_at": { "type": "object", "properties": { "police_record": { "type": "string", "format": "date-time" }, "insurer_register": { "type": "string", "format": "date-time" }, "finance": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Provenance only: when each source built the record this check read. Only sources that say so are listed." }, "model_data_held": { "type": "boolean", "const": false, "description": "Decode only: sent as false when the manufacturer model data is not held for this vehicle, so the model-data fields are missing for that reason." }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATE_IN_RETENTION", "PARAMETER_IGNORED" ] }, "message": { "type": "string" }, "parameter": { "type": "string", "description": "PARAMETER_IGNORED: the request field that was not used." } }, "required": [ "code", "message" ], "additionalProperties": false }, "description": "Facts about a successful answer that are not errors. Sent only when there is one. PLATE_IN_RETENTION: The registration is on a retention certificate. The data returned is for the last vehicle that carried it, which may not be the vehicle in front of you. PARAMETER_IGNORED: A field you sent was not used (for example mileage that is not a positive number, rows above the maximum, or a match option that does not apply). parameter names it." } }, "required": [ "request_id", "cost_pence", "balance_pence", "is_sandbox" ], "additionalProperties": false, "description": "Request bookkeeping, sent with every successful answer." }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_API_KEY", "INVALID_API_KEY", "API_KEY_REVOKED", "ACCOUNT_DISABLED", "EMAIL_NOT_VERIFIED", "SANDBOX_NOT_SUPPORTED", "MISSING_PARAMETER", "INVALID_PARAMETER", "INVALID_VRM", "INVALID_VIN", "VIN_NOT_SUPPORTED", "INVALID_REQUEST_ID", "VEHICLE_NOT_FOUND", "SANDBOX_VEHICLE_NOT_AVAILABLE", "REQUEST_NOT_FOUND", "REQUEST_EXPIRED", "VALUATION_NOT_AVAILABLE", "SPEC_NOT_AVAILABLE", "HISTORY_NOT_AVAILABLE", "MARKET_DATA_NOT_AVAILABLE", "SERVICE_HISTORY_NOT_AVAILABLE", "INSUFFICIENT_BALANCE", "RATE_LIMIT_EXCEEDED", "SANDBOX_DAILY_LIMIT_REACHED", "PACKAGE_LIMIT_EXCEEDED", "ENDPOINT_DAILY_CAP_REACHED", "TOO_MANY_OPEN_REQUESTS", "SOURCE_UNAVAILABLE", "SOURCE_LIMIT_REACHED", "INTERNAL_ERROR", "INVALID_API_KEY_FORMAT", "API_KEY_DISABLED", "INVALID_REQUEST", "SANDBOX_VRM_NOT_ALLOWED", "UPSTREAM_ERROR" ], "description": "Machine-readable error code. Version 2 codes are listed first; the version 1 codes after them are sent only to accounts still on version 1 (see DP-Error-Codes). Match on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Do not match on this text: it can change." }, "details": { "type": "object", "additionalProperties": true, "description": "Extra facts for this error. Always carries request_id. Errors raised after the request was accepted also carry cost_pence (0: refunded) and balance_pence. INSUFFICIENT_BALANCE adds required_pence (and plan_credit_pence when held); the 429 codes add retry_after_seconds (RATE_LIMIT_EXCEEDED also `window`); parameter names the request field (or header) at fault; SANDBOX_VEHICLE_NOT_AVAILABLE adds sandbox_vrm_list; VIN_NOT_SUPPORTED adds vin_endpoints; TOO_MANY_OPEN_REQUESTS adds open_requests_limit.", "properties": { "request_id": { "type": "string" }, "cost_pence": { "type": "integer" }, "balance_pence": { "type": "integer" }, "required_pence": { "type": "integer" }, "plan_credit_pence": { "type": "integer" }, "retry_after_seconds": { "type": "integer" }, "window": { "type": "string", "enum": [ "second", "minute", "day" ] }, "parameter": { "type": "string" }, "sandbox_vrm_list": { "type": "string" }, "vin_endpoints": { "type": "array", "items": { "type": "string" } }, "open_requests_limit": { "type": "integer" } }, "required": [ "request_id" ] }, "type": { "type": "string", "enum": [ "invalid_request", "authentication", "permission", "billing", "limit", "not_found", "not_available", "source_error", "internal" ], "description": "Whose side the failure is on. `invalid_request`: Something in the request needs changing before it can succeed. `authentication`: The API key is missing, not recognised or revoked. `permission`: The key is recognised but this call is not allowed for the account or key. `billing`: The account cannot pay for this call. `limit`: A limit on your key, package or account was reached. It resets on its own. `not_found`: The vehicle or request you named does not exist in the data we use. `not_available`: The vehicle is known, but we hold no data of this kind for it. `source_error`: A data source we use failed or will not answer us for now. You were not charged. `internal`: Something failed on our side. You were not charged." }, "retryable": { "type": "boolean", "description": "true when the same request can succeed later without changes (after the wait in retry_after_seconds for limits)." }, "charged": { "type": "boolean", "description": "Whether this failed request still cost you. Normally false: the price taken up front is refunded before the error is sent." }, "doc_url": { "type": "string", "format": "uri", "description": "This code on the error codes page." }, "legacy_code": { "type": "string", "enum": [ "INVALID_API_KEY", "INVALID_API_KEY_FORMAT", "API_KEY_DISABLED", "ACCOUNT_DISABLED", "EMAIL_NOT_VERIFIED", "MISSING_PARAMETER", "INVALID_VRM", "INVALID_REQUEST", "SANDBOX_VRM_NOT_ALLOWED", "VEHICLE_NOT_FOUND", "REQUEST_EXPIRED", "INSUFFICIENT_BALANCE", "RATE_LIMIT_EXCEEDED", "PACKAGE_LIMIT_EXCEEDED", "ENDPOINT_DAILY_CAP_REACHED", "UPSTREAM_ERROR", "INTERNAL_ERROR" ], "description": "Version 2 answers only, until 2 May 2027: the version 1 code sent for the same case." }, "next_code": { "type": "string", "enum": [ "MISSING_API_KEY", "INVALID_API_KEY", "API_KEY_REVOKED", "ACCOUNT_DISABLED", "EMAIL_NOT_VERIFIED", "SANDBOX_NOT_SUPPORTED", "MISSING_PARAMETER", "INVALID_PARAMETER", "INVALID_VRM", "INVALID_VIN", "VIN_NOT_SUPPORTED", "INVALID_REQUEST_ID", "VEHICLE_NOT_FOUND", "SANDBOX_VEHICLE_NOT_AVAILABLE", "REQUEST_NOT_FOUND", "REQUEST_EXPIRED", "VALUATION_NOT_AVAILABLE", "SPEC_NOT_AVAILABLE", "HISTORY_NOT_AVAILABLE", "MARKET_DATA_NOT_AVAILABLE", "SERVICE_HISTORY_NOT_AVAILABLE", "INSUFFICIENT_BALANCE", "RATE_LIMIT_EXCEEDED", "SANDBOX_DAILY_LIMIT_REACHED", "PACKAGE_LIMIT_EXCEEDED", "ENDPOINT_DAILY_CAP_REACHED", "TOO_MANY_OPEN_REQUESTS", "SOURCE_UNAVAILABLE", "SOURCE_LIMIT_REACHED", "INTERNAL_ERROR" ], "description": "Version 1 answers only: the version 2 code for the same case." } }, "required": [ "code", "message", "details", "type", "retryable", "charged", "doc_url" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "error_codes_version": { "type": "integer", "enum": [ 1, 2 ], "description": "The error code version of this answer (also in the DP-Error-Codes response header)." } }, "required": [ "request_id", "error_codes_version" ], "additionalProperties": false } }, "required": [ "success", "error", "meta" ], "additionalProperties": false, "description": "Every error has this shape." }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_ followed by 24 characters. The same on every retry of this event: use it to ignore duplicates." }, "type": { "type": "string", "enum": [ "balance.low", "balance.topped_up", "key.created", "key.revoked", "plan.changed", "plan.change_scheduled", "subscription.payment_failed", "service_history.completed", "service_history.failed", "limit.daily_cap_reached", "account.email_changed", "api.notice" ] }, "created": { "type": "string", "format": "date-time", "description": "When the event happened." }, "livemode": { "type": "boolean", "description": "false for events caused by sandbox keys and for test events." }, "test": { "type": "boolean", "const": true, "description": "Sent only on test events from the developer portal." }, "data": { "type": "object", "additionalProperties": true, "description": "The event facts. See each event for its fields." } }, "required": [ "id", "type", "created", "livemode", "data" ], "additionalProperties": false, "description": "The JSON body of every webhook event." }, "VehicleDecodeVersion1": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "vrm": { "type": "string", "description": "Registration." }, "make": { "type": "string" }, "model": { "type": "string" }, "model_description": { "type": "string" }, "variant": { "type": "string" }, "series": { "type": "string" }, "year": { "type": "integer", "description": "Year of manufacture." }, "registration_date": { "type": "string", "description": "Date first registered in the UK (else the first date anywhere), as the source writes it (a timestamp at midnight)." }, "date_of_manufacture": { "type": "string", "description": "As the source writes it (a timestamp at midnight)." }, "colour": { "type": "string" }, "fuel_type": { "type": "string" }, "powertrain_type": { "type": "string" }, "transmission": { "type": "string" }, "gears": { "type": "integer" }, "drive_type": { "type": "string" }, "body_type": { "type": "string" }, "wheelplan": { "type": "string" }, "engine_capacity_cc": { "type": "integer" }, "engine_capacity_litres": { "type": "number" }, "engine_number": { "type": "string" }, "vin": { "type": "string" }, "doors": { "type": "integer" }, "seats": { "type": "integer" }, "co2_emissions": { "type": "number", "description": "g/km: the manufacturer figure. The figure on the UK vehicle register is tax.co2_g_per_km and can differ." }, "euro_status": { "type": "string" }, "insurance_group": { "type": [ "string", "number" ], "description": "Version 1 only. Never filled: the source does not hold it." }, "power_bhp": { "type": "number" }, "power_kw": { "type": "number" }, "torque_nm": { "type": "number" }, "top_speed_mph": { "type": "number" }, "acceleration_0_60_mph": { "type": "number", "description": "Seconds." }, "acceleration_0_62_mph": { "type": "number", "description": "Version 1 only. Never filled: see acceleration_0_100_kph (the same test)." }, "fuel_consumption_combined": { "type": "number", "description": "mpg." }, "fuel_consumption_urban": { "type": "number", "description": "mpg." }, "fuel_consumption_extra_urban": { "type": "number", "description": "mpg." }, "gross_weight_kg": { "type": "number" }, "kerb_weight_kg": { "type": "number" }, "mass_in_service_kg": { "type": "number" }, "previous_keepers": { "type": "integer", "description": "Previous keepers: the highest count in the keeper history, and 0 when the record holds a keeper history with no changes. Left out when the record holds no keeper history." }, "colour_changes": { "type": "integer" }, "registration": { "type": "object", "properties": { "first_registered": { "type": "string", "format": "date", "description": "First registered anywhere (for an import, the first date abroad)." }, "first_registered_uk": { "type": "string", "format": "date" }, "used_before_first_registration": { "type": "boolean" }, "cherished_transfer_marker": { "type": "boolean" } }, "additionalProperties": false }, "keeper_history": { "type": "array", "items": { "type": "object", "properties": { "previous_keepers": { "type": "integer", "description": "The number of previous keepers at this change." }, "keeper_start_date": { "type": "string", "format": "date" }, "previous_keeper_disposal_date": { "type": "string", "format": "date" } }, "additionalProperties": false }, "description": "One row per keeper change, latest first. An empty list is a real answer." }, "v5c_issue_dates": { "type": "array", "items": { "type": "string", "format": "date" }, "description": "The date each registration document (V5C) was issued." }, "plate_changes": { "type": "array", "items": { "type": "object", "properties": { "previous_vrm": { "type": "string" }, "current_vrm": { "type": "string" }, "date_of_transaction": { "type": "string", "format": "date" }, "date_of_receipt": { "type": "string", "format": "date" }, "transfer_type": { "type": "string" } }, "additionalProperties": false }, "description": "An empty list is a real answer: the record holds no plate changes." }, "colour_history": { "type": "object", "properties": { "current": { "type": "string" }, "original": { "type": "string" }, "previous": { "type": "string" }, "changes": { "type": "integer" }, "last_change_date": { "type": "string", "format": "date" } }, "additionalProperties": false }, "import_export": { "type": "object", "properties": { "is_imported": { "type": "boolean" }, "imported_from_ni": { "type": "boolean" }, "imported_from_outside_eu": { "type": "boolean" }, "import_date": { "type": "string", "format": "date", "description": "Version 1 only. Never filled by the source, even for imports." }, "is_exported": { "type": "boolean" }, "export_date": { "type": "string", "format": "date" } }, "additionalProperties": false }, "scrapped": { "type": "object", "properties": { "is_scrapped": { "type": "boolean" }, "is_unscrapped": { "type": "boolean" }, "scrap_date": { "type": "string", "format": "date" }, "certificate_of_destruction": { "type": "boolean" } }, "additionalProperties": false }, "tax": { "type": "object", "properties": { "co2_g_per_km": { "type": "number", "description": "The figure on the UK vehicle register." }, "co2_band": { "type": "string" }, "tax_band": { "type": "string" }, "first_year_six_months_gbp": { "type": "number", "description": "Version 1 only. Never filled: there is no six month first-year rate." }, "first_year_twelve_months_gbp": { "type": "number", "description": "The first-year rate for the vehicle's band. Filled for vehicles long past their first year too: it is the band's rate, not proof the vehicle paid it." }, "standard_six_months_gbp": { "type": "number" }, "standard_twelve_months_gbp": { "type": "number" }, "premium_vehicle_six_months_gbp": { "type": "number", "description": "The rate a vehicle in this band pays IF it cost over £40,000 new. Filled for every vehicle registered from April 2017: it is not proof the vehicle pays it." }, "premium_vehicle_twelve_months_gbp": { "type": "number", "description": "As premium_vehicle_six_months_gbp." } }, "additionalProperties": false, "description": "Vehicle excise duty as registered. Rates are in pounds." }, "dvla": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "body_type": { "type": "string" }, "fuel_type": { "type": "string" }, "wheelplan": { "type": "string" }, "engine_capacity_cc": { "type": "integer" }, "power_kw": { "type": "number" }, "seats": { "type": "integer" }, "gross_weight_kg": { "type": "number" }, "mass_in_service_kg": { "type": "number" }, "power_to_weight_ratio": { "type": "number" }, "max_braked_trailer_mass_kg": { "type": "number" }, "max_unbraked_trailer_mass_kg": { "type": "number" } }, "additionalProperties": false, "description": "The values exactly as held on the UK vehicle register. The top-level fields prefer manufacturer model data when it is held, so make, model, body_type, power_kw and seats can be written differently here." }, "power_ps": { "type": "number", "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "torque_lb_ft": { "type": "number" }, "top_speed_kph": { "type": "number" }, "acceleration_0_100_kph": { "type": "number", "description": "Seconds (0 to 100 km/h, the same test as 0 to 62 mph)." }, "fuel_consumption_combined_l_100km": { "type": "number" }, "fuel_consumption_urban_l_100km": { "type": "number" }, "fuel_consumption_extra_urban_l_100km": { "type": "number" }, "country_of_origin": { "type": "string" }, "model_introduction_date": { "type": "string", "format": "date", "description": "When this model was introduced." }, "model_start_date": { "type": "string", "format": "date", "description": "First build date of this model version." }, "model_end_date": { "type": "string", "format": "date", "description": "Last build date of this model version (left out while it is still built)." }, "classification": { "type": "object", "properties": { "type_approval_category": { "type": "string", "description": "For example M1 (car) or N1 (light goods vehicle)." }, "vehicle_class": { "type": "string" }, "taxation_class": { "type": "string" }, "market_sector_code": { "type": "string" } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "engine": { "type": "object", "properties": { "code": { "type": "string", "description": "The manufacturer engine code." }, "manufacturer": { "type": "string" }, "cylinders": { "type": "integer" }, "cylinder_arrangement": { "type": "string" }, "aspiration": { "type": "string" }, "valves_per_cylinder": { "type": "integer" }, "valve_gear": { "type": "string" }, "bore_mm": { "type": "number" }, "stroke_mm": { "type": "number" }, "fuel_delivery": { "type": "string" }, "location": { "type": "string" } }, "additionalProperties": false, "description": "Combustion engine details. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "dimensions": { "type": "object", "properties": { "length_mm": { "type": "number" }, "width_mm": { "type": "number" }, "height_mm": { "type": "number" }, "wheelbase_mm": { "type": "number" }, "load_length_mm": { "type": "number", "description": "Vans." } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "weights": { "type": "object", "properties": { "gross_combined_weight_kg": { "type": "number" }, "gross_train_weight_kg": { "type": "number" }, "payload_kg": { "type": "number" }, "unladen_weight_kg": { "type": "number" } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "body": { "type": "object", "properties": { "body_shape": { "type": "string" }, "cab_type": { "type": "string", "description": "Vans and pick-ups." }, "wheelbase_type": { "type": "string" }, "axles": { "type": "integer" }, "fuel_tank_capacity_litres": { "type": "number" }, "load_volume_litres": { "type": "number", "description": "Load space of a van." }, "platform_name": { "type": "string" }, "platform_shared_across_models": { "type": "boolean" } }, "additionalProperties": false, "description": "From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "safety": { "type": "object", "properties": { "ncap_star_rating": { "type": "number" }, "ncap_adult_percent": { "type": "number" }, "ncap_child_percent": { "type": "number" }, "ncap_pedestrian_percent": { "type": "number" }, "ncap_safety_assist_percent": { "type": "number" } }, "additionalProperties": false, "description": "Euro NCAP ratings. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "warranty": { "type": "object", "properties": { "manufacturer_warranty_months": { "type": "integer" }, "manufacturer_warranty_miles": { "type": "integer" } }, "additionalProperties": false, "description": "The manufacturer's new-vehicle warranty. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "supports_over_the_air_updates": { "type": "boolean" }, "drag_coefficient": { "type": "number" }, "ev": { "type": "object", "properties": { "powertrain_type": { "type": "string", "description": "For example BEV or PHEV." }, "batteries": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "total_capacity_kwh": { "type": "number" }, "usable_capacity_kwh": { "type": "number" }, "chemistry": { "type": "string" }, "voltage": { "type": "number" }, "location": { "type": "string" }, "warranty_months": { "type": "integer" }, "warranty_miles": { "type": "integer" } }, "additionalProperties": false } }, "range_tests": { "type": "array", "items": { "type": "object", "properties": { "test_type": { "type": "string", "description": "For example WLTP." }, "combined_range_miles": { "type": "number" }, "combined_range_km": { "type": "number" }, "city_range_miles": { "type": "number" }, "city_range_km": { "type": "number" } }, "additionalProperties": false } }, "real_range_miles": { "type": "number", "description": "Expected real-world range." }, "real_range_km": { "type": "number" }, "zero_emission_miles": { "type": "number", "description": "Electric-only range (plug-in hybrids)." }, "miles_per_charge_hour": { "type": "number" }, "wh_per_mile": { "type": "number" }, "max_charge_input_kw": { "type": "number" }, "number_of_charge_ports": { "type": "integer" }, "charge_ports": { "type": "array", "items": { "type": "object", "properties": { "port_type": { "type": "string" }, "location": { "type": "string" }, "max_charge_kw": { "type": "number" }, "is_standard": { "type": "boolean" }, "charge_times_10_to_80_percent": { "type": "array", "items": { "type": "object", "properties": { "charger_kw": { "type": "number" }, "minutes": { "type": "number" } }, "additionalProperties": false }, "description": "Average time to charge from 10% to 80% on a charger of this power." } }, "additionalProperties": false } }, "motors": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "location": { "type": "string" }, "axle_driven": { "type": "string" }, "power_kw": { "type": "number" }, "max_torque_nm": { "type": "number" }, "max_power_rpm": { "type": "number" }, "manufacturer": { "type": "string" }, "model": { "type": "string" }, "regenerative_braking": { "type": "boolean" } }, "additionalProperties": false } }, "tesla_supercharger_compatible": { "type": "boolean" } }, "additionalProperties": false, "description": "Electric and plug-in hybrid vehicles only. From the manufacturer model data: left out when it is not held for this vehicle (meta.model_data_held is then false)." }, "raw": { "type": "object", "additionalProperties": true, "description": "The source record as received, with supplier bookkeeping removed. Its layout can change without notice: rely on the documented fields instead." } }, "required": [ "vrm" ], "additionalProperties": false, "description": "The vehicle. Fields and groups not held for this vehicle are omitted." } }, "required": [ "vehicle" ], "additionalProperties": false }, "VehicleSpecVersion1": { "type": "object", "properties": { "specification": { "type": "object", "properties": { "vrm": { "type": "string", "description": "Registration (or the VIN when the request was made by VIN)." }, "vehicle": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string", "description": "Live: the full model description. Version 1 sandbox: the model range." }, "model_description": { "type": "string" }, "variant": { "type": "string", "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "series": { "type": "string", "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "year": { "type": "string", "description": "Year of manufacture, as text (version 2: a number)." }, "body_type": { "type": "string", "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "powertrain_type": { "type": "string", "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." } }, "additionalProperties": false }, "engine": { "type": "object", "properties": { "fuel_type": { "type": "string" }, "capacity_cc": { "type": "integer" }, "capacity_litres": { "type": "number" }, "cylinders": { "type": "integer" }, "cylinder_arrangement": { "type": "string" }, "aspiration": { "type": "string" }, "valves_per_cylinder": { "type": "integer" }, "valve_gear": { "type": "string" }, "engine_location": { "type": "string" } }, "additionalProperties": false, "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "performance": { "type": "object", "properties": { "power_bhp": { "type": "number" }, "power_kw": { "type": "number" }, "power_ps": { "type": "number" }, "power_rpm": { "type": "number" }, "torque_nm": { "type": "number" }, "torque_lb_ft": { "type": "number" }, "torque_rpm": { "type": "number" }, "top_speed_mph": { "type": "number" }, "top_speed_kph": { "type": "number" }, "acceleration_0_60_mph": { "type": "number" }, "acceleration_0_100_kph": { "type": "number" }, "acceleration_0_62_mph": { "type": "number", "description": "Never filled." } }, "additionalProperties": false, "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "transmission": { "type": "object", "properties": { "type": { "type": "string" }, "gears": { "type": "integer" }, "drivetrain": { "type": "string" }, "driving_axle": { "type": "string" } }, "additionalProperties": false, "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "dimensions": { "type": "object", "properties": { "length_mm": { "type": "number" }, "width_mm": { "type": "number" }, "height_mm": { "type": "number" }, "wheelbase_mm": { "type": "number" }, "kerb_weight_kg": { "type": "number" }, "gross_weight_kg": { "type": "number" }, "payload_kg": { "type": "number" }, "boot_capacity_litres": { "type": "number", "description": "The load space of a van, not a car boot." }, "fuel_tank_capacity_litres": { "type": "number" } }, "additionalProperties": false, "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "economy": { "type": "object", "properties": { "combined_mpg": { "type": "number" }, "urban_mpg": { "type": "number" }, "extra_urban_mpg": { "type": "number" }, "combined_l_100km": { "type": "number" }, "co2_emissions": { "type": "number" }, "euro_status": { "type": "string" } }, "additionalProperties": false, "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "practicality": { "type": "object", "properties": { "doors": { "type": "integer" }, "seats": { "type": "integer" }, "axles": { "type": "integer" }, "airbags": { "type": "integer", "description": "Never filled." } }, "additionalProperties": false, "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "safety": { "type": "object", "properties": { "ncap_star_rating": { "type": "number" }, "ncap_adult_percent": { "type": "number" }, "ncap_child_percent": { "type": "number" }, "ncap_pedestrian_percent": { "type": "number" }, "ncap_safety_assist_percent": { "type": "number" } }, "additionalProperties": false, "description": "Version 1 only. Empty on live answers: the specification source does not send it (use /v1/vehicle/decode). Version 1 sandbox answers fill it from test data." }, "insurance": { "type": "object", "properties": { "group": { "type": [ "string", "number" ] }, "security": { "type": "string" } }, "additionalProperties": false, "description": "Version 1 only. Never filled, live or sandbox." }, "factory_equipment": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of items." }, "items": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "fitment": { "type": "string", "description": "Standard, Option or Free." }, "type": { "type": "string" }, "price": { "type": [ "string", "number" ], "description": "Pounds. On options only; can be negative (a credit option)." }, "contents": { "type": "array", "items": { "type": "string" }, "description": "What an option pack contains, one line per item." } }, "additionalProperties": false } } }, "required": [ "count", "items" ], "additionalProperties": false, "description": "Equipment fitted at the factory for this model." }, "raw": { "type": "object", "additionalProperties": true, "description": "The source record as received, with supplier bookkeeping removed. Its layout can change without notice: rely on the documented fields instead." } }, "required": [ "vrm" ], "additionalProperties": false, "description": "The specification (version 1 shape). Groups are always present; fields not held are omitted, so a group can be empty." } }, "required": [ "specification" ], "additionalProperties": false }, "VehicleValuationVersion1": { "type": "object", "properties": { "valuation": { "type": "object", "properties": { "vrm": { "type": "string", "description": "Registration (or the VIN when the request was made by VIN)." }, "mileage_used": { "type": "integer", "description": "The mileage the figures were produced at, as the source reports it (your mileage only when it reports none)." }, "currency": { "type": "string", "const": "GBP" }, "valuations": { "type": "object", "properties": { "retail": { "type": "number" }, "trade": { "type": "number" }, "private": { "type": "number" }, "part_exchange": { "type": "number" }, "auction": { "type": "number" } }, "additionalProperties": false, "description": "Headline figures in pounds." }, "figures": { "type": "object", "properties": { "on_the_road": { "type": "number", "description": "The price when new, not today's value." }, "dealer_forecourt": { "type": "number" }, "trade_retail": { "type": "number" }, "trade_average": { "type": "number" }, "trade_poor": { "type": "number" }, "private_clean": { "type": "number" }, "private_average": { "type": "number" }, "part_exchange": { "type": "number" }, "auction": { "type": "number" } }, "additionalProperties": false, "description": "Every figure held, in pounds." }, "condition_adjustments": { "description": "Version 1 only. Never filled: the source does not send it." }, "mileage_adjustment": { "description": "Version 1 only. Never filled: the source does not send it." }, "valuation_date": { "type": "string", "description": "When the valuation was produced, as the source writes it (a timestamp)." }, "valued_at": { "type": "string", "format": "date-time", "description": "The exact time the valuation was produced." }, "valuation_book": { "type": "string", "description": "The source's own label for the valuation set it used (for example \"Direct\"). For reference only." }, "vehicle_summary": { "type": "object", "properties": { "description": { "type": "string" }, "make": { "type": "string", "description": "Never filled." }, "model": { "type": "string", "description": "Never filled." }, "variant": { "type": "string", "description": "Never filled." }, "year": { "type": "integer", "description": "Never filled." }, "first_registered": { "type": "string", "description": "As the source writes it (a timestamp at midnight)." }, "fuel_type": { "type": "string", "description": "Never filled." }, "transmission": { "type": "string", "description": "Never filled." } }, "additionalProperties": false }, "raw": { "type": "object", "additionalProperties": true, "description": "The source record as received, with supplier bookkeeping removed. Its layout can change without notice: rely on the documented fields instead." } }, "required": [ "vrm", "currency" ], "additionalProperties": false, "description": "The valuation. Fields not held are omitted." } }, "required": [ "valuation" ], "additionalProperties": false }, "VehicleProvenanceVersion1": { "type": "object", "properties": { "provenance": { "type": "object", "properties": { "vrm": { "type": [ "string", "null" ] }, "check_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When this check ran." }, "vehicle": { "type": [ "object", "null" ], "properties": { "make": { "type": [ "string", "null" ], "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "model": { "type": [ "string", "null" ], "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "variant": { "type": [ "string", "null" ], "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "year": { "type": [ "integer", "null" ], "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "colour": { "type": [ "string", "null" ], "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "vin": { "type": [ "string", "null" ] } }, "required": [ "make", "model", "variant", "year", "colour", "vin" ], "additionalProperties": false }, "registration": { "type": [ "object", "null" ], "properties": { "first_registered_uk": { "type": [ "string", "null" ] }, "first_registered": { "type": [ "string", "null" ] }, "registration_changes": { "type": [ "integer", "null" ] } }, "required": [ "first_registered_uk", "first_registered", "registration_changes" ], "additionalProperties": false, "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "ownership": { "type": [ "object", "null" ], "properties": { "keeper_changes": { "type": [ "integer", "null" ] }, "keeper_history": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "previous_keepers": { "type": "integer", "description": "The number of previous keepers at this change." }, "keeper_start_date": { "type": "string", "format": "date" }, "previous_keeper_disposal_date": { "type": "string", "format": "date" } }, "additionalProperties": false } }, "last_keeper_change": { "type": [ "string", "null" ] } }, "required": [ "keeper_changes", "keeper_history", "last_keeper_change" ], "additionalProperties": false, "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "finance": { "type": [ "object", "null" ], "properties": { "has_outstanding_finance": { "type": [ "boolean", "null" ], "description": "true: finance recorded. false: the finance register was checked and holds none. null: not held for this check." }, "finance_records": { "type": [ "integer", "null" ] }, "finance_details": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "agreement_date": { "type": "string", "description": "As the source writes it (a date and midnight time, no time zone)." }, "agreement_type": { "type": "string" }, "agreement_number": { "type": "string" }, "agreement_term_months": { "type": [ "string", "number" ] }, "finance_company": { "type": "string" }, "contact_number": { "type": "string", "description": "The finance company's phone number." }, "vehicle_description": { "type": "string" }, "is_stock_funding": { "type": "boolean", "description": "true for a UNIT STOCKING agreement: a dealer's stock funding, not a keeper's finance agreement." } }, "additionalProperties": false } } }, "required": [ "has_outstanding_finance", "finance_records", "finance_details" ], "additionalProperties": false }, "stolen": { "type": [ "object", "null" ], "properties": { "is_stolen": { "type": [ "boolean", "null" ], "description": "true when at least one source holds a stolen marker (the police record or an insurer theft record); false only when both were checked and are clear. Read police_marked_stolen and insurer_theft_recorded to see which: an insurer theft record can be for a vehicle that was later recovered." }, "police_marked_stolen": { "type": [ "boolean", "null" ], "description": "The police record on its own: true when it marks the vehicle as stolen. null when it could not be checked." }, "insurer_theft_recorded": { "type": [ "boolean", "null" ], "description": "The insurer register on its own: true when it holds a theft record. null when it could not be checked." }, "police_recorded": { "type": [ "boolean", "null" ], "description": "Version 1 only: the same as police_marked_stolen." }, "stolen_date": { "type": [ "string", "null" ], "description": "Version 1 only: the police stolen date, else the first insurer theft loss date. Use police.date_reported_stolen and insurer_theft_records instead." }, "police_force": { "type": [ "string", "null" ], "description": "Version 1 only: also police.police_force." }, "record_status": { "type": [ "string", "null" ], "description": "Version 1 only: also police.record_status." }, "record_added_date": { "type": [ "string", "null" ], "description": "Version 1 only: also police.record_added_at." }, "police": { "type": [ "object", "null" ], "properties": { "marked_stolen": { "type": [ "boolean", "null" ], "description": "true: the police record marks the vehicle as stolen." }, "date_reported_stolen": { "type": [ "string", "null" ], "format": "date" }, "police_force": { "type": [ "string", "null" ] }, "record_status": { "type": [ "string", "null" ], "description": "The current status on the police record." }, "record_added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the police record was created." }, "vrm": { "type": [ "string", "null" ], "description": "The registration on the police record." }, "vin": { "type": [ "string", "null" ], "description": "The VIN on the police record." } }, "required": [ "marked_stolen", "date_reported_stolen", "police_force", "record_status", "record_added_at", "vrm", "vin" ], "additionalProperties": false, "description": "The police record in full. null when the police record could not be checked." }, "insurer_theft_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Write-off category (A, B, S, N, or the older C and D) or the theft category." }, "status": { "type": "string", "description": "The register's description, for example \"CAT S STRUCTURAL DAMAGE\"." }, "loss_date": { "type": "string", "description": "Date of the loss. As the source writes it (a timestamp at midnight UTC on the UK day)." }, "entry_date": { "type": "string", "description": "When the record was added to the insurers' register. As the source writes it (a timestamp at midnight UTC on the UK day)." }, "insurer": { "type": "string" }, "insurer_branch": { "type": "string" }, "insurer_code": { "type": "string" }, "claim_number": { "type": "string" }, "contact_number": { "type": "string", "description": "The insurer's phone number." }, "theft_indicator": { "type": [ "string", "number" ], "description": "The register's own theft marker code, as received. Use theft_indicator_literal to read it." }, "theft_indicator_literal": { "type": "string", "description": "\"STOLEN\" or \"NOT STOLEN\"." }, "loss_type": { "type": "string", "description": "The register's loss type code, as received (\"0\" on every record seen so far)." }, "removed_date": { "type": "string", "description": "When the record was taken off the register, if it was. As the source writes it (a timestamp at midnight UTC on the UK day)." } }, "additionalProperties": false, "description": "One insurer register record with every field the register gives. Fields the register leaves empty are omitted." }, "description": "Every insurer register theft record, with all its fields." } }, "required": [ "is_stolen", "police_marked_stolen", "insurer_theft_recorded", "police_recorded", "stolen_date", "police_force", "record_status", "record_added_date", "police", "insurer_theft_records" ], "additionalProperties": false }, "write_off": { "type": [ "object", "null" ], "properties": { "is_write_off": { "type": [ "boolean", "null" ] }, "category": { "type": [ "string", "null" ], "description": "The category of the most recent write-off record (latest loss date, else latest entry date). Every record is in write_off_records; every category held is in categories." }, "date": { "type": [ "string", "null" ], "description": "Loss date of the most recent record (its entry date when it has no loss date), as the source writes it." }, "categories": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Every write-off category held, each once, from the newest record." }, "write_off_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Write-off category (A, B, S, N, or the older C and D) or the theft category." }, "status": { "type": "string", "description": "The register's description, for example \"CAT S STRUCTURAL DAMAGE\"." }, "loss_date": { "type": "string", "description": "Date of the loss. As the source writes it (a timestamp at midnight UTC on the UK day)." }, "entry_date": { "type": "string", "description": "When the record was added to the insurers' register. As the source writes it (a timestamp at midnight UTC on the UK day)." }, "insurer": { "type": "string" }, "insurer_branch": { "type": "string" }, "insurer_code": { "type": "string" }, "claim_number": { "type": "string" }, "contact_number": { "type": "string", "description": "The insurer's phone number." }, "theft_indicator": { "type": [ "string", "number" ], "description": "The register's own theft marker code, as received. Use theft_indicator_literal to read it." }, "theft_indicator_literal": { "type": "string", "description": "\"STOLEN\" or \"NOT STOLEN\"." }, "loss_type": { "type": "string", "description": "The register's loss type code, as received (\"0\" on every record seen so far)." }, "removed_date": { "type": "string", "description": "When the record was taken off the register, if it was. As the source writes it (a timestamp at midnight UTC on the UK day)." } }, "additionalProperties": false, "description": "One insurer register record with every field the register gives. Fields the register leaves empty are omitted." }, "description": "Every write-off record, newest first, with all its fields." } }, "required": [ "is_write_off", "category", "date", "categories", "write_off_records" ], "additionalProperties": false }, "mileage": { "type": [ "object", "null" ], "properties": { "current_mileage": { "type": [ "integer", "null" ] }, "mileage_date": { "type": [ "string", "null" ] }, "mileage_anomaly": { "type": [ "boolean", "null" ] }, "mileage_history": { "type": [ "array", "null" ], "items": { "type": "object" } } }, "required": [ "current_mileage", "mileage_date", "mileage_anomaly", "mileage_history" ], "additionalProperties": false, "description": "Version 1 only. Always null: MOT mileage readings come from /v1/vehicle/tax-mot." }, "plate_changes": { "type": [ "object", "null" ], "properties": { "has_plate_changes": { "type": [ "boolean", "null" ] }, "change_count": { "type": [ "integer", "null" ] }, "changes": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } } }, "required": [ "has_plate_changes", "change_count", "changes" ], "additionalProperties": false, "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "colour": { "type": [ "object", "null" ], "properties": { "current": { "type": [ "string", "null" ] }, "original": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] }, "changes": { "type": [ "integer", "null" ] }, "last_change_date": { "type": [ "string", "null" ] } }, "required": [ "current", "original", "previous", "changes", "last_change_date" ], "additionalProperties": false, "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "import_export": { "type": [ "object", "null" ], "properties": { "is_imported": { "type": [ "boolean", "null" ] }, "import_date": { "type": [ "string", "null" ] }, "imported_from_ni": { "type": [ "boolean", "null" ] }, "is_exported": { "type": [ "boolean", "null" ] }, "export_date": { "type": [ "string", "null" ] } }, "required": [ "is_imported", "import_date", "imported_from_ni", "is_exported", "export_date" ], "additionalProperties": false, "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "scrapped": { "type": [ "object", "null" ], "properties": { "is_scrapped": { "type": [ "boolean", "null" ] }, "scrap_date": { "type": [ "string", "null" ] }, "certificate_of_destruction": { "type": [ "boolean", "null" ] } }, "required": [ "is_scrapped", "scrap_date", "certificate_of_destruction" ], "additionalProperties": false, "description": "Version 1 only. Always null on this check: use /v1/vehicle/decode." }, "alerts": { "type": [ "object", "null" ], "properties": { "has_alerts": { "type": [ "boolean", "null" ], "description": "true when any alert below is known; false only when finance, stolen and write-off were all checked and are clear; otherwise null." }, "alert_count": { "type": [ "integer", "null" ] }, "alert_list": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Plain-language alerts. Stolen alerts name their source: \"Police record: marked as stolen\", \"Insurer register: theft record\". Match on the fields above, not on this text." } }, "required": [ "has_alerts", "alert_count", "alert_list" ], "additionalProperties": false }, "raw": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The police, insurer, finance and vehicle code records as received, with supplier bookkeeping removed. Nulls inside are removed. Layout can change without notice." } }, "required": [ "vrm", "check_date", "vehicle", "registration", "ownership", "finance", "stolen", "write_off", "mileage", "plate_changes", "colour", "import_export", "scrapped", "alerts", "raw" ], "additionalProperties": false, "description": "Provenance (version 1 shape) keeps every field: null means \"not held for this check\", never \"no\". false or 0 is a real answer. Rows inside lists omit null fields as elsewhere." } }, "required": [ "provenance" ], "additionalProperties": false } }, "responses": { "BadRequest": { "description": "The request needs changing before it can succeed. Not charged. Codes (version 2): MISSING_PARAMETER (A required field is missing. details.parameter names it.); INVALID_PARAMETER (A field has a value we cannot use, for example a callback_url that is not https. details.parameter names it when known.); INVALID_VRM (The registration is not 2 to 8 letters and digits, or the vehicle register refuses it as a registration that cannot exist.); INVALID_VIN (The VIN is not 5 to 17 letters and digits without I, O or Q, or it was refused as a VIN that cannot exist. Service history needs all 17 characters.); VIN_NOT_SUPPORTED (This endpoint looks vehicles up by registration only. details.vin_endpoints lists the endpoints that take a VIN.); INVALID_REQUEST_ID (The service history request id in the URL is not a valid id.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "MISSING_PARAMETER", "message": "A required field is missing. details.parameter names it.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "invalid_request", "retryable": false, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#MISSING_PARAMETER" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "Unauthorized": { "description": "The API key is missing, not recognised or revoked. Codes (version 2): MISSING_API_KEY (The request carried no API key.); INVALID_API_KEY (The key is not one of ours, or is not in the right format (dp_live_ or dp_sandbox_ followed by 48 characters).); API_KEY_REVOKED (This key was revoked and no longer works.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "MISSING_API_KEY", "message": "The request carried no API key.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "authentication", "retryable": false, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#MISSING_API_KEY", "legacy_code": "INVALID_API_KEY" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "PaymentRequired": { "description": "The balance (plus any plan credit) does not cover the price. Top up and retry. Codes (version 2): INSUFFICIENT_BALANCE (Your balance plus any plan credit is below the price of this call. details.required_pence and details.balance_pence give the figures.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your balance plus any plan credit is below the price of this call. details.required_pence and details.balance_pence give the figures.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "billing", "retryable": false, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INSUFFICIENT_BALANCE" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "Forbidden": { "description": "The key is recognised but this call is not allowed for the account or key. Codes (version 2): ACCOUNT_DISABLED (The developer account this key belongs to is disabled, so none of its keys work.); EMAIL_NOT_VERIFIED (Live keys work only once the account email address is verified. Sandbox keys work without it.); SANDBOX_NOT_SUPPORTED (This endpoint has no sandbox data, so sandbox keys cannot call it.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "ACCOUNT_DISABLED", "message": "The developer account this key belongs to is disabled, so none of its keys work.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "permission", "retryable": false, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#ACCOUNT_DISABLED", "legacy_code": "API_KEY_DISABLED" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "NotFound": { "description": "No such vehicle or request, or a known vehicle with no data of this kind. Not charged. Codes (version 2): VEHICLE_NOT_FOUND (No source we use knows this registration or VIN.); SANDBOX_VEHICLE_NOT_AVAILABLE (Sandbox keys answer only for the published test vehicles.); REQUEST_NOT_FOUND (There is no service history request with this id on your account.); VALUATION_NOT_AVAILABLE (The vehicle is known, but we hold no valuation for it.); SPEC_NOT_AVAILABLE (The vehicle is known, but we hold no factory specification for it.); HISTORY_NOT_AVAILABLE (The vehicle is known, but the history checks could not be answered for it.); MARKET_DATA_NOT_AVAILABLE (The vehicle is known, but we cannot match it to a model on the market, so there is nothing to compare it with.); SERVICE_HISTORY_NOT_AVAILABLE (The manufacturer service network does not recognise this vehicle, or the make is not covered.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "VEHICLE_NOT_FOUND", "message": "No source we use knows this registration or VIN.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "not_found", "retryable": false, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#VEHICLE_NOT_FOUND" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "Gone": { "description": "A service history request finished more than 7 days ago and can no longer be read. Codes (version 2): REQUEST_EXPIRED (The service history request finished more than 7 days ago and can no longer be read.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "REQUEST_EXPIRED", "message": "The service history request finished more than 7 days ago and can no longer be read.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "not_found", "retryable": false, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#REQUEST_EXPIRED" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "TooManyRequests": { "description": "A limit was reached. Wait for Retry-After seconds. Never charged. Codes (version 2): RATE_LIMIT_EXCEEDED (Too many calls on this key. details.window says which limit: second, minute or day. Retryable.); SANDBOX_DAILY_LIMIT_REACHED (The account has used its 1,000 sandbox calls for the day, across all its sandbox keys. Retryable.); PACKAGE_LIMIT_EXCEEDED (Your package limit across all live keys on the account was reached. Retryable.); ENDPOINT_DAILY_CAP_REACHED (Your package's daily cap for this endpoint was reached. Retryable.); TOO_MANY_OPEN_REQUESTS (The account already has the most service history requests in progress at once (25). Retryable.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many calls on this key. details.window says which limit: second, minute or day.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "limit", "retryable": true, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#RATE_LIMIT_EXCEEDED" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "ServerError": { "description": "Something failed on our side. Not charged. Safe to retry; quote the request id if it persists. Codes (version 2): INTERNAL_ERROR (Something failed on our side, for example reading your balance. You were not charged. Retryable.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something failed on our side, for example reading your balance. You were not charged.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "internal", "retryable": true, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INTERNAL_ERROR" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "BadGateway": { "description": "A data source failed or did not answer in time, after our automatic retries. Not charged. Safe to retry. Codes (version 2): SOURCE_UNAVAILABLE (A data source we use failed or did not answer in time. You were not charged. Retryable.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "SOURCE_UNAVAILABLE", "message": "A data source we use failed or did not answer in time. You were not charged.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "source_error", "retryable": true, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SOURCE_UNAVAILABLE", "legacy_code": "UPSTREAM_ERROR" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } }, "ServiceUnavailable": { "description": "A data source will not answer us again until its daily reset. Not charged. Retry later. Codes (version 2): SOURCE_LIMIT_REACHED (A data source will not answer us again until its daily reset. This is our capacity, not yours, and you were not charged. Retryable.).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "DP-Error-Codes": { "$ref": "#/components/headers/DP-Error-Codes" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "SOURCE_LIMIT_REACHED", "message": "A data source will not answer us again until its daily reset. This is our capacity, not yours, and you were not charged.", "details": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01" }, "type": "source_error", "retryable": true, "charged": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SOURCE_LIMIT_REACHED", "legacy_code": "UPSTREAM_ERROR" }, "meta": { "request_id": "req_3f9a1c0d2b7e4a5f6c8d9e01", "error_codes_version": 2 } } } } } } }, "x-error-codes": [ { "code": "MISSING_API_KEY", "http": 401, "type": "authentication", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#MISSING_API_KEY", "replaces": [ { "code": "INVALID_API_KEY", "http": 401 } ] }, { "code": "INVALID_API_KEY", "http": 401, "type": "authentication", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INVALID_API_KEY", "replaces": [ { "code": "INVALID_API_KEY", "http": 401 }, { "code": "INVALID_API_KEY_FORMAT", "http": 401 } ] }, { "code": "API_KEY_REVOKED", "http": 401, "type": "authentication", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#API_KEY_REVOKED", "replaces": [ { "code": "API_KEY_DISABLED", "http": 401 } ] }, { "code": "ACCOUNT_DISABLED", "http": 403, "type": "permission", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#ACCOUNT_DISABLED", "replaces": [ { "code": "API_KEY_DISABLED", "http": 401 } ] }, { "code": "EMAIL_NOT_VERIFIED", "http": 403, "type": "permission", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#EMAIL_NOT_VERIFIED", "replaces": [ { "code": "EMAIL_NOT_VERIFIED", "http": 401 } ] }, { "code": "SANDBOX_NOT_SUPPORTED", "http": 403, "type": "permission", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SANDBOX_NOT_SUPPORTED", "replaces": [] }, { "code": "MISSING_PARAMETER", "http": 400, "type": "invalid_request", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#MISSING_PARAMETER", "replaces": [ { "code": "MISSING_PARAMETER", "http": 400 } ] }, { "code": "INVALID_PARAMETER", "http": 400, "type": "invalid_request", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INVALID_PARAMETER", "replaces": [ { "code": "INVALID_REQUEST", "http": 400 } ] }, { "code": "INVALID_VRM", "http": 400, "type": "invalid_request", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INVALID_VRM", "replaces": [ { "code": "INVALID_VRM", "http": 400 }, { "code": "INVALID_REQUEST", "http": 400 }, { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "INVALID_VIN", "http": 400, "type": "invalid_request", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INVALID_VIN", "replaces": [ { "code": "INVALID_REQUEST", "http": 400 } ] }, { "code": "VIN_NOT_SUPPORTED", "http": 400, "type": "invalid_request", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#VIN_NOT_SUPPORTED", "replaces": [ { "code": "INVALID_REQUEST", "http": 400 } ] }, { "code": "INVALID_REQUEST_ID", "http": 400, "type": "invalid_request", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INVALID_REQUEST_ID", "replaces": [ { "code": "INVALID_REQUEST", "http": 400 } ] }, { "code": "VEHICLE_NOT_FOUND", "http": 404, "type": "not_found", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#VEHICLE_NOT_FOUND", "replaces": [ { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "SANDBOX_VEHICLE_NOT_AVAILABLE", "http": 404, "type": "not_found", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SANDBOX_VEHICLE_NOT_AVAILABLE", "replaces": [ { "code": "SANDBOX_VRM_NOT_ALLOWED", "http": 404 } ] }, { "code": "REQUEST_NOT_FOUND", "http": 404, "type": "not_found", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#REQUEST_NOT_FOUND", "replaces": [ { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "REQUEST_EXPIRED", "http": 410, "type": "not_found", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#REQUEST_EXPIRED", "replaces": [ { "code": "REQUEST_EXPIRED", "http": 410 } ] }, { "code": "VALUATION_NOT_AVAILABLE", "http": 404, "type": "not_available", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#VALUATION_NOT_AVAILABLE", "replaces": [ { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "SPEC_NOT_AVAILABLE", "http": 404, "type": "not_available", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SPEC_NOT_AVAILABLE", "replaces": [ { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "HISTORY_NOT_AVAILABLE", "http": 404, "type": "not_available", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#HISTORY_NOT_AVAILABLE", "replaces": [ { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "MARKET_DATA_NOT_AVAILABLE", "http": 404, "type": "not_available", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#MARKET_DATA_NOT_AVAILABLE", "replaces": [ { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "SERVICE_HISTORY_NOT_AVAILABLE", "http": 404, "type": "not_available", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SERVICE_HISTORY_NOT_AVAILABLE", "replaces": [ { "code": "VEHICLE_NOT_FOUND", "http": 404 } ] }, { "code": "INSUFFICIENT_BALANCE", "http": 402, "type": "billing", "retryable": false, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INSUFFICIENT_BALANCE", "replaces": [ { "code": "INSUFFICIENT_BALANCE", "http": 402 } ] }, { "code": "RATE_LIMIT_EXCEEDED", "http": 429, "type": "limit", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#RATE_LIMIT_EXCEEDED", "replaces": [ { "code": "RATE_LIMIT_EXCEEDED", "http": 429 } ] }, { "code": "SANDBOX_DAILY_LIMIT_REACHED", "http": 429, "type": "limit", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SANDBOX_DAILY_LIMIT_REACHED", "replaces": [ { "code": "RATE_LIMIT_EXCEEDED", "http": 429 } ] }, { "code": "PACKAGE_LIMIT_EXCEEDED", "http": 429, "type": "limit", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#PACKAGE_LIMIT_EXCEEDED", "replaces": [ { "code": "PACKAGE_LIMIT_EXCEEDED", "http": 429 } ] }, { "code": "ENDPOINT_DAILY_CAP_REACHED", "http": 429, "type": "limit", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#ENDPOINT_DAILY_CAP_REACHED", "replaces": [ { "code": "ENDPOINT_DAILY_CAP_REACHED", "http": 429 } ] }, { "code": "TOO_MANY_OPEN_REQUESTS", "http": 429, "type": "limit", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#TOO_MANY_OPEN_REQUESTS", "replaces": [ { "code": "RATE_LIMIT_EXCEEDED", "http": 429 } ] }, { "code": "SOURCE_UNAVAILABLE", "http": 502, "type": "source_error", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SOURCE_UNAVAILABLE", "replaces": [ { "code": "UPSTREAM_ERROR", "http": 502 } ] }, { "code": "SOURCE_LIMIT_REACHED", "http": 503, "type": "source_error", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#SOURCE_LIMIT_REACHED", "replaces": [ { "code": "UPSTREAM_ERROR", "http": 502 } ] }, { "code": "INTERNAL_ERROR", "http": 500, "type": "internal", "retryable": true, "doc_url": "https://www.dealerpricing.co.uk/developer/errors#INTERNAL_ERROR", "replaces": [ { "code": "INTERNAL_ERROR", "http": 500 } ] } ] }