When you need to reliably determine a vehicle’s body style and number of doors from a VIN for listing templates, risk models, parts fitment, or eligibility checks, you want one fast, consistent field you can trust. By the end of this guide, you’ll be able to call Vehicle API’s VIN decoder, extract the body style and doors from the response envelope, handle nulls and errors correctly, and ship a cache-friendly integration.
What this endpoint does (and exactly what you’ll use)
The Vehicle API VIN decoder turns any 17-character VIN into normalized specs including body style and number of doors. Body and doors are the two fields you’ll use for “VIN Body Style API” use cases:
- data.body: a normalized body style label, e.g., “Coupe”.
- data.doors: the number of doors as an integer, e.g., 2.
Coverage notes to plan around:
- VIN decoding works worldwide but is fullest for US-market vehicles. Fields not published by NHTSA can be null in the response.
- US safety datasets (recalls, complaints, NCAP crash ratings) are US-market only and are matched by make + model + year. They are separate from VIN decoding and not covered here.
- Dutch plates from RDW open data never include a VIN, so plate-based lookups from the Netherlands do not bridge to this VIN endpoint.
- This is not a vehicle history report; no title, accident, or ownership history is included.
Base URL: https://vehicles-api.com/api/v1. Authenticate with the X-API-Key header (Authorization Bearer also works). You can also access the same capabilities as an MCP server at MCP.
Endpoint and required request
Endpoint: POST https://vehicles-api.com/api/v1/vin/decode
Request body: a JSON object with the 17-character VIN. No other parameters are required to get body and doors.
Copy-paste cURL
Official Vehicle API docs example. Decodes any 17-character VIN worldwide; fullest for US-market vehicles. Fields NHTSA does not publish come back null. The control VIN is a gasoline car, so the electrification fields (electrification_level, battery_kwh, charger_level…) are null: do not invent EV values.
Source: docs_fixture
cURL:
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"}'Official JSON response
JSON:
{
"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 actually use for body style:
- status: "success" on successful decode. On failures it is "error".
- source: "nhtsa" indicates the authoritative source used for decoding.
- data.body: normalized body style label, here "Coupe".
- data.doors: number of doors, here 2.
- data.valid: true means the VIN structure passed validation. If false, downstream fields can be incomplete or null.
Other fields are available if you need them (year, make, model, engine specs, transmission, plant, manufacturer). For a VIN Body Style integration, keep your parsing minimal and robust to null values on fields that may be unreported.
JavaScript example: parse body and doors safely
This minimal Node.js/JavaScript snippet demonstrates how to call the endpoint, extract body and doors, and guard against nulls. It uses the same VIN and headers as the official example and is ready to paste into your service or test script.
import fetch from "node-fetch";
const API_URL = "https://vehicles-api.com/api/v1/vin/decode";
const API_KEY = "YOUR_API_KEY"; // Or use Authorization: Bearer YOUR_API_KEY
async function getBodyStyleFromVin(vin) {
const res = await fetch(API_URL, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
// "Authorization": "Bearer YOUR_API_KEY" // optional alternative
},
body: JSON.stringify({ vin })
});
const json = await res.json();
// Envelope handling
if (!json || json.status !== "success") {
const code = json && json.error && json.error.code;
const message = json && json.error && json.error.message;
throw new Error(message || `VIN decode failed${code ? ` (${code})` : ""}`);
}
const data = json.data || {};
// Safely read body and doors, preserving nulls if not published
const body = data.body ?? null;
const doors = typeof data.doors === "number" ? data.doors : null;
return { body, doors, source: json.source };
}
(async () => {
try {
const result = await getBodyStyleFromVin("1HGCM82633A004352");
console.log("Body:", result.body); // expected "Coupe"
console.log("Doors:", result.doors); // expected 2
console.log("Source:", result.source); // expected "nhtsa"
} catch (err) {
console.error("Error:", err.message);
}
})();Response envelope, nulls, and error handling
Every response is an envelope with:
- status: "success" or "error".
- On success: source and data are present.
- On error: error.code and error.message explain what went wrong.
Plan your control flow like this:
- Check status first.
- On success, read data.body and data.doors defensively. Either may be null when the source does not publish the attribute for that VIN configuration.
- On error, bubble up error.message (and optionally error.code) to your logs and retry or prompt for correction as appropriate.
Null handling is expected for fields NHTSA does not publish. Do not coerce null into misleading defaults. If you must render a value, prefer a UI fallback such as “Unknown body style” or a disabled filter state.
Caching decoded VINs
VINs are immutable identifiers. Once decoded, body style and door count for a given VIN will not change. To reduce latency and conserve your quota:
- Cache successful decodes by VIN key in your database or an edge cache.
- Cache null results as well, but consider a longer TTL for positive results and a shorter TTL for nulls if you expect future data backfills (e.g., when a source expands coverage).
- Log source to help diagnose differences when testing across markets or data providers.
Production practices for body style accuracy
To keep your “VIN Body Style API” implementation dependable in real apps:
- Validate VIN length (17 characters) client-side before calling the API to reduce avoidable errors.
- Respect case insensitivity for VIN input but store VINs uppercased to normalize cache keys.
- Prefer the normalized body string from data.body for UI filters and taxonomy mapping. It avoids variations in manufacturer marketing names.
- When building eligibility or pricing logic tied to doors (e.g., 2-door vs. 4-door coupes/sedans), branch on data.doors as an integer and treat null as “unknown” instead of assuming 4.
- If your workflow includes non-US vehicles, expect more nulls on attributes not published by NHTSA. For US-market vehicles, coverage is generally fuller.
Rate limits, monthly quota, and retries
Vehicle API enforces plan-based rate limits and monthly quotas. If you exceed your plan’s limits, the API returns an error envelope (status = "error"). Handle these cases cleanly:
- Retry with exponential backoff only for transient network issues or timeouts, not for hard limit errors.
- Surface error.message to your logs or metrics so you can monitor consumption against your monthly quota.
- Use caching to minimize redundant decodes and stay within limits.
To review current limits for your plan and environment, see the Documentation.
MCP server option for agentic workflows
If you are building AI agents or tools that prefer MCP over REST, Vehicle API also runs an MCP server at MCP. Your agent can request a VIN decode and read the same body and doors fields from the standardized tool response, mirroring the JSON envelope returned by the REST API at https://vehicles-api.com/api/v1.
Security and authentication
Authenticate requests with one of:
- X-API-Key: YOUR_API_KEY
- Authorization: Bearer YOUR_API_KEY
Scope your key to the environments that need it and inject via secrets management. Avoid embedding keys in mobile binaries or client-side JavaScript; proxy calls through your backend if needed.
Testing with the control VIN (do not use as your production fixture)
The example VIN 1HGCM82633A004352 decodes to a 2003 HONDA Accord EX-V6, body = "Coupe", doors = 2. It appears in the official docs and is suitable for smoke tests and integration checks, but do not rely on it as a representative sample for all markets or trims. Always validate your own VIN set, especially for vehicles outside the US market where some attributes may be null.
Troubleshooting checklist
- Received status = "error": Log error.code and error.message; check API key validity, VIN length (17), and plan limits.
- data.body is null: The source does not publish that attribute for the given VIN; handle gracefully or fall back to a manual selection flow.
- data.doors is null: Treat as unknown. If your UX requires a value, prompt for confirmation. Do not assume a default.
- High latency or timeouts: Cache decoded VINs and batch background enrichment to keep UI fast. Consider retries with short backoff on transient failures, not on API limit errors.
Putting it all together in your app
For dealer tools and marketplaces, map body and doors directly to inventory filters, listing badges, and search facets. For fleet and insurance apps, branch logic on data.doors when door count alters eligibility or pricing. For AI agents, combine VIN decoding over REST or MCP with your reasoning chain, but treat nulls as explicit unknowns to avoid hallucinating body styles.
Remember:
- VIN decoding is worldwide but fullest for US-market vehicles. Keep null-tolerant logic for non-US VINs.
- US safety datasets (recalls, complaints, NCAP) are separate and US-only; they are matched by make + model + year, not VIN-specific in this guide.
- RDW Dutch plates never include VINs, so use plate-native lookups for NL workflows and VIN decoding for VIN-native workflows.
cURL and JSON recap for quick reference
Keep this cURL in your README for teammate smoke tests. It exercises authentication, method, and payload, and returns body and doors in the envelope shown above.
On success, read data.body and data.doors. On error, read error.code and error.message. Cache by VIN.
Where to go next
Explore the complete field reference and additional datasets in the Documentation. If you prefer tool-style integration, start with the MCP server at MCP. To start testing against live endpoints right away, begin your 7-day free trial on the Starter plan at Register. You can always return to the homepage at vehicles-api.com for product context.
FAQ
Does the VIN Body Style API return different values for markets outside the US?
The same endpoint decodes VINs worldwide, but fields are fullest for US-market vehicles. If NHTSA does not publish a field for a given VIN, it will be null. Handle nulls gracefully in non-US workflows.
Is body style linked to recall or crash rating data?
No. Recalls, owner complaints, and NCAP crash ratings are US-market datasets matched by make + model + year. They are separate from VIN decoding. Use VIN decoding for specs like body and doors; use the safety datasets when you need US-market safety information.
Will Dutch plate lookups give me a VIN to decode into body style?
No. RDW open data for Dutch plates does not include a VIN. Use VIN decoding when you have a VIN; use RDW plate endpoints for plate-native data (separate from this guide).
How should I handle null doors or body in my UI?
Treat null as unknown. Do not coerce to a default. Provide a manual selection fallback or an "Unknown" label and allow users to proceed without forced assumptions.
What happens if I exceed my plan’s rate limit or monthly quota?
The API returns an error envelope with status = "error". Log error.message (and error.code if present), back off from retries for hard limit errors, and prioritize caching to reduce repeat decodes. See the Documentation for plan details.
Ready to implement VIN body style and door count in your app? Start your 7-day free trial and get your API key at Register, then call the decoder at https://vehicles-api.com/api/v1 to ship your integration.
