Developer Reference
Everything you need to integrate VINrichment into your application. Simple REST API, JSON responses, API key authentication.
All API requests require an API key sent via the X-Api-Key header.
X-Api-Key: your_api_key_here
Content-Type: application/json
Accept: application/jsonGetting an API Key
API keys are issued on request. Contact us to get your key. Each key has a configurable rate limit and can be scoped to specific data segments.
https://backend.datadyne.dev/api/vinrichmentAll endpoints below are relative to this base URL.
Get your first decode running in under 5 minutes.
Step 1
Request access through contact. Keys are issued with plan and attribute scope settings.
Step 2
Send a 17-character VIN to /decode with your API key in the X-Api-Key header.
Step 3
Use structured segment objects for vehicle identity, engine, shop specs, and service interval data.
Step 4
Handle 429 and 5xx retries, persist decoded VINs, and use attribute filtering for smaller payloads.
curl -X POST https://backend.datadyne.dev/api/vinrichment/decode \
-H "X-Api-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"vin":"1HGCV1F33LA000001"}'| Method | Endpoint | Description |
|---|---|---|
| POST | /decode | Decode a single VIN |
| GET | /stats | Get database statistics and coverage info |
Decode a single VIN and get complete vehicle data with enriched service specifications.
| Parameter | Type | Required | Description |
|---|---|---|---|
| vin | string | Yes | 17-character Vehicle Identification Number |
curl -X POST https://backend.datadyne.dev/api/vinrichment/decode \
-H "X-Api-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"vin": "1HGCV1F33LA000001"}'{
"success": true,
"data": {
"vin": "1HGCV1F33LA000001",
"cached": false,
"segments": {
"vehicle": {
"year": 2020,
"make": "Honda",
"model": "Accord",
"trim": "Sport 1.5T",
"body_class": "Sedan/Saloon"
},
"manufacturing": {
"manufacturer": "Honda",
"plant_city": "Marysville",
"plant_state": "Ohio",
"plant_country": "United States"
},
"engine": {
"displacement_l": "1.5",
"fuel_type": "Gasoline",
"horsepower": "192",
"cylinders": "4",
"engine_configuration": "In-Line",
"turbo": "Yes"
},
"transmission": {
"type": "CVT",
"speeds": "1"
},
"drivetrain": {
"drive_type": "FWD"
},
"dimensions": {
"wheelbase_in": "111.4",
"overall_length_in": "192.2",
"overall_width_in": "73.3",
"overall_height_in": "57.1"
},
"weight": {
"curb_weight_lb": "3131",
"gvwr_lb": "4354"
},
"fuel": {
"fuel_type_primary": "Gasoline"
},
"safety": {
"abs": "Standard",
"esc": "Standard",
"tpms": "Direct",
"backup_camera": "Standard"
},
"airbags": {
"front": "1st Row (Driver and Passenger)",
"side": "1st and 2nd Rows",
"curtain": "1st and 2nd Rows",
"knee": "1st Row (Driver and Passenger)"
},
"shop_specs": {
"fluids": {
"engine_oil_type": "0W-20 Full Synthetic",
"engine_oil_capacity": "3.4 quarts (with filter)",
"coolant_type": "Honda Type 2 (Blue)",
"brake_fluid": "DOT 3",
"transmission_fluid": "Honda HCF-2"
},
"torque_specs": {
"lug_nuts": "80 ft-lbs",
"oil_drain_plug": "29 ft-lbs",
"spark_plugs": "13 ft-lbs"
},
"tires_wheels": {
"front_tire_size": "225/50R17",
"rear_tire_size": "225/50R17",
"tire_pressure_psi": "33",
"bolt_pattern": "5x114.3"
},
"electrical": {
"battery_group": "51R",
"battery_cca": "410"
}
},
"service_intervals": {
"oil_change": "7,500 miles / 12 months",
"brake_inspection": "15,000 miles",
"coolant_flush": "60,000 miles / 5 years",
"spark_plugs": "60,000 miles",
"transmission_fluid": "60,000 miles"
}
}
}
}Get database statistics including total vehicles, VIN lookups, and coverage information. No API key required.
curl https://backend.datadyne.dev/api/vinrichment/stats{
"total_vehicles": 12847,
"total_lookups": 3291,
"unique_makes": 48,
"year_range": {
"min": 1981,
"max": 2026
},
"service_specs_count": 856,
"cache_hit_rate": "73.2%"
}Each decoded VIN returns data organized into structured segments. Here's what's included in each:
Core vehicle identification data.
Engine specifications and performance data.
OEM fluid types and capacities.
Torque specifications with units for common service points.
OEM tire and wheel specifications.
Battery and electrical system specifications.
Manufacturer-recommended service intervals.
Assembly plant and manufacturer details.
Transmission type and configuration.
Drive type configuration.
Vehicle dimensions and measurements.
Curb weight and gross vehicle weight rating.
Primary fuel type information.
Active safety systems and driver assistance features.
Airbag locations and coverage.
All errors return a consistent JSON structure with an appropriate HTTP status code.
{
"success": false,
"error": "Invalid VIN format. Must be 17 characters."
}| HTTP Code | Meaning | Common Cause |
|---|---|---|
| 400 | Bad Request | Invalid VIN format or missing fields |
| 401 | Unauthorized | Missing or invalid API key |
| 429 | Too Many Requests | Rate limit exceeded for this API key |
| 500 | Server Error | Internal error — contact support |
Each API key has a monthly lookup limit. Cached VINs (repeat lookups of previously decoded VINs) do not count against your rate limit.
Pro Tip
VINs are cached after the first lookup. If you decode the same VIN again, it returns instantly and doesn't count against your rate limit. This lets you re-query vehicles you've already looked up without consuming additional lookup volume.
Use exponential backoff for transient 5xx responses. Respect 429 limits and avoid immediate retry storms.
Persist VIN results in your application cache to reduce round trips and protect your monthly lookup budget.
Reject VINs that are not 17 characters before calling the API to prevent avoidable request failures.
Request only the fields your workflow needs for faster responses and cleaner data contracts.