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
Decode a VIN into available vehicle identification, specifications, and usage data. A populated manufacturer identifies the vehicle make; without it, treat the result as VIN parsing. Free access provides basic information. Starter and Business can include extended technical data where available.
Response metadata describes what was returned: verifiedTechnicalFields, estimatedTechnicalFields, and possibleConfigurationsCount count their respective results. publishedSupplementalFields counts additional vehicle fields in the response. The legacy premiumFieldsAvailable count also includes premium values not shown on the current plan.
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
{
"status": "decoded",
"requestId": "8e24ce52-cc7b-46f2-a42a-dfc77fd23f9d",
"isFinal": true,
"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.
Enrichment can take tens of seconds. A pending response is not final: poll the returned relative URL with the same API key, honor Retry-After, and stop when isFinal is true. Polling does not create another logical decode or add another charge; a usable completed decode is charged at most once.
Pending response
{
"requestId": "ddfdc2d7-cbb0-4e24-9b9b-afd109ba23c4",
"status": "enrichment_pending",
"isFinal": false,
"retryAfterSeconds": 15,
"pollUrl": "/api/decode/ddfdc2d7-cbb0-4e24-9b9b-afd109ba23c4",
"usageCharged": false
}Poll with curl
curl https://vehicode.eu/api/decode/ddfdc2d7-cbb0-4e24-9b9b-afd109ba23c4 \\ -H "x-api-key: vdx_your_api_key"
TypeScript helper
async function waitForDecode(initial, apiKey) {
let result = initial;
while (!result.isFinal) {
await new Promise((resolve) =>
setTimeout(resolve, result.retryAfterSeconds * 1000)
);
const response = await fetch(
'https://vehicode.eu' + result.pollUrl,
{ headers: { 'x-api-key': apiKey } }
);
result = await response.json();
}
return result;
}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
Free responses include basic vehicle information. Starter and Business can include additional specifications and configurations where available for the VIN.
Basic VIN and vehicle identification, when available.
vinwmivdsmanufacturermodelbodyStylebodyStyleNormalizedmodelYearregionusageExtended vehicle and technical data where available.
specs.enginespecs.fuelTypespecs.powerKwspecs.driveTypespecs.displacementCctechnicalSpecs.lengthMmtechnicalSpecs.curbWeightKgtechnicalSpecs.cargoVolumeLitersmetadata.upgradeAvailableTechnical certainty
specs and technicalSpecs contain confirmed technical values. Some dimensions and weights may apply to a model or variant.estimatedSpecs contains supported inferences, not confirmed facts. Each value has a type and confidence, never a percentage.possibleConfigurations lists supported alternatives, not the exact vehicle build. engineCode: "UNKNOWN" means the engine code is unavailable; coverage: "partial" means the list is not exhaustive.{
"specs": {
"fuelType": "Gasoline"
},
"estimatedSpecs": {
"powerKw": {
"value": 95,
"type": "estimated",
"confidence": "high"
},
"curbMassKg": {
"min": 1450,
"max": 1825,
"type": "range",
"confidence": "medium"
}
}
}Attribution
Where applicable, VehiCode uses vehicle type-approval data from the Swiss Federal Roads Office (ASTRA/FEDRO) TAS open dataset. Responses using this data include an X-Data-Attribution header.
Usage 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."
}'