Decode a VIN with an API call

US federal rules set the content of a VIN in 49 CFR 565.15 ¹. It has four sections: three characters, then five, then one, then eight. This post calls the first three the WMI (world manufacturer identifier), positions 4 to 8 the VDS (vehicle descriptor section) and positions 10 to 17 the VIS (vehicle identifier section). Those labels are shorthand, and the regulation itself speaks of sections ¹.

The same section assigns a value to every letter except I, O and Q, and the model year and plant characters come from the same character set ¹. The decoder follows that: it rejects any VIN that is not exactly 17 characters or that contains I, O or Q, before it looks anything up.

The regulation turns the check digit into arithmetic: each character gets a value (digits keep their face value, letters map through a table), each position has a weight, the products are added and the sum is divided by 11 ¹. The remainder gives the ninth character, and a remainder of 10 is written as X ¹.

Here is the code the decoder runs, in JavaScript. Position 9 has weight 0 because it is the character being checked.

1const TRANSLITERATION = {
2  A: 1, B: 2, C: 3, D: 4, E: 5, F: 6, G: 7, H: 8, J: 1, K: 2, L: 3, M: 4, N: 5,
3  P: 7, R: 9, S: 2, T: 3, U: 4, V: 5, W: 6, X: 7, Y: 8, Z: 9,
4};
5const WEIGHTS = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];
6​
7export function checkDigit(vin) {
8  let sum = 0;
9  for (let i = 0; i < 17; i++) {
10    const c = vin[i];
11    sum += (c >= '0' && c <= '9' ? Number(c) : TRANSLITERATION[c]) * WEIGHTS[i];
12  }
13  const r = sum % 11;
14  return r === 10 ? 'X' : String(r);
15}
16​
17console.log(checkDigit('1HGCM82633A004352')); // 3, the ninth character

For the VIN 1HGCM82633A004352, the products by position are 8, 56, 42, 15, 16, 24, 4, 60, 0, 27, 8, 0, 0, 20, 12, 15 and 4. They add up to 311. Dividing 311 by 11 leaves a remainder of 3, and the ninth character of the VIN is 3, so the check passes. Change any one character and the sum moves, so most single typing mistakes fail the check.

The check digit rule belongs to the US regulation ¹, and the vehicle data behind the decoder covers vehicles intended for sale or importation into the United States ³. A VIN on a vehicle built for another market may not follow the US rule. For that reason the VIN decoder verifies the check digit by default and refuses a mismatch with a message that tells you the digit it expected. If you know the VIN is real and was built outside North America, send ignore_check_digit: true and the length and character rules still apply.

The data source also says that vehicles not intended for sale or importation into the US return a limited result ³. Expect more empty fields for those.

The decoder checks the VIN locally first, then asks the NHTSA vPIC service, which is the US government vehicle decoder ². VINs that fail the local checks are refused with HTTP 400 and cost nothing, so a typo never reaches NHTSA. Try one VIN with curl before you write code.

1curl -X POST https://YOUR_API_HOST/v1/vin-decoder \
2  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"vin":"1HGCM82633A004352"}'

The response for that VIN has found: true and a data object. These are the fields, taken from the live capture for that VIN:

A null value means NHTSA has no data for that field. It does not mean the vehicle lacks the feature, and the response says so in its notes field. A decode_quality of partial means NHTSA could not resolve every part of the VIN, so check warnings before you trust the model and trim.

This function returns a small summary and turns every refusal into an error that carries the API's message. It uses the built-in fetch, so it has no dependencies.

1const API = 'https://YOUR_API_HOST';
2​
3export async function decodeVin(vin) {
4  const response = await fetch(`${API}/v1/vin-decoder`, {
5    method: 'POST',
6    headers: {
7      Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
8      'Content-Type': 'application/json',
9    },
10    body: JSON.stringify({ vin }),
11  });
12  const body = await response.json();
13  if (!response.ok) {
14    // A bad length, a bad character or a wrong check digit is a 400 with a message that names the problem.
15    throw new Error(body.error?.message ?? `HTTP ${response.status}`);
16  }
17  if (!body.found) return { vin, decoded: false, reason: body.reason };
18  const { model_year, make, model, trim, decode_quality } = body.data;
19  return { vin, decoded: true, model_year, make, model, trim, decode_quality };
20}
21​
22console.log(await decodeVin('1HGCM82633A004352'));

• Input: vin is required. model_year (1981 to 2040) is optional, and NHTSA recommends always sending it when you have it ². ignore_check_digit is optional.
• Cost: a VIN that decodes costs 1 credit. A refused VIN and a VIN with no data are free.
• Repeats: the same VIN, model year and check setting is served from your account's cache for 7 days at no charge.
• Spelling: the VIN is trimmed and upper-cased before it is checked, so lower-case input from a form is fine.

To try a VIN without writing code, use the free VIN decoder. To see how keys work, start at the documentation.

1. Ask for the VIN and, if you have it, the model year.
2. Call the decoder on submit. On a 400, show the message beside the field, because it names the exact problem.
3. On found: false, keep the VIN and let the person continue, since a real VIN can be missing from the source.
4. On a match, prefill make, model and year, and let the person correct them.

Treat the decoded fields as a prefill, not a ruling. They come from what the manufacturer reported to NHTSA, and plenty of fields on older vehicles will be empty.