Overview
Data is sourced from the NHTSA vPIC database, the official US vehicle identification record, and is refreshed with each monthly release. Covers vehicles manufactured for sale in the United States.
Endpoint
One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.
curl "https://api.apiverve.com/v1/vindecoder?vin=1HGCM82633A004352" \
-H "x-api-key: your_api_key_here"const res = await fetch('https://api.apiverve.com/v1/vindecoder?vin=1HGCM82633A004352', {
headers: { 'x-api-key': 'your_api_key_here' },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data } = await res.json();
console.log(data);import requests
res = requests.get(
"https://api.apiverve.com/v1/vindecoder?vin=1HGCM82633A004352",
headers={"x-api-key": "your_api_key_here"},
timeout=15,
)
res.raise_for_status()
print(res.json()["data"])package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.apiverve.com/v1/vindecoder?vin=1HGCM82633A004352", nil)
req.Header.Set("x-api-key", "your_api_key_here")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.
Authentication
Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.
A 401 means the key is missing, invalid or expired. A 403 means the key is valid but not permitted here — blocked by a key restriction or an IP allow-list. Running out of credits is a 429.
Parameters
Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them.
| Parameter | Type | Description |
|---|---|---|
vinRequired | string | The Vehicle Identification Number to decode. Partial VINs are accepted and decode as far as the available characters allow. length 1–17 |
Response
Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.
{
"status": "ok",
"error": null,
"data": {
"vin": "1HGCM82633A004352",
"valid": true,
"decoded": true,
"vehicleDescriptor": "1HGCM826*3A",
"make": "HONDA",
"model": "Accord",
"year": 2003,
"trim": "EX-V6",
"trim2": null,
"series": null,
"series2": null,
"manufacturer": "AMERICAN HONDA MOTOR CO., INC.",
"vehicleType": "PASSENGER CAR",
"bodyClass": "Coupe",
"plant": {
"country": "UNITED STATES (USA)",
"city": "MARYSVILLE",
"state": "OHIO"
},
"engine": {
"displacementL": "2.998832712",
"displacementCc": "2998.832712",
"displacementCi": "183",
"engineNumberOfCylinders": "6",
"engineBrakeHpFrom": "240",
"engineConfiguration": "V-Shaped",
"engineModel": "J30A4",
"valveTrainDesign": "Single Overhead Cam (SOHC)",
"fuelTypePrimary": "Gasoline"
},
"features": {
"exterior": {
"doors": "2",
"grossVehicleWeightRatingFrom": "Class 1C: 4,001 - 5,000 lb (1,814 - 2,268 kg)",
"grossVehicleWeightRatingTo": "Class 1: 6,000 lb or less (2,722 kg or less)"
},
"mechanical": {
"transmissionStyle": "Automatic",
"transmissionSpeeds": "5"
},
"passiveSafetySystem": {
"seatBeltType": "Manual",
"otherRestraintSystemInfo": "Seat Belt (Rr center position)",
"frontAirBagLocations": "1st Row (Driver and Passenger)",
"sideAirBagLocations": "1st Row (Driver and Passenger)",
"curtainAirBagLocations": "1st and 2nd Rows"
}
},
"validation": {
"errorCode": "0",
"errorCodes": [
"0"
],
"errorText": "0 - VIN decoded clean. Check Digit (9th position) is correct"
}
}
}Response fields
Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.
| Field | Type | Example | Description |
|---|---|---|---|
vin | string | "1HGCM82633A004352" | The VIN that was decoded, normalized to uppercase |
valid | boolean | true | Whether the VIN passes all NHTSA checks, including the check digit True only when the decode is completely clean (error code 0). A VIN with a mistyped check digit returns false here but may still decode to a real vehicle — read `decoded` for that. |
decoded | boolean | true | Whether the VIN resolved to an identifiable vehicle True when a make was identified. Independent of `valid`: an imperfect VIN can still decode. |
vehicleDescriptor | string | "1HGCM826*3A" | The portion of the VIN that identifies the vehicle build, with variable positions masked |
make | string | "HONDA" | Vehicle manufacturer or brand name |
model | string | "Accord" | Vehicle model name |
year | number | 2003 | Model year of the vehicle |
trimPremium | string | "EX-V6" | Trim level or variant of the model |
trim2Premium | object | null | Secondary trim designation where the manufacturer provides one |
seriesPremium | object | null | Series designation of the vehicle |
series2Premium | object | null | Secondary series designation where the manufacturer provides one |
manufacturer | string | "AMERICAN HONDA MOTOR CO., INC." | Full legal name of the manufacturing company |
vehicleType | string | "PASSENGER CAR" | Broad vehicle classification, such as passenger car or truck |
bodyClass | string | "Coupe" | Body style of the vehicle, such as coupe or sedan |
plantPremium | object | {...} | Manufacturing plant that built the vehicle, including city, state, country and company |
countryPremium | string | "UNITED STATES (USA)" | |
cityPremium | string | "MARYSVILLE" | |
statePremium | string | "OHIO" | |
enginePremium | object | {...} | Engine specifications, including displacement, cylinder count, configuration, horsepower, fuel type and electrification level Fields present vary by vehicle. Electric vehicles report electrification level and motor detail in place of displacement and cylinders. |
displacementLPremium | string | "2.998832712" | |
displacementCcPremium | string | "2998.832712" | |
displacementCiPremium | string | "183" | |
engineNumberOfCylindersPremium | string | "6" | |
engineBrakeHpFromPremium | string | "240" | |
engineConfigurationPremium | string | "V-Shaped" | |
engineModelPremium | string | "J30A4" | |
valveTrainDesignPremium | string | "Single Overhead Cam (SOHC)" | |
fuelTypePrimaryPremium | string | "Gasoline" | |
features | object | {...} | Equipment fitted to this build, grouped by area A container. The grouped objects inside it are premium. Fields absent from NHTSA's record for a given vehicle are omitted rather than returned empty. |
exteriorPremium | object | {...} | Exterior attributes including body, doors, dimensions, weight rating, wheels, and truck, bus, trailer or motorcycle specifics |
doorsPremium | string | "2" | |
grossVehicleWeightRatingFromPremium | string | "Class 1C: 4,001 - 5,000 lb (1,814 - 2,268 kg)" | |
grossVehicleWeightRatingToPremium | string | "Class 1: 6,000 lb or less (2,722 kg or less)" | |
mechanicalPremium | object | {...} | Mechanical attributes including transmission, drivetrain, brakes and battery |
transmissionStylePremium | string | "Automatic" | |
transmissionSpeedsPremium | string | "5" | |
passiveSafetySystemPremium | object | {...} | Passive safety equipment including air bag locations and seat belt type |
seatBeltTypePremium | string | "Manual" | |
otherRestraintSystemInfoPremium | string | "Seat Belt (Rr center position)" | |
frontAirBagLocationsPremium | string | "1st Row (Driver and Passenger)" | |
sideAirBagLocationsPremium | string | "1st Row (Driver and Passenger)" | |
curtainAirBagLocationsPremium | string | "1st and 2nd Rows" | |
validation | object | {...} | Decode diagnostics reported by NHTSA |
errorCode | string | "0" | NHTSA error code or codes for the decode, as a comma-separated string "0" means the VIN decoded clean. Multiple codes are returned together, for example "1,7,11". |
errorCodes | array | [0] | The same NHTSA error codes split into an array for programmatic handling |
errorText | string | "0 - VIN decoded clean. Check Digit (9th position) is correct" | Human-readable explanation of each error code returned |
Errors
Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.
| Status | Meaning | What to do |
|---|---|---|
400 | Input was rejected | Read error; it names the parameter. |
401 | Key missing or invalid | Check the header name and the key value. |
403 | Key valid, but not permitted | A key restriction or IP allow-list; see key scoping. |
429 | Rate limited, or out of credits | Read error to tell them apart; see rate limits. |
Other ways to use VIN Decoder
Set up VIN Decoder on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.
Related
More in Transportation: