YugoVIN API Documentation

Complete guide to integrating our VIN decoding API

Quick Start

Get started with the YugoVIN API in just two steps:

1. Get Your API Key

Sign up for a free account at app.yugovin.com/signup to get your API key.

2. Make Your First Request

curl "https://api.yugovin.com/api/v1/decode/1HGBH41JXMN109186" \
  -H "X-API-Key: your_api_key_here"

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

GET /api/v1/decode/{vin} HTTP/1.1
Host: api.yugovin.com
X-API-Key: your_api_key_here
Security Note: Never expose your API key in client-side code or public repositories.

API Endpoints

GET /api/v1/decode/{vin}

Decode a single VIN and return detailed vehicle information.

Parameters

Name Type Required Description
vin string Yes 17-character Vehicle Identification Number

Example Request

curl "https://api.yugovin.com/api/v1/decode/5UXWX7C5XBA123456" \
  -H "X-API-Key: your_api_key_here"

Example Response

{
  "success": true,
  "data": {
    "vin": "5UXWX7C5XBA123456",
    "year": 2011,
    "make": "BMW",
    "model": "X3",
    "trim": "xDrive35i",
    "body_style": "Sport Utility Vehicle (SUV)",
    "engine": "3.0L 6-cyl",
    "transmission": "Automatic",
    "fuel_type": "Gasoline",
    "manufacturer": "BMW MANUFACTURER CORPORATION"
  },
  "decode_time_ms": 45,
  "cached": true,
  "source": "cache"
}
POST /api/v1/batch-decode

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

Request Body

{
  "vins": [
    "1HGBH41JXMN109186",
    "5UXWX7C5XBA123456",
    "WBAFR7C53BC278899"
  ]
}

Example Request

curl -X POST "https://api.yugovin.com/api/v1/batch-decode" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"vins": ["1HGBH41JXMN109186", "5UXWX7C5XBA123456"]}'
GET /api/v1/validate/{vin}

Validate a VIN without decoding it.

Example Response

{
  "success": true,
  "valid": true,
  "vin": "5UXWX7C5XBA123456",
  "error_message": null
}

Safety Data

Access comprehensive vehicle safety information including recalls, complaints, and technical service bulletins. Safety data is updated weekly from official government databases.

Tier Availability: Safety endpoints require Basic tier or higher. Complaints require Pro tier, and TSBs require Enterprise tier.
GET /api/v1/safety/recalls/{vin}

Get all safety recalls for a vehicle by VIN. Returns official recall campaigns affecting this specific vehicle.

Parameters

Name Type Required Description
vin string Yes 17-character Vehicle Identification Number

Example Request

curl "https://api.yugovin.com/api/v1/safety/recalls/5UXWX7C5XBA123456" \
  -H "X-API-Key: your_api_key_here"

Example Response

{
  "vin": "5UXWX7C5XBA123456",
  "vehicle": {
    "make": "BMW",
    "model": "X3",
    "year": 2011
  },
  "recalls": [
    {
      "campaign_number": "11V579000",
      "component": "AIR BAGS",
      "summary": "BMW is recalling certain model year 2011 X3 vehicles...",
      "consequence": "In the event of a crash, the side airbag may not deploy...",
      "remedy": "Dealers will replace the side airbag modules...",
      "report_received_date": "2011-12-01",
      "potentially_affected": 12500
    }
  ],
  "total_recalls": 1
}
GET /api/v1/safety/recalls/vehicle

Get all safety recalls for a vehicle by make, model, and year. Useful when you don't have the full VIN.

Query Parameters

Name Type Required Description
make string Yes Vehicle manufacturer (e.g., "BMW", "TOYOTA")
model string Yes Vehicle model (e.g., "X3", "CAMRY")
year integer Yes Model year (e.g., 2011)

Example Request

curl "https://api.yugovin.com/api/v1/safety/recalls/vehicle?make=BMW&model=X3&year=2011" \
  -H "X-API-Key: your_api_key_here"
GET /api/v1/safety/complaints/{vin} Pro+

Get owner complaints filed for this vehicle. Includes crash, fire, injury, and fatality data.

Example Response

{
  "vin": "5UXWX7C5XBA123456",
  "vehicle": {
    "make": "BMW",
    "model": "X3",
    "year": 2011
  },
  "complaints": [
    {
      "odi_number": 10456789,
      "component": "ENGINE",
      "summary": "Engine stalls unexpectedly at highway speeds...",
      "date_received": "2015-03-15",
      "crash": false,
      "fire": false,
      "injuries": 0,
      "deaths": 0,
      "mileage": 45000
    }
  ],
  "summary": {
    "total_complaints": 5,
    "crashes": 0,
    "fires": 0,
    "injuries": 0,
    "deaths": 0
  }
}
GET /api/v1/safety/tsbs/{vin} Enterprise

Get Technical Service Bulletins (TSBs) for this vehicle. TSBs are issued by manufacturers to address common issues.

Example Response

{
  "vin": "5UXWX7C5XBA123456",
  "vehicle": {
    "make": "BMW",
    "model": "X3",
    "year": 2011
  },
  "tsbs": [
    {
      "tsb_id": "SI B11 01 11",
      "component": "ELECTRICAL SYSTEM",
      "summary": "Software update to address intermittent warning light...",
      "date_issued": "2011-06-15"
    }
  ],
  "total_tsbs": 12
}
GET /api/v1/safety/summary/{vin}

Get a combined safety summary including recalls, complaint statistics, and TSB counts for a vehicle. Returns counts based on your subscription tier.

Example Response

{
  "vin": "5UXWX7C5XBA123456",
  "vehicle": {
    "make": "BMW",
    "model": "X3",
    "year": 2011
  },
  "summary": {
    "recalls": {
      "total": 3,
      "available": true
    },
    "complaints": {
      "total": 15,
      "crashes": 1,
      "fires": 0,
      "injuries": 0,
      "deaths": 0,
      "available": true
    },
    "tsbs": {
      "total": 12,
      "available": false
    }
  },
  "safety_score": "moderate",
  "tier_restrictions": {
    "complaints_detail": "pro",
    "tsbs_detail": "enterprise"
  }
}

Data Coverage

Our safety database includes:

Dataset Records Coverage Update Frequency
Recalls 231,000+ 1966 - Present Weekly
Complaints 1,550,000+ 1995 - Present Weekly
TSBs 50,000+ 2000 - Present Weekly

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Code Status Description
200 OK Request successful
400 Bad Request Invalid VIN or parameters
401 Unauthorized Invalid or missing API key
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error - contact support

Error Response Format

{
  "success": false,
  "error": "Invalid VIN format",
  "detail": "VIN must be exactly 17 characters"
}

Rate Limits & Pricing

Rate limits and pricing vary by subscription plan:

Plan Price Requests/Second Monthly Quota Overage Rate
Demo Free 1 50 -
Starter $15/mo 2 500 4.5¢/decode
Basic $49/mo 5 2,000 3.7¢/decode
Pro $199/mo 20 10,000 3.0¢/decode
Scale $999/mo 50 50,000 2.5¢/decode
Enterprise Custom Unlimited Unlimited Custom
Overage Billing: When you exceed your monthly quota, additional decodes are billed at your plan's overage rate. You'll only pay for what you use beyond your included limit.
Generous Upgrades: When you upgrade your plan, you immediately receive your full new quota. For example, upgrading from Starter (500) to Pro (10,000) mid-month gives you the full 10,000 decodes right away. Downgrades take effect at your next billing cycle.

Rate limit information is included in response headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1640000000

Code Examples

Python

import requests

API_KEY = "your_api_key_here"
VIN = "5UXWX7C5XBA123456"

response = requests.get(
    f"https://api.yugovin.com/api/v1/decode/{VIN}",
    headers={"X-API-Key": API_KEY}
)

vehicle = response.json()["data"]
print(f"{vehicle['year']} {vehicle['make']} {vehicle['model']}")
# Output: 2011 BMW X3

JavaScript (Node.js)

const axios = require('axios');

const API_KEY = 'your_api_key_here';
const VIN = '5UXWX7C5XBA123456';

async function decodeVIN() {
  try {
    const response = await axios.get(
      `https://api.yugovin.com/api/v1/decode/${VIN}`,
      {
        headers: { 'X-API-Key': API_KEY }
      }
    );
    
    const vehicle = response.data.data;
    console.log(`${vehicle.year} ${vehicle.make} ${vehicle.model}`);
    // Output: 2011 BMW X3
  } catch (error) {
    console.error('Error:', error.message);
  }
}

decodeVIN();

PHP

<?php
$api_key = 'your_api_key_here';
$vin = '5UXWX7C5XBA123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yugovin.com/api/v1/decode/$vin");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("X-API-Key: $api_key"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$vehicle = $data['data'];

echo "{$vehicle['year']} {$vehicle['make']} {$vehicle['model']}\n";
// Output: 2011 BMW X3
?>