API Documentation
Overview
The VIN Decoding API provides programmatic access to OEM factory build sheet data. The API uses an asynchronous request/response pattern optimized for high-volume operations.
Typical latency: 25-30 seconds end-to-end depending on OEM response time.
Built for automation at scale
Our API is designed for high-volume VIN decoding operations, delivering comprehensive factory data programmatically.
Asynchronous Processing
Submit requests and receive results via webhooks. Typical end-to-end latency is 25-30 seconds depending on OEM response.
Reliable Authentication
Secure API key authentication with rotation and revocation capabilities. Manage keys directly from your dashboard.
RESTful Design
Simple, predictable REST API with JSON responses. Clear error codes and comprehensive documentation.
Transparent Billing
Only successful decodes are billed. Track usage in real-time with detailed reporting and analytics.
Base URL & Versioning
All API requests should be made to this base URL. The API version is included in the path.
Authentication
Authenticate your requests using an API key passed in the Authorization header.
Core Concepts
Request Lifecycle
- Submit a VIN decode request (returns request ID)
- Request status changes: pending → processing → decoded or failed
- Receive webhook notification when complete (recommended)
- Alternatively, poll the status endpoint
Billable vs Non-Billable
- Billable: Status = "decoded" (OEM data returned)
- Not billable: Status = "failed" (no OEM data)
Create Decode Request
Create a new VIN decode request.
Request Body
Response
Get Request Status
Retrieve the current status and results of a decode request.
Response (Completed)
Error Codes
Invalid VIN format or missing required fields
Invalid or missing API key
Request ID does not exist
Rate limit exceeded
Webhooks
Webhooks allow you to receive real-time notifications when decode requests are completed. This is the recommended approach for high-volume operations.
Webhook Event
Your webhook endpoint should respond with a 2xx status code to acknowledge receipt. Failed deliveries will be retried with exponential backoff.
API Output Scope
Each successful decode returns comprehensive OEM factory data structured as follows:
Vehicle identification
Complete make, model, year, and variant information for accurate vehicle identification.
Market & production data
Market and production attributes where available from manufacturer records.
Powertrain specifications
Detailed engine, transmission, drivetrain, and fuel system information from factory data.
OEM build sheet
Complete equipment codes with human-readable descriptions from the original manufacturer.
Key unit identifiers
Essential unit identifiers for supported OEMs, enabling precise parts matching and technical lookups.