A vehicle identification number is seventeen characters long and every position means something. The first three are the world manufacturer identifier. Positions four through eight describe the vehicle: body style, restraint system, engine family, series. Position nine is a check digit computed from the other sixteen. Position ten is the model year, eleven is the assembly plant, and the last six are the sequential number that makes the whole string unique.
That structure is why a VIN is worth decoding rather than storing as an opaque string. It is also why a decoded VIN stops short of what a shop actually needs. The characters describe how the car was built. They do not describe how it is serviced.
The check digit is the cheapest test you can run
Position nine is derived, not assigned. Each character maps to a value, each position carries a weight, and the sum modulo eleven gives the digit (with X standing for ten). A VIN that fails that arithmetic was mistyped or invented, and you can find that out before making any request at all. The API returns 400 with invalid_vin for anything that is not seventeen characters, but the check digit catches the harder case: seventeen characters that are still wrong.
Where the decode stops
Decoding gives you a family: a 2019 Honda CR-V, say, with an idea of the engine and body. What it does not give you is the exact configuration, and the configuration is where the maintenance numbers live. Two cars with the same model name and the same year can take different oil volumes, run different tire sizes and follow different service schedules, because they left the factory with different drivetrains.
GET /v1/decode?vin=5J6RW2H82KL000007{ "config_key": "2019_honda_cr_v_ex_l15be", "engine": { "label": "1.5L L15BE 4cyl" }, "drivetrain": "4WD", "transmission": "CVT" }That config_key is the useful output. It is stable, it is exact, and every other endpoint takes it. Decode once, store the key with the vehicle, and every later call skips the ambiguity entirely.
What to do with it
- Validate the check digit before you call anything. It costs nothing and catches typed VINs.
- Decode once per vehicle, not once per screen. The config_key does not change.
- Treat identity and maintenance as two different questions. The first has one answer; the second has a shape.