DecodeThis API Documentation

Integrate VIN decoding into your apps with our RESTful Vehicle API — complete vehicle data, specifications, and recall information via JSON or XML.

Get Started Free Quick Start

On This Page

VIN API Quick Start Guide

Get up and running with our Vehicle Identification Number API in minutes. Start decoding vehicle data instantly.

1. Authentication

Get your VIN API key from your dashboard and include it in the Authorization header for Vehicle API authentication.

# Include your API key in requests
curl -H "Authorization: Bearer ak_your_api_key_here" \
  https://api.decodethis.com/v1/vins/1HGBH41JXMN109186/decode
2. Make Your First Request

Decode any 17-character Vehicle Identification Number (VIN) with a simple GET request to our Vehicle API.

# Decode a VIN
GET /api/v1/vins/1HGBH41JXMN109186/decode
# Response
{
  "success": true,
  "data": { "year": 2013, "make": "Honda", ... }
}

Interactive API Documentation

Try our API directly in your browser with Swagger UI. Our interactive documentation is powered by OpenAPI 3.0 — test endpoints, see real responses, and understand request/response schemas in a user-friendly interface.

  • Try It Live — execute API calls directly from the documentation
  • Complete Schemas — detailed request and response object schemas
  • Authentication — test with your own API keys securely
Open Interactive Documentation

Opens in a new tab

API Reference

Complete reference for all available endpoints.

Base URL
https://api.decodethis.com/v1
Subscription-Based API Response Levels

DecodeThis API provides two levels of vehicle data depending on your subscription plan:

Basic VIN Decode

Available for Free, Ad-Free Basic, and Professional plans
  • Standard vehicle information (year, make, model, trim)
  • Engine and transmission details
  • Categorized specifications
  • Country and manufacturer information

Full VIN Decode

Available for Business and Enterprise plans
  • All Basic VIN Decode features
  • Complete raw pattern data
  • Advanced vehicle specifications
  • Detailed trim information and options
  • MSRP and pricing data

Decode VINGET

Decode a Vehicle Identification Number and retrieve comprehensive vehicle information. Response content varies by subscription level.

Endpoint
GET /vins/{vin}/decode
Parameters
ParameterTypeDescription
vinstring (required)17-character Vehicle Identification Number
formatstring (optional)Response format: json (default) or xml
detailstring (optional)Response detail level: minimal, standard (default), or detailed
Example Response — Basic (Free, Professional)
{
  "success": true,
  "data": {
    "vin": "SADCJ2FX2LA628929",
    "year": 2020,
    "make": "Jaguar",
    "model": "F-Pace",
    "trim": "25t Premium",
    "body_style": "SEDAN 4-DR",
    "engine": "2.0L L4 DOHC 16V",
    "transmission": "8-Speed Automatic",
    "drive_type": "AWD",
    "fuel_type": "Gasoline",
    "doors": 4,
    "country": "United Kingdom",
    "manufacturer": "Jaguar",
    "categorized_specifications": {
      "Basic Information": [
        {"category": "Model Year", "value": "2020"},
        {"category": "Make", "value": "Jaguar"},
        {"category": "Model", "value": "F-Pace"}
      ],
      "Engine & Performance": [
        {"category": "Engine Type", "value": "2.0L L4 DOHC 16V"}
      ]
    },
    "data_source": "pattern_export",
    "pattern_matched": "SADCJ2FX L"
  },
  "cached": false,
  "timestamp": "2024-01-15T10:30:00Z"
}
Example Response — Full (Business, Enterprise)
{
  "success": true,
  "data": {
    "vin": "SADCJ2FX2LA628929",
    "year": 2020,
    "make": "Jaguar",
    "model": "F-Pace",
    "trim": "25t Premium",
    "body_style": "SEDAN 4-DR",
    "engine": "2.0L L4 DOHC 16V",
    "transmission": "8-Speed Automatic",
    "drive_type": "AWD",
    "fuel_type": "Gasoline",
    "doors": 4,
    "country": "United Kingdom",
    "manufacturer": "Jaguar",
    "categorized_specifications": {
      "Basic Information": [
        {"category": "Model Year", "value": "2020"},
        {"category": "Make", "value": "Jaguar"},
        {"category": "Model", "value": "F-Pace"}
      ],
      "Engine & Performance": [
        {"category": "Engine Type", "value": "2.0L L4 DOHC 16V"}
      ]
    },
    "data_source": "pattern_export",
    "pattern_matched": "SADCJ2FX L",
    "data": {
      "name": "2020 Jaguar F-Pace",
      "model_year": 2020,
      "manufacturer": "Jaguar",
      "series_name": "F-Pace",
      "regex": "SADCJ2FX L",
      "trims": [
        {
          "name": "25t Premium",
          "vehicle_id": 70316,
          "items": [
            {"category": "Model Year", "value": "2020"},
            {"category": "Make", "value": "Jaguar"},
            {"category": "MSRP", "value": "$47,800"}
          ]
        }
      ]
    }
  },
  "cached": false,
  "timestamp": "2024-01-15T10:30:00Z"
}

Batch Decode VINsPOST

Decode multiple VINs in a single request (up to 100 VINs).

Endpoint
POST /vins/batch_decode
Request Body
{
  "vins": [
    "1HGBH41JXMN109186",
    "2HGFB2F50EH542093",
    "WBXHT93488L100234"
  ],
  "format": "json"
}
Example Response
{
  "success": true,
  "results": [
    {
      "vin": "1HGBH41JXMN109186",
      "success": true,
      "data": { ... }
    },
    {
      "vin": "2HGFB2F50EH542093",
      "success": true,
      "data": { ... }
    },
    {
      "vin": "WBXHT93488L100234",
      "success": false,
      "error": "VIN not found"
    }
  ],
  "total_processed": 3,
  "successful": 2,
  "failed": 1
}

Authentication

Secure your API requests with proper authentication.

API Keys

All API requests require authentication using your API key. Include your API key in the Authorization header using Bearer authentication.

# Example request with authentication
curl -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  https://api.decodethis.com/v1/vins/1HGBH41JXMN109186/decode

Keep your API keys secure

Never expose your API keys in client-side code or public repositories. Store them securely as environment variables.

Rate Limiting

API requests are rate limited based on your subscription plan. Rate limits are enforced per API key.

PlanRequests/MinuteRequests/HourMonthly Limit
Free160100
Ad-Free Basic1601,000
Professional53005,000
Business1060025,000
Enterprise503,000Unlimited

Error Handling

Understand API error responses and status codes.

Error Response Format

All API errors return a consistent JSON response format with detailed error information.

{
  "success": false,
  "error": {
    "code": "VIN_INVALID_FORMAT",
    "message": "VIN must be exactly 17 characters",
    "details": "Provided VIN '1HGBH41JXM' is only 10 characters"
  },
  "request_id": "req_abc123"
}
HTTP Status Codes
200 OK

Request successful, VIN decoded

400 Bad Request

Invalid VIN format or malformed request

401 Unauthorized

Missing or invalid API key

402 Payment Required

Quota exceeded, upgrade required

404 Not Found

VIN not found in database

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error, contact support

503 Service Unavailable

Temporary service outage

SDKs & Code Examples

Get started quickly with our official SDKs and examples.

JavaScript / Node.js
// Using fetch API
const response = await fetch(
  'https://api.decodethis.com/v1/vins/1HGBH41JXMN109186/decode',
  {
    headers: {
      'Authorization': 'Bearer ak_your_api_key_here',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data.data); // Vehicle information

Download JavaScript SDK

Python
import requests

url = "https://api.decodethis.com/v1/vins/1HGBH41JXMN109186/decode"
headers = {
    "Authorization": "Bearer ak_your_api_key_here",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data['data'])  # Vehicle information

Download Python SDK

PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.decodethis.com/v1/vins/1HGBH41JXMN109186/decode',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ak_your_api_key_here',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$data = json_decode($response, true);
print_r($data['data']); // Vehicle information
?>

Download PHP SDK

Ruby
require 'net/http'
require 'json'

uri = URI('https://api.decodethis.com/v1/vins/1HGBH41JXMN109186/decode')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer ak_your_api_key_here'
request['Content-Type'] = 'application/json'

response = http.request(request)
data = JSON.parse(response.body)
puts data['data'] # Vehicle information

Download Ruby SDK

MCP Server for AI Tools

Connect Claude and other AI tools directly to VinDecoder via the Model Context Protocol. Use your existing API key to give AI assistants access to VIN decoding, lookups, and more via /mcp.

Read the MCP integration guide →

Need Help?

Our team is here to help you integrate the DecodeThis API successfully.

  • Documentation — comprehensive guides and API reference
  • Support — get help from our technical support team
  • Community — connect with other developers
Contact Support