--- title: "VIN Decoder reference" url: "https://lookvalid.com/docs/api/vin-decoder.md" canonical_url: "https://lookvalid.com/docs/api/vin-decoder" last_updated: "2026-10-22" type: "reference" summary: "Request and response reference for VIN Decoder: parameters, response fields, credit cost and error codes." related: ["https://lookvalid.com/docs/errors.md"] --- # VIN Decoder reference Request and response reference for VIN Decoder: parameters, response fields, credit cost and error codes. Decodes a 17-character vehicle identification number with the US NHTSA vPIC service: model year, make, model, trim, body, engine, drivetrain, assembly plant and the safety equipment NHTSA has on record. The check digit is verified before NHTSA is called. Empty fields mean NHTSA has no data, not that the feature is missing. ```http POST https://YOUR_API_HOST/v1/vin-decoder ``` ## Credits and caching - Success billing. 1 credit per VIN that decodes (a VIN with no data is free). You are charged only when the lookup finds something; a not-found result is free. - Results are cached per account for 7 days. Repeating the same lookup in that window is free and returns `cache_hit: true`. - Invalid input, rate limits and errors are never charged. - Read the [billing rules](https://lookvalid.com/docs/credits-and-billing.md) for the full picture. ## Request Send a JSON body with `Authorization: Bearer `. The body can be up to 64 KB. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `vin` | string | yes | Up to 40 characters. | | `ignore_check_digit` | boolean | no | - | | `model_year` | integer | no | Minimum 1981. Maximum 2040. | ### Example request **cURL** ```sh curl -X POST https://YOUR_API_HOST/v1/vin-decoder \ -H "Authorization: Bearer $LOOKVALID_API_KEY" \ -H "Content-Type: application/json" \ -d '{"vin":"1HGCM82633A004352"}' ``` **Node.js** ```js const response = await fetch("https://YOUR_API_HOST/v1/vin-decoder", { method: "POST", headers: { Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "vin": "1HGCM82633A004352" }), }); const result = await response.json(); if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`); console.log(result.found, result.data, result.credits_charged); ``` **Python** ```python import os import requests response = requests.post( "https://YOUR_API_HOST/v1/vin-decoder", headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"}, json={ "vin": "1HGCM82633A004352", }, timeout=30, ) result = response.json() if not response.ok: raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}") print(result["found"], result["data"], result["credits_charged"]) ``` ## Response The status is 200 whether or not anything was found. Check `found`. Every response also carries the `X-Request-Id`, `X-Credits-Charged`, `X-Credits-Remaining` and `X-RateLimit-*` headers. ### Envelope | Field | Type | Notes | | --- | --- | --- | | `request_id` | string | - | | `product` | "vin-decoder" | - | | `found` | boolean | False means the lookup ran and found nothing; it is free. | | `reason` | string or null | Why nothing was found; null when found. | | `sources` | array of string | Where the data came from, including any attribution the licence requires. | | `credits_charged` | integer | 0 for a cache hit, a not-found result or an error. | | `credits_remaining` | integer | - | | `cache_hit` | boolean | True when the account already paid for this lookup within the cache window. | | `cache` | object | - | ### The `data` object Present when `found` is true, otherwise `null`. | Field | Type | Notes | | --- | --- | --- | | `vin` | string | - | | `model_year` | number or null | - | | `make` | string or null | - | | `model` | string or null | - | | `trim` | string or null | - | | `series` | string or null | - | | `vehicle_type` | string or null | - | | `body_class` | string or null | - | | `doors` | number or null | - | | `drive_type` | string or null | - | | `transmission` | string or null | - | | `fuel_type_primary` | string or null | - | | `fuel_type_secondary` | string or null | - | | `electrification_level` | string or null | - | | `engine` | object | - | | `engine.cylinders` | number or null | - | | `engine.displacement_l` | number or null | - | | `engine.horsepower` | number or null | - | | `engine.kw` | number or null | - | | `engine.model` | string or null | - | | `engine.configuration` | string or null | - | | `engine.turbo` | string or null | - | | `engine.manufacturer` | string or null | - | | `plant` | object | - | | `plant.city` | string or null | - | | `plant.state` | string or null | - | | `plant.country` | string or null | - | | `plant.company` | string or null | - | | `manufacturer` | string or null | - | | `gvwr` | string or null | - | | `safety` | object | - | | `safety.abs` | string or null | - | | `safety.esc` | string or null | - | | `safety.tpms` | string or null | - | | `safety.traction_control` | string or null | - | | `safety.seat_belts` | string or null | - | | `safety.airbags` | object | - | | `safety.airbags.front` | string or null | - | | `safety.airbags.side` | string or null | - | | `safety.airbags.curtain` | string or null | - | | `safety.airbags.knee` | string or null | - | | `safety.airbags.seat_cushion` | string or null | - | | `safety.driver_assistance` | object | - | | `safety.driver_assistance.forward_collision_warning` | string or null | - | | `safety.driver_assistance.lane_departure_warning` | string or null | - | | `safety.driver_assistance.lane_keep_system` | string or null | - | | `safety.driver_assistance.blind_spot_monitoring` | string or null | - | | `safety.driver_assistance.parking_assist` | string or null | - | | `safety.driver_assistance.adaptive_cruise_control` | string or null | - | | `safety.driver_assistance.crash_imminent_braking` | string or null | - | | `safety.driver_assistance.dynamic_brake_support` | string or null | - | | `safety.driver_assistance.pedestrian_automatic_emergency_braking` | string or null | - | | `safety.driver_assistance.rear_visibility_system` | string or null | - | | `safety.driver_assistance.rear_cross_traffic_alert` | string or null | - | | `safety.driver_assistance.rear_automatic_emergency_braking` | string or null | - | | `safety.driver_assistance.blind_spot_intervention` | string or null | - | | `safety.driver_assistance.lane_centering_assistance` | string or null | - | | `safety.driver_assistance.daytime_running_light` | string or null | - | | `safety.driver_assistance.adaptive_driving_beam` | string or null | - | | `decode_quality` | string | One of `complete`, `partial`. | | `warnings` | array of object | - | | `warnings[].code` | integer | - | | `warnings[].text` | string | - | | `additional_notes` | string or null | - | | `suggested_vin` | string or null | - | | `notes` | string | - | ### Captured example (2026-10-18) A real run of this lookup on 2026-10-18, using the request above, which is a public input. The envelope fields are left out. ```json { "product": "vin-decoder", "found": true, "data": { "vin": "1HGCM82633A004352", "model_year": 2003, "make": "HONDA", "model": "Accord", "trim": "EX-V6", "series": null, "vehicle_type": "PASSENGER CAR", "body_class": "Coupe", "doors": 2, "drive_type": null, "transmission": "Automatic", "fuel_type_primary": "Gasoline", "fuel_type_secondary": null, "electrification_level": null, "engine": { "cylinders": 6, "displacement_l": 3, "horsepower": 240, "kw": null, "model": "J30A4", "configuration": "V-Shaped", "turbo": null, "manufacturer": null }, "plant": { "city": "MARYSVILLE", "state": "OHIO", "country": "UNITED STATES (USA)", "company": null }, "manufacturer": "AMERICAN HONDA MOTOR CO., INC.", "gvwr": "Class 1C: 4,001 - 5,000 lb (1,814 - 2,268 kg)", "safety": { "abs": null, "esc": null, "tpms": null, "traction_control": null, "seat_belts": "Manual", "airbags": { "front": "1st Row (Driver and Passenger)", "side": "1st Row (Driver and Passenger)", "curtain": "1st and 2nd Rows", "knee": null, "seat_cushion": null }, "driver_assistance": { "forward_collision_warning": null, "lane_departure_warning": null, "lane_keep_system": null, "blind_spot_monitoring": null, "parking_assist": null, "adaptive_cruise_control": null, "crash_imminent_braking": null, "dynamic_brake_support": null, "pedestrian_automatic_emergency_braking": null, "rear_visibility_system": null, "rear_cross_traffic_alert": null, "rear_automatic_emergency_braking": null, "blind_spot_intervention": null, "lane_centering_assistance": null, "daytime_running_light": null, "adaptive_driving_beam": null } }, "decode_quality": "complete", "warnings": [], "additional_notes": null, "suggested_vin": null, "notes": "Empty values in the source mean NHTSA has no data for that field; they do not mean the vehicle lacks the feature." }, "sources": [ "NHTSA vPIC vehicle decoder (vpic.nhtsa.dot.gov), US government data" ] } ``` ## Errors - `400` [`invalid_input`](https://lookvalid.com/docs/errors.md#invalid_input): The request input is invalid. - `401` [`unauthorized`](https://lookvalid.com/docs/errors.md#unauthorized): The API key is missing, malformed, revoked or unknown. - `402` [`insufficient_credits`](https://lookvalid.com/docs/errors.md#insufficient_credits): The account does not have enough credits for this lookup. Error code: insufficient_credits. During a trial whose allowance is used up the code is trial_allowance_exhausted: nothing is charged and the customer starts the plan from the billing page. - `405` [`method_not_allowed`](https://lookvalid.com/docs/errors.md#method_not_allowed): This endpoint does not accept that HTTP method. - `413` [`payload_too_large`](https://lookvalid.com/docs/errors.md#payload_too_large): The request body is too large. - `429` [`rate_limited`](https://lookvalid.com/docs/errors.md#rate_limited): Too many requests for this API key. - `500` [`internal_error`](https://lookvalid.com/docs/errors.md#internal_error): An unexpected error occurred. - `503` [`provider_unavailable`](https://lookvalid.com/docs/errors.md#provider_unavailable): The data source for this product is unavailable right now. ## Related - [Errors](https://lookvalid.com/docs/errors.md)