Plain-English guide to the VIN Decoder API. For interactive Swagger, see /docs.
Decode any VIN with a single POST request:
curl -X POST https://YOUR-HOST/decode \
-H "Content-Type: application/json" \
-d '{"vin": "19XFB4F25DE200650"}'
This decoder decodes road vehicles (cars, vans, trucks, buses and motorcycles) and, for the manufacturer codes on its powersports list, ATVs and side-by-sides (also off-road motorcycles registered as ATVs; for a few codes also snowmobiles). It refuses a VIN whose own record names a trailer, a boat or personal watercraft, a tractor (a farm tractor or a semi-truck tractor unit: truck tractors are not decoded yet), lawn or construction equipment, or a forklift, and an off-road vehicle from a code or of a kind that list does not cover.
A powersports vehicle (a VIN whose own record names an ATV class, from a manufacturer code on the powersports list, with a matching check digit) is answered with vehicle_type "powersports" and only the fields measured for that class: the make and the model year read from VIN position 10, each checked against registration records, and the plant country, checked against the vehicles' own NHTSA vPIC records; each only for the manufacturer codes where it passed. Every other field is withheld when the decoder found a value (data_quality reason withheld_powersports_scope) or shows not_decoded when it found none. Polaris (4XA, TAP) and Can-Am (3JB) codes keep their earlier decode with all fields.
Other vehicles are refused with HTTP 422; the message states the evidence (the VIN's own record, or the decoder's table for the manufacturer code), never a conclusion about the vehicle.
Decode a single VIN. Returns make/model/year/engine/transmission/body and per-character breakdown.
{"vin": "19XFB4F25DE200650"}
{
"vin": "19XFB4F25DE200650",
"make": "HONDA",
"model": "Civic",
"year": 2013,
"engine_code": "LEA2",
"engine_displacement": 1491,
"transmission": "CVT",
"fuel_type": "GASOLINE",
"body_type": "Sedan",
"country_rules": {...},
"positions": [{"pos":1,"char":"1","name":"Country/Region","value":"North America"}, ...],
"segments": [{"name":"WMI","value":"19X","positions":"1-3"}, ...]
}
Decode up to 50 VINs in one request.
{"vins": ["VIN1", "VIN2", ..., "VIN50"]}
Upload a VIN plate photo, get OCR + decode.
curl -X POST https://YOUR-HOST/decode/image \ -F "file=@vin_photo.jpg"
NHTSA recall campaigns (US-market data) for the vehicle /decode displays: the same list, recall_vehicle and a recall_status (served / none / no_model; 503 = unavailable / not_checked).
Get a representative Wikipedia thumbnail of the make/model/year. Cached 24h.
Validate VIN format + ISO 3779 check digit (no DB hit, instant).
Reverse lookup — find WMI+VDS patterns matching a make/model/year.
curl "https://YOUR-HOST/search?make=TOYOTA&model=COROLLA&year=2020&limit=10"
Generate test VINs for development. count up to 50.
Service health and dataset coverage metrics.
decoder_versionEvery decode result carries decoder_version (for example "2.22.0"), the release of the decoder that produced it. The same number is in the X-Decoder-Version header of every response and in /health. Store it with any result you save or print: the same VIN can decode differently in a later release.
Releases before August 2026 are Beta 1.0. The What's new page lists every release with its version.
data_qualityEvery decode result includes a data_quality block: the /decode response (full and fast), each result of /decode/batch and the /decode/audit response carry it at the top level; /decode/asean carries it inside standard_decode, /decode/pdf inside each decoded[].decoded, and /decode/image inside decoded. A VIN the decoder refuses (HTTP 422 on /decode, an error entry in a batch) has no decode and so no block. For each of the 21 decoded fields it says whether the value is confirmed for this vehicle, so a result can be printed without reading any internal keys. Expect most fields to be unverified: "verified" is deliberately hard to earn.
derived_from_..._engine reason unless the result contradicts the figure itself more directly (for example official_record_disagrees or power_units_disagree).candidate: Only when status is 'withheld' and reason_code is one of withheld_unconfirmed, withheld_weak_source, withheld_record_agrees, withheld_unconfirmed_candidate, withheld_multiple_builds, withheld_multiple_brands, withheld_fuzzy_match: a value the decoder found but did NOT serve. Never a value the decoder set aside as conflicting or rejected as inconsistent, never a value this VIN's own NHTSA vPIC record contradicts (North-American VINs), never an engine code whose hybrid / non-hybrid type conflicts with the served fuel type, and never a value that came with an engine code the decoder withheld or replaced (engine size, cylinders, power, torque, or a fuel type reverted with that code). Several values are joined with ' | '. It is unconfirmed: never print it as the vehicle's value.Only these routes. Each was measured against per-vehicle records (NHTSA vPIC records of other vehicles, registration records) and passed a bar of 16 correct in 17 at 95% confidence (Wilson lower bound).
registration_document]registration_engine_number]wmi_registry]vin_year_code]powersports_registry]nhtsa_record] - 216 of 217 agreed with independent registration recordsFor every other field this VIN's NHTSA vPIC record is a check, not a confirmation: when it agrees the reason says so (nhtsa_record_agrees); when it differs the field is unverified whatever else says, estimated values included (official_record_disagrees); when it states the field less precisely, more specifically, or spells the same value differently, the reason says which (record_less_precise, record_more_specific, record_spelling_differs). NHTSA records are known to be wrong about the transmission of many hybrids (nhtsa_known_unreliable). Registry lookups matched to a parts catalogue, dealer records, records of other vehicles with the same VIN prefix, catalogues, inferences and engine serial numbers never verify. Nothing is verified when the VIN contains I, O or Q, when its manufacturer code looks mistyped or is unknown, when its check digit fails (North America, China), for a partial VIN, or when the decoder hit an error; warnings then says why.
A fast decode ("fast": true) consults fewer sources and adds the fast_decode warning; its values, and therefore its statuses, can differ from a full decode of the same VIN. Use the full decode when it matters.
Opting out: send "include_quality": false in the body of a /decode or /decode/batch request (it is also honoured by /decode/audit) to skip this block and save about 5.6 KB per result; data_quality is then null and every other key is unchanged. Leaving the option out (or sending true) always includes the block.
Each field carries status, value (always identical to the top-level field of the same name; null when withheld or missing), candidate, source (plain-language origin, or for a verified field what confirms it; never an internal tag), reason_code (stable, machine-readable) and reason (one printable sentence that is true for this decode). summary groups the field names by status. A candidate appears only under these reason codes: withheld_unconfirmed, withheld_weak_source, withheld_record_agrees, withheld_unconfirmed_candidate, withheld_multiple_builds, withheld_multiple_brands, withheld_fuzzy_match.
field_meta is kept for backward compatibility; its confidence is a legacy source-tier heuristic, not a probability, and it can disagree with data_quality. Use data_quality."data_quality": {
"schema_version": 1,
"summary": {
"verified": [
"make",
"year",
"fuel_type"
],
"unverified": [
"model",
"series",
"submodel",
"body_type",
"vehicle_type",
"engine_displacement",
"cylinders",
"drive_type",
"power_hp",
"power_kw",
"doors",
"seats",
"plant_country",
"manufacturer",
"torque_nm"
],
"estimated": [],
"withheld": [
"engine_code"
],
"missing": [
"transmission",
"transmission_speeds"
]
},
"fields": { // 8 of 21 shown
"make": {
"status": "verified",
"value": "BMW",
"candidate": null,
"source": "Manufacturer code (VIN positions 1-3)",
"reason_code": "wmi_registry",
"reason": "Fixed by the VIN's first three characters: this manufacturer code was checked against official vehicle records and belongs to this brand only."
},
"year": {
"status": "verified",
"value": 2010,
"candidate": null,
"source": "Model-year code (VIN position 10)",
"reason_code": "vin_year_code",
"reason": "Read from VIN position 10 (the model-year code); for this manufacturer code that rule was checked against official vehicle records."
},
"fuel_type": {
"status": "verified",
"value": "diesel",
"candidate": null,
"source": "NHTSA vPIC record (this VIN)",
"reason_code": "nhtsa_record",
"reason": "This VIN's own record in the US government's NHTSA vPIC database gives the same value; for this field such records were checked against independent registration records."
},
"engine_code": {
"status": "withheld",
"value": null,
"candidate": "M57D30TU2",
"source": null,
"reason_code": "withheld_weak_source",
"reason": "The only source for this value is one the decoder does not serve without confirmation (such as a reference table, a shared VIN prefix or an inference), so it was withheld."
},
"engine_displacement": {
"status": "unverified",
"value": 2993,
"candidate": null,
"source": "Reference table (engines or models)",
"reason_code": "record_less_precise",
"reason": "This VIN's own NHTSA vPIC record states this field less precisely than the value shown (for example the engine size only to the nearest 0.1 litre, a power range, a shorter model name or several possible engine codes), so the exact value shown is not confirmed."
},
"power_hp": {
"status": "unverified",
"value": 265.0,
"candidate": null,
"source": "Other vehicles sharing part of this VIN",
"reason_code": "nhtsa_record_agrees",
"reason": "This VIN's own NHTSA vPIC record gives the same value, but NHTSA records have not been shown accurate enough for this field (on this kind of vehicle) to count as confirmed."
},
"torque_nm": {
"status": "unverified",
"value": 520,
"candidate": null,
"source": "Engine data (engine not confirmed)",
"reason_code": "derived_from_withheld_engine",
"reason": "Taken from engine data, but the decoder withheld this vehicle's engine code (see engine_code), so this figure is not confirmed for this vehicle."
},
"plant_country": {
"status": "unverified",
"value": "UNITED STATES",
"candidate": null,
"source": "Labelled NHTSA vPIC (this VIN)",
"reason_code": "nhtsa_label_unchecked",
"reason": "Labelled as taken from this VIN's NHTSA vPIC record, but that record could not be checked for this field here, so it is not confirmed."
}
},
"warnings": []
}
import requests
r = requests.post("https://YOUR-HOST/decode", json={"vin": "5UXFF0C55ALJ98962"}).json()
dq = r["data_quality"]
for w in dq["warnings"]:
print("NOTE:", w["message"])
for name, f in dq["fields"].items():
if f["status"] == "missing":
continue
value = f["value"] if f["value"] is not None else "(not shown)"
line = f"{name:20} {value!s:30} {f['status'].upper()}"
if f["status"] != "verified":
line += " - " + f["reason"]
if f["candidate"] is not None:
line += f" [unconfirmed candidate, not the vehicle's value: {f['candidate']}]"
print(line)
decode_incomplete (no field is verified) - The decoder hit an internal error on this VIN and returned only basic facts from the VIN's structure.vin_autocorrected (no field is verified) - The VIN as given contains I, O or Q, which modern VINs never use. The decoder either replaced them (I->1, O/Q->0) or kept them for an older VIN it has records for. Check the VIN against the vehicle.vin_may_be_mistyped (no field is verified) - The decoder flagged the first three characters of this VIN as likely mistyped; check the VIN and decode again.unregistered_manufacturer_code (no field is verified) - The first three characters of this VIN are not a manufacturer code the decoder recognises.vin_check_digit_failed (no field is verified) - The VIN's check digit does not match; the VIN is probably mistyped.shared_manufacturer_code - This VIN's manufacturer code is used by more than one brand; the brand shown is the decoder's best choice.partial_vin (no field is verified) - Only part of a VIN was given, so only the fields its characters can support were decoded.fast_decode - This was a fast decode, which consults fewer sources: a full decode (without "fast") can show different values and may confirm fields shown here as unverified.registration_document - Taken from a transcription of this vehicle's own registration card, which shows this value.registration_engine_number - The engine number on this vehicle's own registration card begins with this engine code.wmi_registry - Fixed by the VIN's first three characters: this manufacturer code was checked against official vehicle records and belongs to this brand only.vin_year_code - Read from VIN position 10 (the model-year code); for this manufacturer code that rule was checked against official vehicle records.powersports_registry - Read from this VIN by the powersports list's rule for its manufacturer code; for that code the rule was checked against registration records (make, model year) or the vehicles' own NHTSA vPIC records (plant country) of other vehicles with the code.nhtsa_record - This VIN's own record in the US government's NHTSA vPIC database gives the same value; for this field such records were checked against independent registration records.nhtsa_record_agrees - This VIN's own NHTSA vPIC record gives the same value, but NHTSA records have not been shown accurate enough for this field (on this kind of vehicle) to count as confirmed.nhtsa_record_agrees_untrusted - This VIN's own NHTSA vPIC record gives the same value, but the decoder does not rely on NHTSA records for this kind of vehicle (such as heavy trucks, motorcycles or export models), so it is not confirmed.nhtsa_known_unreliable - This VIN's own NHTSA vPIC record gives the same value, but NHTSA records are often wrong about the transmission of hybrid and electric vehicles, so it is not confirmed.official_record_disagrees - This VIN's own NHTSA vPIC record gives a different value for this field.record_less_precise - This VIN's own NHTSA vPIC record states this field less precisely than the value shown (for example the engine size only to the nearest 0.1 litre, a power range, a shorter model name or several possible engine codes), so the exact value shown is not confirmed.record_more_specific - This VIN's own NHTSA vPIC record states this field more specifically than the value shown (for example a longer model name or engine code that begins with the value shown), so the value shown is not confirmed.record_spelling_differs - This VIN's own NHTSA vPIC record gives what appears to be the same value written differently (different spacing, punctuation or a longer or shorter form of the name); NHTSA records are only a check for this field, so it is not confirmed.value_rounded - The value shown is rounded, while this VIN's own NHTSA vPIC record gives a more exact figure, so the rounded value is not confirmed as stated.nhtsa_label_unchecked - Labelled as taken from this VIN's NHTSA vPIC record, but that record could not be checked for this field here, so it is not confirmed.power_units_disagree - The horsepower and kW figures in this result do not convert into each other, so at least one of them is wrong.conflicting_values - The decoder found a different value for this field during this decode and set it aside, so this value is not treated as confirmed.engine_family_conflict - This value does not match what the decoder expects for the family of the engine code shown (for example its fuel or number of cylinders).not_code_shaped - This value does not look like an engine code (it may be an engine serial number or a description), so it is not treated as confirmed.shared_manufacturer_code - This VIN's first three characters are used by more than one brand, so the brand is not confirmed.make_was_changed - The decoder changed the brand during this decode, so it is not treated as confirmed.record_label_unbacked - The decoder marks this value's record label as unbacked, so it is not treated as confirmed.derived_from_conflicting_engine - Taken from engine data, but every engine code the decoder found for this vehicle conflicts with other information about it (such as its fuel type or its own NHTSA record) and was withheld, so this figure may belong to a different engine and is not confirmed.derived_from_withheld_engine - Taken from engine data, but the decoder withheld this vehicle's engine code (see engine_code), so this figure is not confirmed for this vehicle.derived_from_disputed_engine - Taken from engine data while the engine code shown is itself contradicted in this result (see engine_code), so this figure is not confirmed.registry_lookup_record - Taken from a registry lookup for this VIN that was matched to a parts-catalogue vehicle type; checked against manufacturer records, these catalogue matches were not accurate enough to count as confirmed.registration_year_near - This VIN's registration entry shows a registration year within two years of this model year; that supports the year but does not confirm the exact model year.registration_year_used - Set to the year on this VIN's registration entry because the VIN's model-year code gave a year more than 15 years away; a registration year is not necessarily the model year.dealer_record - Taken from a dealer's record for this VIN. Dealer records are not official documents and some contain errors (such as engine serial numbers), so it is not treated as confirmed.prefix_record - Taken from dealer or registry records of vehicles whose VIN starts with the same characters (this vehicle's own record may be among them); not confirmed for this VIN.unbacked_record_claim - Labelled as coming from a registration or user record, but the decoder could not confirm that such a record was applied to this decode.machine_research - Comes from automated (machine) research that no person has checked.manual_correction - Comes from a correction entered by a person, not from an official record for this vehicle.unverified_submission - Comes from a user-submitted correction that is not marked as checked against a listing or document.listing_extract - Comes from a correction record whose source is a sales listing, not a registration record.not_on_registration_card - Comes with a registration-card correction record, but a registration card does not show this field, so the card does not confirm it.engine_number_mismatch - The engine number on this vehicle's registration card does not begin with this engine code, so the card does not confirm it.engine_number_unavailable - The registration card's engine number is not available in this result, so the card cannot confirm this engine code.card_year_differs - This vehicle's registration-card correction record gives a different year of manufacture (year_made in this result) than the year shown, so the card does not confirm this year.card_year_not_confirmed - Taken from this vehicle's registration-card correction record. A card year is not treated as proof, because correction records sometimes replace an unreadable or impossible printed year with one worked out from the VIN.brand_not_fixed_by_wmi - This is the brand the decoder's table lists for the VIN's first three characters; that code has not been shown to belong to one brand only, so the brand is not confirmed.wmi_registry_name - This is the company name the decoder's table lists for the VIN's first three characters; it describes the code's owner and is not a record for this vehicle.wmi_registered_country - This is the country the decoder's table lists for the VIN's manufacturer code; it may not be where this vehicle was assembled.year_code_unconfirmed - Read from VIN position 10; for this manufacturer code that has not been shown to give the model year reliably (outside North America it often does not).year_code_mismatch - Labelled as read from VIN position 10, but it does not match the model-year rule checked for this manufacturer code, so it is not confirmed.shared_vin_prefix - Taken from records of other vehicles that share part of this VIN; not confirmed for this VIN.reference_table - Looked up in a reference table of typical values for engines or models; not confirmed for this VIN.depends_on_unverified_engine - Looked up in an engine table using the engine code, and that engine code is not verified.inferred - Inferred from the model name or from other fields, not read from this VIN or from a record for it.weak_rule - Comes from a general rule that has not been shown reliable enough to count as confirmed.rule_not_measured - Read from this VIN's characters by a decoding rule that has not been shown reliable enough for this field to count as confirmed.rule_table_unconfirmed - Comes from a manufacturer option-code table (VIN position 8) that disagrees with the official US record for some vehicles.no_recorded_source - The decoder did not record where this value came from.other_source - Comes from a source that this quality check does not accept as confirmation.decode_incomplete - The decoder hit an internal error on this VIN, so nothing in this result is confirmed.vin_autocorrected - The VIN as given contains I, O or Q, which modern VINs never use, so it may be mistyped; the vehicle's identity is uncertain and nothing in this result is confirmed.vin_may_be_mistyped - The decoder flagged the first three characters of this VIN as likely mistyped, so nothing in this result is confirmed.unregistered_manufacturer_code - The first three characters of this VIN are not a manufacturer code the decoder recognises, so nothing in this result is confirmed.vin_check_digit_failed - The VIN's check digit (position 9) does not match the rest of the VIN, so it is probably mistyped and nothing in this result is confirmed.partial_vin - Only part of a VIN was given, so nothing in this result is confirmed for a specific vehicle.family_typical_value - A typical figure for this engine family, not a figure recorded for this particular vehicle.production_window_estimate - Estimated from the model's production years, because the year could not be read from this VIN.withheld_unconfirmed - The decoder found a value but withheld it because it could not confirm it for this vehicle.withheld_weak_source - The only source for this value is one the decoder does not serve without confirmation (such as a reference table, a shared VIN prefix or an inference), so it was withheld.withheld_record_agrees - The decoder withheld this value even though this VIN's own NHTSA vPIC record gives the same value; it is offered only as an unconfirmed candidate.withheld_unconfirmed_candidate - A candidate engine code passed the decoder's basic checks, but nothing confirms it for this VIN, so it was not served.withheld_multiple_builds - Records of vehicles sharing this VIN prefix list more than one entry for this field, so the decoder did not serve a value; any candidate shown comes from those entries and is not confirmed.withheld_multiple_brands - This manufacturer code is used by more than one brand and nothing in this decode says which, so no brand is shown.withheld_fuzzy_match - This value came from an approximate (fuzzy) match to other vehicles and was withheld.withheld_conflict - The decoder found a value but set it aside because it conflicts with other information about this vehicle.withheld_contradicted - The decoder found a value but withheld it, and this VIN's own NHTSA vPIC record contradicts it, so no candidate is shown.withheld_candidate_conflicts - The decoder withheld a value that conflicts with this vehicle's fuel type (for example a non-hybrid engine code on a hybrid), so no candidate is shown.withheld_followed_conflicting_engine - This value was withheld together with the engine code it came with, and that engine code conflicts with other information about this vehicle, so no candidate is shown.withheld_followed_engine - This value came with an engine code that the decoder withheld or replaced for this vehicle, so it was withheld too and is not offered as a candidate.withheld_rule_rejected - A value was found but the decoder rejected it as inconsistent with this vehicle, so neither a value nor a candidate is shown.withheld_powersports_scope - This is a powersports vehicle: the decoder shows only the make, model year and plant country for it, each only where it was checked for the manufacturer code, so no value or candidate is shown.not_decoded - The decoder did not produce a value for this field.The decoder applies 6 layers of deduction in order:
Even unknown VINs get region/country/year/plant from pure ISO rules.
The decoder reads VINs differently depending on origin. BMW, Toyota, Honda, Tesla, etc. use their own VDS encoding schemes (60+ manufacturer schemes built in). Check digit validation is mandatory only for North American + Chinese VINs.
Sellers often mask serial digits: JTDKN3EE2D30XXXXX, WBAPH5C55BA2*****, JTD-KN3-DU5-?????. The decoder handles all of these — masking characters (X, *, ., ?, #, dashes, spaces) are stripped automatically.