API docs
Use the VehiCode API to decode VINs, track usage, and report corrections from your own product or backend service.
Authentication
x-api-key: vdx_your_api_keyAuthorization: Bearer vdx_your_api_keyPlans
Errors
400Invalid request payload401Invalid or inactive API key429Monthly or public usage limit reachedRate-limit details are returned in response headers and body usage metadata.
Decode endpoint
The main endpoint returns a compact public vehicle report and current usage metadata. Successful and partial identified decodes include manufacturer. If the manufacturer is absent, treat the response as VIN parsing only, not an identified vehicle. Free and anonymous access returns basic vehicle data. Starter and Business API keys unlock available premium specs, dimensions, weight, and factory details. Empty fields, internal notes, source details, confidence labels, and AI diagnostics are not included in client responses.
Request
curl -X POST https://vehicode.eu/api/decode \
-H "Content-Type: application/json" \
-H "x-api-key: vdx_your_api_key" \
-d '{"vin":"WVWZZZAUZHP507470"}'Response
Vehicle reportVIN segments, manufacturer, model, body style, year, optional specs
Usage metadatalimit, remaining, resetAt
{
"report": {
"vin": "WVWZZZAUZHP507470",
"wmi": "WVW",
"vds": "ZZZAUZ",
"vis": "HP507470",
"validFormat": true,
"manufacturer": "Volkswagen",
"model": "Golf",
"bodyStyle": "Combi",
"bodyStyleNormalized": "wagon",
"modelYear": "2017",
"vehicleType": "Passenger car",
"region": "Europe"
},
"metadata": {
"plan": "business",
"upgradeAvailable": false,
"premiumFieldsAvailable": 0
},
"usage": {
"limit": 2500,
"remaining": 2499,
"resetAt": "2026-08-01T00:00:00.000Z"
}
}Result contract
A usable decode includes a meaningful vehicle identity, usually manufacturer and model. Stronger partial responses may also include model year, body style, vehicle type, or technical fields.
When a valid VIN needs slower enrichment before it is useful, the API returns enrichment_pending with retryAfterSeconds and usageCharged: false. Invalid VIN format and malformed JSON return 400 and are not charged.
bodyStyleHuman-readable source label such as Combi, Station Wagon, Convertible, or 5-door hatchback.
bodyStyleNormalizedStable integration value such as wagon, hatchback, suv, van, or cabrio.
unknownNo body style was determined.
otherA body style was known but does not fit a supported canonical category.
{
"bodyStyle": "Combi",
"bodyStyleNormalized": "wagon"
}
{
"bodyStyle": "Convertible",
"bodyStyleNormalized": "cabrio"
}Response depth
The response shape stays stable, but premium fields are only included server-side for Starter, Business, and Enterprise access. Free clients never receive locked values in the JSON payload.
Good for evaluation and basic VIN identification.
vinwmivdsmanufacturermodelbodyStylebodyStyleNormalizedmodelYearregionusageDesigned for production integrations that need richer vehicle records.
specs.enginespecs.fuelTypespecs.powerKwspecs.driveTypespecs.displacementCctechnicalSpecs.lengthMmtechnicalSpecs.curbWeightKgtechnicalSpecs.cargoVolumeLitersmetadata.upgradeAvailableUsage limits
When the monthly subscriber limit is reached, decode requests pause until the next reset or until the plan is upgraded.
{
"error": "Monthly subscriber decode limit reached.",
"limit": 25,
"remaining": 0,
"resetAt": "2026-08-01T00:00:00.000Z"
}Response headers
Successful and limited responses include rate-limit headers. Subscriber requests also include the authenticated workspace slug.
X-Vehicode-AuthShows whether the request used an API key or public access.
X-Vehicode-ClientSubscriber workspace slug when an API key is used.
X-RateLimit-LimitPlan limit for authenticated usage.
X-RateLimit-RemainingRequests left in the current usage window.
X-RateLimit-ResetUnix timestamp for the next usage reset.
X-Request-IdSupport/debug identifier when the decode request was stored.
Corrections
Use POST /api/report-decode-issue when your system knows the expected manufacturer, model, body style, model year, and a short note. Reports are queued for admin review.
curl -X POST https://vehicode.eu/api/report-decode-issue \
-H "Content-Type: application/json" \
-H "x-api-key: vdx_your_api_key" \
-d '{
"vin": "WVWZZZAUZHP507470",
"expectedManufacturer": "Volkswagen",
"expectedModel": "Golf",
"expectedBodyStyle": "Combi",
"expectedModelYear": "2017",
"note": "Customer record confirms this is a Golf Variant."
}'