API Documentation

 

VINdecode API 2.0 (Coding Examples)


Our VINdecode API provides detailed vehicle specifications based on the submitted vehicle identification number (VIN). These specifications include the year, make, model, engine and transmission details, color, and both standard and optional equipment. This API method supports the submission of one VIN at a time and returns comprehensive specifications. The returned data includes the vehicle's country of origin, year/make/model details, engine and powertrain specifics, manufacturer-included options, and other specifications such as gross vehicle weight (GVW) and MSRP.


Our records show that some users with unlimited access to the VINdecode API tend to make excessive and sometimes unnecessary API calls. To maintain the overall health of our system, we may block traffic from a specific source once it reaches a certain level. This ensures that one user's actions do not negatively impact the larger community. We reserve the right to throttle excessive API calls or even refuse service if necessary.

 

REST API Description

Our VINdecode API provides programmatic access to our VIN decode database.

Parameter Name Parameter Value Used in URL
API Key * accesscode * xxxxx-xxxxx-xxxxx-xxxxx GET https://ws.vinquery.com/vindecode/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3
Vehicle Identification Number * vin * XXXXXXXXXXXXXXXXX GET https://ws.vinquery.com/vindecode/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3
Data Type * reporttype * 0, 1, 2, 3 GET https://ws.vinquery.com/vindecode/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3
Partial VIN ** partialvin ** TRUE or FALSE (default: FALSE) GET https://ws.vinquery.com/vindecode/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3&partialvin=TRUE
Data Format format XML or Json (default: XML) GET https://ws.vinquery.com/vindecode/v2?accesscode=xxxxx-xxxxx-xxxxx-xxxxx&vin=XXXXXXXXXXXXXXXXX&reporttype=3&partialvin=TRUE&format=json
* These three parameters are mandatory.
** Set the optional parameter "partialvin" to "TRUE" if you'd like our system NOT to validate the VIN. The system will NOT do checksum test before submitting the VIN to our decoding engine for processing. Set the value of this parameter to "FALSE" otherwise.

Data Types

Data Code Data Type Data Format
0 Basic Data ws_vindecode_bas.xml  |   ws_vindecode_bas.json
1 Standard Data ws_vindecode_std.xml  |   ws_vindecode_std.json
2 Extended Data ws_vindecode_ext.xml  |   ws_vindecode_ext.json
3 Lite Data ws_vindecode_lit.xml  |   ws_vindecode_lit.json

Lookup Tables

These tables are static. They don't change often, if at all.

Body Style Show the complete list of all possible body styles used in our system.
COUPE 2-DR CREW CAB PICKUP 4-DR CROSSOVER 4-DR EXTENDED CAB PICKUP 4-DR HATCHBACK 2-DR HATCHBACK 4-DR PASSENGER VAN REGULAR CAB PICKUP 2-DR SEDAN 4-DR SPORT UTILITY 4-DR SPORTS VAN WAGON 4-DR WAGON 5-DR
Vehice Type Show the complete list of all possible vehicle types used in our system.
BUS MOTORCYCLE MPV PASSENGER RECREATIONAL TRAILER VAN LOW SPEED VEHICLE ELECTRIC VEHICLE DUMP TRUCK TRACTOR TRUCK SNOWMOBILE ATV
Fuel Type
CNG DIESEL ELECTRIC FFV GAS HYBRID PLUG-IN HYBRID HYDROGEN LPG No data
Engine Shape
H12 H4 H6 L2 L3 L4 L5 L6 No data NO ENGINE ROTARY V10 V12 V20 V4 V6 V8 VL W12 W16 W8
Driveline
10X4 10X6 12X6 4WD 4X2 4X4 6X2 6X4 8X4 8X6 AWD FWD FWD | AWD RWD RWD | AWD 2WD No data

Error Codes

Error Code (Key) Description (Value)
0 Database Errors.
2 Valid VIN number. However, no data available for it at this moment.
3 Invalid VIN number: This VIN number did not pass checksum test
4 Invalid VIN number: A valid VIN number must be exactly 17 digits
5 Invalid VIN number: This VIN number contains invalid letters: I,O or Q.
6 Invalid report type. A valid report type should be 0 for BASIC, 1 for STANDARD, 2 for EXTENDED or 3 for LITE.
8 Service access denied: Double check your Access Code.
9 Report type missing: A report type (0,1,2 or 3) must be specified.
10 Insufficient balance for Basic Reports.
11 Insufficient balance for Standard Reports.
12 Insufficient balance for Extended Reports.
13 VIN missing: A VIN must be submitted as part of the querystring.
14 Invalid VIN number: The 10th digit of a VIN number cannot be letter U, letter Z or number 0.
15 Insufficient balance for Lite Reports.
16 A VIN can only contain alphanumeric characters. 
                    
A sample error message returned in XML format:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<VINdecode version="2.0" report_type="EXTENDED" Date="8/27/2022">
  <VIN number="1FTRF02W24KXXXXXX" status="FAILED">
    <Message Key="3" Value="Invalid VIN number: This VIN number did not pass checksum test." />
  </VIN>
</VINdecode>
        

                    
A sample error message returned in Json format:

{
  "service": "vindecode",
  "version": "2.0",
  "date": "8/27/2022",
  "vin": "1FTRF02W24KXXXXXX",
  "status": "FAILED",
  "message_key": "3",
  "message": "Invalid VIN number: This VIN number did not pass the checksum test."
}

Known Issues

  • A single VIN returns data related to multiple trim levels.

    • Occasionally, information coded by the manufacturer in a submitted VIN may not be sufficient for our VIN decode engine to narrow it down to a single trim level so all available records for that particular VIN will be returned. In this case, all available trim levels may have to be presented to end users so they can make a selection from those returned choices.

  • A single trim level returns multiple transmissions, exterior colors, interior trims, ABS(Non-ABS |* 2-Wheel ABS |* 4-Wheel ABS) etc.

    • For instance, a decoded VIN may offer all exterior color choices that were available for a particular vehicle, but can't tell you what color the vehicle actually is - therefore all available color choices for the vehicle might have to be presented to end users so they can select the color or have the option to enter another color choice in case the vehicle was painted over.

    * "|" is used as a delimiters or separator when a data item contains multiple choices.

Coding Examples

JavaScript(Python, C#, Java, PHP, Swift) 

    <html>
        <head></head>
        <body>
            <form id = "form">
                <label>Please input a VIN:<input type="text" id ="input"></label>
                <br>
                <a href="javascript: fetchResponseXml()">Submit (XML Output)</a>
                <br>
                <a href="javascript: fetchResponseJson()">Submit (Json Output)</a>
            </<form>
            <pre id="out"></pre>
        </body>

        <script>
            const form=document.getElementById("form")
            const out=document.getElementById("out")

        // Javascript XML 
            async function fetchResponseXml(){
                const url="https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&reportType=YOUR_REPORT_TYPE&format=xml;
                var parser=new DOMParser();
                var xmlHttp=new XMLHttpRequest();
                xmlHttp.open("GET", url, false);
                xmlHttp.send();
                var xmlResponse=parser.parseFromString(xmlHttp.responseText, "text/xml");
                console.log(xmlResponse)

                var text="";
                var children=xmlResponse.documentElement.childNodes;
                for (var i=0; i < children.length; i++){
                    console.log(children)
                    // text += children[i].tagName+": "+children[i].textContent+"\n"
                    text += children[i].nodeName+": "+children[i].textContent+"\n"
                }
                out.textContent=text;
            }

        // Javascript Json
            async function fetchResponseJson(){
                const url="https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&reportType=YOUR_REPORT_TYPE&format=json";
                fetch(url).then(function(response){
                    return response.json()
                }).then(function(data){
                    let text="";
                    for (let x in data){
                        text+=x+": "+data[x]+"\n";
                    }   
                    out.textContent=text;
                }).catch(function(){
                    out.textContent="Something went wrong..."
                });
            }
        </script>
    </html>
Python(JavaScript, C#, Java, PHP, Swift) 

    import xml.etree.ElementTree as ET
    import requests

    
    url="https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN";
    response = requests.get(url)
    xml = ET.fromstring(response.content.decode('UTF-8'))

    output = "Model Year: " + xml[0][0].attrib['Model_Year'] + "\n"
    output += "Make: " + xml[0][0].attrib['Make'] + "\n"
    output += "Model: " + xml[0][0].attrib['Model'] + "\n"
    output += "Trim Level: " + xml[0][0].attrib['Trim_Level']
    ...
    print(output)




    import requests
    import json

    url="https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&vin=YOUR_VIN&reportType=YOUR_REPORT_TYPE&format=json"

    response = requests.get(url)
    result=response.json()

    print(result)

    if result["status"]=="SUCCESS":
        print("Service: "+result["service"])
        print("Version: "+result["version"])
        print("Date: "+result["date"])
        print("Status: "+result["status"])
        vehicles=result["vehicles"]
        for vehicle in vehicles:
            print(vehicle["VINquery_Vehicle_ID"]["value"])
            print(vehicle["Model Year"]["value"])
            print(vehicle["Make"]["value"])
            print(vehicle["Model"]["value"])
            print(vehicle["Trim Level"]["value"])
    else:
        print("Service: "+result["service"])
        print("Version: "+result["version"])
        print("Date: "+result["date"])
        print("Status: "+result["status"])
        print("Message Key: "+str(result["message_key"]))
        print("Message: "+result["message"])
C#(JavaScript, Python, Java, PHP, Swift) 

    // C# XML

    using System;
    using System.Net;
    using System.Xml;

    String url="https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN&format=xml";    

    String responseString = client.DownloadString(url);

    Console.WriteLine("XML Output (Parsed): \n");

    var xmlResponse = new XmlDocument();
    xmlResponse.LoadXml(responseString);

    foreach (XmlNode node in xmlResponse.DocumentElement.ChildNodes)
    {
        Console.WriteLine(node.Name + ": " + node.InnerText);
    }




    // C# Json 

    using System;
    using System.Net;
    using Newtonsoft.Json.Linq;

    String url="https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN&format=json";
    String responseString = client.DownloadString(url);

    Console.WriteLine("\nJSON Output (Parsed): \n");

    JObject jsonResponse = JObject.Parse(responseString);

    foreach (var node in jsonResponse)
    {
        Console.WriteLine(node.Key + ": " + node.Value);
    }
Java(JavaScript, Python, C#, PHP, Swift) 

    // Java XML
    import java.io.BufferedReader;
    import java.io.InputStreamReader;
    import java.io.StringReader;
    import java.net.HttpURLConnection;
    import java.net.URL;

    import org.w3c.dom.Document;
    import org.w3c.dom.Node;
    import org.w3c.dom.NodeList;
    import org.xml.sax.InputSource;
    import javax.xml.parsers.*;

    String response = "";
    URL url = new URL("https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN&format=xml");
    final HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setRequestMethod("GET");
    BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream()));
    StringBuilder sb = new StringBuilder();
    while ((response = br.readLine()) != null) {
        sb.append(response);
    }

    response = sb.toString();
    con.disconnect();

    System.out.println(response);
    String output = "";
    output = parseXML(response);
    System.out.println(output);

    private static String parseXML(String response) {
        String output = "";
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
        DocumentBuilder builder = factory.newDocumentBuilder();
        Document document = builder.parse(new InputSource(new StringReader(response)));
        document.getDocumentElement().normalize();

        NodeList list = document.getFirstChild().getChildNodes();
        Node node;
        for (int i = 0; i < list.getLength(); i++) {
            node = list.item(i);
            if (node.getNodeType() == Node.ELEMENT_NODE) {
                output += node.getNodeName() + ": " + node.getTextContent() + "\n";
            }
        }

        return output;
    }



                

    // Java Json
    import java.io.BufferedReader;
    import java.io.InputStreamReader;
    import java.io.StringReader;
    import java.net.HttpURLConnection;
    import java.net.URL;

    import org.json.JSONArray;
    import org.json.JSONObject;

    String response = "";
    URL url = new URL("https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN&format=json");
    final HttpURLConnection con = (HttpURLConnection) url.openConnection();
    con.setRequestMethod("GET");
    BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream()));
    StringBuilder sb = new StringBuilder();
    while ((response = br.readLine()) != null) {
        sb.append(response);
    }

    response = sb.toString();
    con.disconnect();

    System.out.println(response);
    String output = "";
    output = parseJSON(response);
    System.out.println(output);

    private static String parseJSON(String response) {
        String output = "";
        JSONObject jsonObject = new JSONObject(response.trim());
        JSONArray names = jsonObject.names();

        for (int i = 0; i < names.length(); i++) {
            output += names.getString(i) + ": " + jsonObject.get(names.getString(i)) + "\n";
        }
        return output;
    }
PHP(JavaScript, Python, C#, Java, Swift) 

    // PHP XML

    <?php

    $response = file_get_contents('http://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN&format=xml');
    $response = new SimpleXMLElement($response);
    $string = $response -> asXML();

    echo($string);

    foreach($response -> VIN -> Vehicle -> Item as $Item) {
        echo $Item['Key'], ': ', $Item['Value'], ' ';
    }

    ?>


                
    // PHP Json

    <?php

    $response = file_get_contents("http://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN&format=json");

    echo($response);

    $json = json_decode($response, true);
    foreach ($json as $key => $value) {
        echo($key.": ".$value."\n");
    }

    ?>
Swift(JavaScript, Python, C#, Java, PHP) 

    // Swift XML

    import UIKit

    if let url = URL(string: "https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN") {
        do {
            let contents = try String(contentsOf: url)
            print(contents)
        } catch {
            print("contents of the URL couldn't be loaded")
        }
    } else {
        print("bad URL, try again")
    }


                
    // Swift Json

    import UIKit

    if let url = URL(string:"https://ws.vinquery.com/vindecode/v2?accesscode=YOUR_ACCESS_CODE&reportType=YOUR_REPORT_TYPE&vin=YOUR_VIN&format=json") {
        do {
            let contents = try String(contentsOf: url)
            print(contents)
        } catch {
            print("contents of the URL couldn't be loaded")
        }
    } else {
        print("bad URL, try again")
    }