You need to turn a 17-character VIN into a dependable year, make and model for listings, underwriting, or fleet inventory. By the end of this guide, you will send one POST request to decode a VIN with Vehicle API, read the year/make/model fields, handle nulls and errors, and ship a production-ready integration that caches results and respects your plan limits.
What this endpoint does and when to use it
The VIN Year Make Model lookup decodes any 17-character VIN worldwide and returns normalized year, make and model alongside trim, body, engine, transmission and plant details. Data is sourced from NHTSA’s vPIC. Coverage is strongest for US-market vehicles. When certain fields are not published by NHTSA, they are returned as null.
Use this endpoint whenever you need authoritative year/make/model from a VIN for dealer tools, marketplaces, fleet and insurance apps, or AI agents. This is not a vehicle history report (no title, accident, or ownership history). US safety data (recalls, owner complaints, NCAP crash ratings) are available in Vehicle API, but they are US-market only and matched by year + make + model. Dutch plates are supported from RDW open data and never contain a VIN.
Set up: free trial, API key, and base URL
Every plan starts with a 7-day free trial. Create your account, copy your key from the dashboard, and you’re ready to call the VIN decode endpoint.
- Start here: Register
- Docs reference: Documentation
- MCP server (for AI agents): MCP
Base URL: https://vehicles-api.com/api/v1
Auth: send your key as X-API-Key: YOUR_API_KEY (Authorization: Bearer YOUR_API_KEY is also accepted).
Make a VIN Year Make Model request
The endpoint is a POST to /vin/decode with a JSON body containing the VIN. All responses are wrapped in an envelope with status and source, and a data object on success.
cURL: POST /vin/decode
curl -X POST "https://vehicles-api.com/api/v1/vin/decode" -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"vin":"1HGCM82633A004352"}'Understand the response envelope and the year/make/model fields
Every response adheres to this structure:
- status: "success" or "error"
- source: the upstream dataset (for VIN decoding, "nhtsa")
- data: present on success; contains the decoded vehicle fields including year, make and model
- error: present on error; contains error.code and error.message
Official JSON example (VIN: 1HGCM82633A004352)
{
"status": "success",
"source": "nhtsa",
"data": {
"vin": "1HGCM82633A004352",
"valid": true,
"year": 2003,
"make": "HONDA",
"model": "Accord",
"trim": "EX-V6",
"body": "Coupe",
"doors": 2,
"vehicle_type": "PASSENGER CAR",
"engine": {
"cylinders": 6,
"displacement_l": 3,
"configuration": "V-Shaped",
"model": "J30A4",
"hp": 240,
"fuel": "Gasoline"
},
"fuel_type": "Gasoline",
"electrification_level": null,
"ev_drive_unit": null,
"battery_kwh": null,
"charger_level": null,
"charger_power_kw": null,
"drive": null,
"transmission": {
"style": "Automatic",
"speeds": 5
},
"plant": {
"country": "UNITED STATES (USA)",
"city": "MARYSVILLE",
"state": "OHIO"
},
"manufacturer": "AMERICAN HONDA MOTOR CO., INC."
}
}Fields you will typically read for this use case:
- data.year: integer model year (e.g., 2003)
- data.make: manufacturer name (e.g., HONDA)
- data.model: model name (e.g., Accord)
Other fields are available for UI display or filtering (trim, body, engine, transmission, plant). Electrification fields are null for gasoline vehicles. When NHTSA does not publish a field for a VIN, that field is returned as null.
Parse year, make and model in code
The following example shows how to call the endpoint, check the response envelope, and extract year/make/model. The control VIN 1HGCM82633A004352 is a 2003 Honda Accord (example only; it is not your user’s vehicle).
Python example: decode VIN and read year/make/model
import requests
API_URL = "https://vehicles-api.com/api/v1/vin/decode"
API_KEY = "YOUR_API_KEY"
def decode_vin(vin: str):
headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}
resp = requests.post(API_URL, json={"vin": vin}, headers=headers, timeout=10)
resp.raise_for_status()
payload = resp.json()
# Envelope check
if payload.get("status") != "success":
err = payload.get("error", {})
code = err.get("code", "unknown_error")
msg = err.get("message", "Unexpected error")
raise RuntimeError(f"VIN decode failed: {code}: {msg}")
data = payload.get("data", {}) or {}
# Safely access fields with defaults
year = data.get("year")
make = data.get("make")
model = data.get("model")
# Validate the core fields are present
if year is None or make is None or model is None:
# Fields can be null if not published by the source
raise ValueError("Missing year/make/model for this VIN")
return {
"vin": data.get("vin"),
"year": year,
"make": make,
"model": model,
"trim": data.get("trim"),
}
if __name__ == "__main__":
result = decode_vin("1HGCM82633A004352")
print(f"{result['vin']}: {result['year']} {result['make']} {result['model']} (trim: {result.get('trim')})")Production details that save time
Response envelope and errors
- Success: status is "success", source will be "nhtsa", and data contains the vehicle fields.
- Error: status is "error", and error.code plus error.message explain what went wrong (for example, invalid request body or a VIN that cannot be decoded). Always branch on status before reading data.
Null fields
- Fields that are not available from NHTSA return null (for example, electrification_level on gasoline vehicles).
- Do not assume optional fields are present. Guard against None/null in your serializers and UI.
Caching decoded VINs
- VIN decode results are stable for a given VIN and rarely change. Cache by VIN key for long durations (e.g., days to months) to reduce latency and conserve quota.
- When you cache, store the envelope timestamp from your system and consider revalidating periodically if you display non-core attributes (trim or engine details may be corrected upstream, though year/make/model are generally immutable).
Rate limits and monthly quota
- Vehicle API enforces per-plan rate limits and a monthly request quota. If you exceed them, you will receive an error response with status "error".
- Check your dashboard for current usage and plan limits. Implement exponential backoff on 429/limit errors and serve cached results.
Timeouts and retries
- Use client timeouts (e.g., 5–10 seconds) and retry idempotently on transient network errors. The VIN decode POST is safe to retry with the same body.
Security and keys
- Send your key as X-API-Key: YOUR_API_KEY. Authorization: Bearer YOUR_API_KEY also works.
- Store keys server-side and proxy requests from your frontend if you cannot protect the key in the browser.
Coverage notes and what not to expect
- VIN decoding works worldwide for 17-character VINs, with fullest coverage for US-market vehicles.
- US safety data (recall campaigns, owner complaints, NCAP crash ratings) are US-market only and matched by make + model + year, separate from the VIN result.
- Dutch plates (RDW) are supported in Vehicle API and never include a VIN. Treat plate lookups and VIN decode as separate flows.
- This is not a vehicle history report: there is no title, accident, or ownership history.
End-to-end workflow for dealers, marketplaces and insurers
- Accept a 17-character VIN input from your user or partner system.
- Normalize by trimming whitespace and uppercasing (A–Z, 0–9). Validate length equals 17 before calling.
- POST to /vin/decode with the VIN in JSON as shown above.
- Check status == "success". If "error", read error.code and error.message and display a helpful message.
- Extract data.year, data.make and data.model for your core schema. Store the entire data object if you need trim/engine/body later.
- Cache results keyed by VIN to save requests and speed up UI.
- If your app also shows US safety data, query by the returned year + make + model to fetch recalls, complaints or NCAP ratings (US-market only).
Testing and QA checklist
- Happy path: valid 17-character VIN returns status "success" and non-null year/make/model.
- Invalid input: non-17 characters or illegal characters returns status "error" with a clear error.message.
- Null handling: confirm your UI tolerates null trim, drive, electrification fields without crashing layout.
- Rate limit simulation: verify your client logs and retries gracefully on limit errors, and serves from cache.
- Monitoring: capture and alert on non-success responses and unusual spikes in decode volume.
Using the MCP server (for agents and tools)
If you are building AI agents or IDE tools, the same capability is available over an MCP server at https://vehicles-api.com/mcp. This gives you a standard tool transport to decode VINs in agent workflows while reusing your Vehicle API key and respecting the same plan limits.
Learn more: MCP
Operational guidance
- Idempotency: VIN decode results are deterministic; you can de-duplicate requests by VIN to avoid duplicate work.
- Logging: log the VIN (hashed if required for privacy), status, source and a small subset of fields (year/make/model) for troubleshooting.
- Privacy: a VIN is not PII but may be handled as sensitive in some environments. Follow your compliance rules.
Frequently asked questions
Is the control VIN 1HGCM82633A004352 my customer’s car?
No. It is the public docs example and decodes to a 2003 HONDA Accord. Use your own VINs in production.
What happens if a field isn’t published by NHTSA?
The field is returned as null. Always check for nulls, especially for electrification and drivetrain details.
Are recalls, complaints, and crash ratings tied to the VIN?
They are US-market only and matched by make + model + year, not by individual VIN.
Do Dutch plates include a VIN?
No. RDW plate data never includes a VIN. Treat Dutch plate lookups as a separate flow from VIN decoding.
Where can I see my rate limits and monthly quota?
In your Vehicle API dashboard. On limit errors, the response has status "error" with an error.code and error.message; implement backoff and serve cached results.
Ready to ship your VIN Year Make Model integration? Start your 7-day free trial and get your API key now: Register. For complete field definitions and additional capabilities, see the Documentation on vehicles-api.com.