docs / api / vin / decoder

VIN Decoder API

The VIN Decoder API provides access to a library of vehicle specifications data covering attributes, color options, equipment details, recall information, warranties, and photos. See below for the complete documentation details. A “selections” request can be used to retrieve lists of vehicles based on their year, make, model, trim, style, or ID. Get started today with an active VinAudit API key. HTTPS calls are made to (specifications.vinaudit.com).

FUNCTION #1: Get Vehicle Specifications

Get vehicle attributes, equipment, colors, recalls, warranties, photos, and more by VIN, YMMT, or ID. To retrieve vehicle specifications using GET or POST parameters, request:

GET
https://specifications.vinaudit.com/v3/specifications?

Request Parameters
When searching by VIN

Parameter

vin

required

Example

1NXBR32E85Z505904

Description

The vehicle identification number

Parameter

include

optional

Example

selections, attributes, equipment, colors, recalls, warranties, photos

Description

Type of data to be included in the response

Parameter

key

required

Example

YOUR_API_KEY_HERE

Description

Your VinAudit API key

Parameter

format

optional

Example

json

Description

The output format: json or xml

When searching by YMMT

Parameter

year

required

Example

2004

Description

The selected vehicle year

Parameter

make

required

Example

toyota

Description

The selected vehicle make

Parameter

model

required

Example

corolla

Description

The selected vehicle model

Parameter

trim

optional

Example

ce

Description

The selected vehicle trim

Parameter

include

optional

Example

selections, attributes, equipment, colors, recalls, warranties, photos

Description

Type of data to be included in the response

Parameter

key

required

Example

YOUR_API_KEY_HERE

Description

Your VinAudit API key

Parameter

format

optional

Example

json

Description

The output format: json or xml

When searching by ID

Parameter

id

required

Example

id=2004_toyota_corolla_ce id=2013_bmw_3series_328i_sedan

Description

Unique identifier associated with each of the following attribute combinations:
year_make_model_trim
year_make_model_trim_style

Parameter

include

optional

Example

selections, attributes, equipment, colors, recalls, warranties, photos

Description

Type of data to be included in the response

Parameter

key

required

Example

YOUR_API_KEY_HERE

Description

Your VinAudit API key

Parameter

format

optional

Example

json

Description

The output format: json or xml

Response Attributes

Parameter

input

Example

{"key":"YOUR_API_KEY_HERE","vin":"1NXBR32E85Z505904","format":"json","include":"selections,attributes"}

Description

Contains the input parameters specified by the query

Parameter

selections

Example

{ "trims": [ { "id": "2013_bmw_3series_328i", "name": "328i", "selected": 1, "styles": [ { "id": "2013_bmw_3series_328i_sedan", "name": "Sedan", "selected": 1 } ] } ] }

Description

Contains the trim IDs, trim names, style IDs, and style names

Parameter

attributes

Example

{"year":"2004","make":"Toyota","model":"Corolla","trim":"S","style":"","type":"Car","size":"Compact","category":"Compact Cars","made_in":"America","made_in_city":"Cambridge","doors":"4","fuel_type":"Regular Unleaded","fuel_capacity":"13.20 gallons","city_mileage":"30 – 32 miles/gallon","highway_mileage":"38 – 41 miles/gallon","engine":"1.8-L L-4 DOHC 16V","engine_size":"1.8-L","engine_cylinders":"L-4","transmission":"4-Speed Automatic 5-Speed Manual","transmission_type":"Manual","transmission_speeds":"5-Speed"}

Description

A map of specifications about the VIN (VIN, Year, Make, Model, Trim, Trim Selections, Style, Type, Size, Category, Made In, Made In City, Doors, Fuel Type, Fuel Capacity, CityMileage, Highway Mileage, Engine, Engine Size, Engine Cylinders, Transmission, Transmission Type, Transmission Speeds, Drivetrain, Anti-Brake System, Steering Type, Curb Weight, Gross Weight, Gross Vehicle Weight Rating, Overall Height, Overall Length, Overall Width, Wheelbase Length, Standard Seating, Invoice Price, Delivery Charges, Manufacturer Suggested Retail Price)

Parameter

colors

Example

[{"category":"Exterior","name":"Super White"},{"category":"Exterior","name":"Silver Streak Mica"},{"category":"Exterior","name":"Impulse RED"},{"category":"Exterior","name":"Black Sand Pearl"},{"category":"Exterior","name":"Indigo INK Pearl"},{"category":"Exterior","name":"Phantom Gray Pearl"}]

Description

Details about available color options based on the vehicle’s year, make, model

Parameter

equipment

Example

[ { "group": "Anti-Theft & Locks", "name": "Child Safety Door Locks", "availability": "Standard" }, { "group": "Braking & Traction", "name": "ABS Brakes", "availability": "Optional" }, { "group": "Safety", "name": "Driver Airbag", "availability": "Standard" }, { "group": "Climate Control", "name": "Air Conditioning", "availability": "Standard" }, { "group": "Exterior Lighting", "name": "Daytime Running Lights", "availability": "Standard" }, { "group": "Chassis", "name": "Steering Type", "value": "R&P" }, { "group": "Interior Dimensions", "name": "Front Headroom", "value": "39.10 In." }, { "group": "Capacities", "name": "Standard Seating", "value": "5" } ]

Description

Details about a vehicle’s equipment based on the vehicle’s year, make, model

Parameter

recalls

Example

[{"source":"NHTSA","campaign":"15V285000","date":"20150513","components":"AIR BAGS","summary":"Toyota Motor Engineering & Manufacturing (Toyota) notified the agency on May 13, 2015 that they are recalling certain model year…"}]

Description

Details about recall information based on the vehicle’s year, make, model, and trim

Parameter

warranties

Example

[{"type":"Basic","miles":"36,000 miles","months":"36 months"},{"type":"Powertrain","miles":"60,000 miles","months":"60 months"},{"type":"Rust","months":"60 months","miles":"Unlimited miles"}]

Description

Details about manufacturer warranties based on the vehicle’s year, make, model, and trim

Parameter

photos

Example

[{"url":"https://imgset.info/a/1NXBR38E74Z195377_20190205_0-43001?size=medium"},{"url":"https://imgset.info/a/1NXBR32E04Z192720_20190205_0-46560?size=medium"},{"url":"https://imgset.info/a/JTDBR32E042024060_20190205_0-44966?size=medium"}]

Description

Photos based on the vehicle’s year, make, model, and trim

Parameter

success

Example

true

Description

Whether vehicle specifications data exists

Parameter

error

Example

invalid_vin

Description

One of the following error codes:
invalid_inputs (missing VIN, ID, or year/make/model/trim)
invalid_vin (not a valid VIN)
no_data (no specifications available)
api_not_enabled (functionality not enabled for API key)
(blank if no error)

Example 1: Get by VIN (successful request XML)

REQUEST:
https://specifications.vinaudit.com/v3/specifications?
format=xml
&key=YOUR_API_KEY_HERE
&vin=1NXBR32E85Z505904


RESPONSE:

<result>
  <input>
    <key>YOUR_API_KEY_HERE</key>
    <vin>1NXBR32E85Z505904</vin>
    <format>xml</format>
  </input>
  <selections>
    <trims>
      <trim>
        <id>2005_toyota_corolla_s</id>
        <name>S</name>
        <selected>1</selected>
        <styles/>
      </trim>
      <trim>
        <id>2005_toyota_corolla_ce</id>
        <name>CE</name>
        <styles/>
      </trim>
      <trim>
        <id>2005_toyota_corolla_le</id>
        <name>LE</name>
        <styles/>
      </trim>
    </trims>
  </selections>
  <attributes>
    <year>2005</year>
    <make>Toyota</make>
    <model>Corolla</model>
    <trim>S</trim>
    <style/>
    <type>Car</type>
    <size>Compact</size>
    <category>Compact Cars</category>
    <made_in>America</made_in>
    <made_in_city>Cambridge</made_in_city>
    <doors>4</doors>
    <fuel_type>Regular Unleaded</fuel_type>
    <fuel_capacity>13.20 gallons</fuel_capacity>
    <city_mileage>30 – 32 miles/gallon</city_mileage>
    <highway_mileage>38 – 41 miles/gallon</highway_mileage>
    <engine>1.8-L L-4 DOHC 16V</engine>
    <engine_size>1.8-L</engine_size>
    <engine_cylinders>L-4</engine_cylinders>
    <transmission>4-Speed Automatic 5-Speed Manual</transmission>
    <transmission_type>Manual</transmission_type>
    <transmission_speeds>5-Speed</transmission_speeds>
    <drivetrain>Front-Wheel Drive</drivetrain>
    <anti_brake_system>Non-Abs 4-Wheel ABS</anti_brake_system>
    <steering_type>Rack &amp; Pinion</steering_type>
    <curb_weight>2590 pounds</curb_weight>
    <gross_weight>9999 pounds</gross_weight>
    <gross_vehicle_weight_rating/>
    <overall_height>58.50 inches</overall_height>
    <overall_length>178.30 inches</overall_length>
    <overall_width>66.90 inches</overall_width>
    <wheelbase_length>102.40 inches</wheelbase_length>
    <standard_seating>5</standard_seating>
    <invoice_price>$13,563</invoice_price>
    <delivery_charges>$540</delivery_charges>
    <manufacturer_suggested_retail_price>$14,990</manufacturer_suggested_retail_price>
  </attributes>
  <success>1</success>
  <error/>
</result>

Example 2: Get by year, make, model, and trim (successful request JSON)

REQUEST:

https://specifications.vinaudit.com/v3/specifications?
format=json
&key=YOUR_API_KEY_HERE
&year=2005
&make=toyota
&model=corolla
&trim=ce


RESPONSE:

{
  "input": {
    "key": "YOUR_API_KEY_HERE",
    "year": "2005",
    "make": "toyota",
    "model": "corolla",
    "trim": "ce",
    "format": "json"
  },
  "selections": {
    "trims": [
      {
        "id": "2005_toyota_corolla_ce",
        "name": "CE",
        "selected": 1,
        "styles": []
      }
    ]
  },
  "attributes": {
    "year": "2005",
    "make": "Toyota",
    "model": "Corolla",
    "trim": "CE",
    "style": "",
    "type": "Car 2",
    "size": "Compact",
    "category": "Compact Cars",
    "made_in": "America",
    "made_in_city": "Cambridge",
    "doors": "5",
    "fuel_type": "Regular Unleaded",
    "fuel_capacity": "13.20 gallons",
    "city_mileage": "30 – 32 miles/gallon",
    "highway_mileage": "38 – 41 miles/gallon",
    "engine": "1.8-L L-4 DOHC 16V",
    "engine_size": "1.8-L",
    "engine_cylinders": "L-4",
    "transmission": "4-Speed Automatic 5-Speed Manual",
    "transmission_type": "Manual",
    "transmission_speeds": "5-Speed",
    "drivetrain": "Front-Wheel Drive",
    "anti_brake_system": "Non-ABS 4-Wheel ABS",
    "steering_type": "Rack & Pinion",
    "curb_weight": "2590 pounds",
    "gross_vehicle_weight_rating": "",
    "overall_height": "58.50 inches",
    "overall_length": "178.30 inches",
    "overall_width": "66.90 inches",
    "wheelbase_length": "102.40 inches",
    "standard_seating": "5",
    "invoice_price": "$13,563",
    "delivery_charges": "$540",
    "manufacturer_suggested_retail_price": "$14,990"
  },
  "success": true,
  "error": ""
}

Example 3: Get by ID (successful request XML)

REQUEST:

https://specifications.vinaudit.com/v3/specifications?
format=xml
&key=YOUR_API_KEY_HERE
&id=2004_toyota_corolla_ce
&include=selections,attributes,warranties,photos

RESPONSE:

<result>
  <input>
    <key>YOUR_API_KEY_HERE</key>
    <id>2004_toyota_corolla_ce</id>
    <format>xml</format>
    <include>selections,attributes,warranties,photos</include>
  </input>

  <selections>
    <trims>
      <trim>
        <id>2004_toyota_corolla_ce</id>
        <name>CE</name>
        <selected>1</selected>
        <styles/>
      </trim>
    </trims>
  </selections>

  <attributes>
    <year>2004</year>
    <make>Toyota</make>
    <model>Corolla</model>
    <trim>CE</trim>
    <style/>
    <type>Sedan 4-Door</type>
    <size>Compact</size>
    <category>Compact Cars</category>
    <made_in>Japan</made_in>
    <made_in_city>Takaoka</made_in_city>
    <doors>4</doors>
    <fuel_type>Regular Unleaded</fuel_type>
    <fuel_capacity>13.20 gallons</fuel_capacity>
    <city_mileage>29 – 32 miles/gallon</city_mileage>
    <highway_mileage>38 – 40 miles/gallon</highway_mileage>
    <engine>1.8-L L-4 DOHC</engine>
    <engine_cylinders>L-4</engine_cylinders>
    <transmission>4-Speed Automatic 5-Speed Manual</transmission>
    <transmission_type>Manual</transmission_type>
    <transmission_speeds>5-Speed</transmission_speeds>
    <drivetrain>Front-Wheel Drive</drivetrain>
    <anti_brake_system>Non-ABS 4-Wheel ABS</anti_brake_system>
    <steering_type>Rack &amp; Pinion</steering_type>
    <curb_weight>2590 pounds</curb_weight>
    <gross_vehicle_weight_rating/>
    <overall_height>58 inches</overall_height>
    <overall_length>178 inches</overall_length>
    <overall_width>66 inches</overall_width>
    <standard_seating>5</standard_seating>
    <invoice_price>$13,374</invoice_price>
    <delivery_charges>$515</delivery_charges>
    <manufacturer_suggested_retail_price>$14,780</manufacturer_suggested_retail_price>
  </attributes>

  <warranties>
    <warranty>
      <type>Basic</type>
      <months>36 Months</months>
      <miles>36,000 miles</miles>
    </warranty>
    <warranty>
      <type>Powertrain</type>
      <months>60 Months</months>
      <miles>60,000 miles</miles>
    </warranty>
    <warranty>
      <type>Rust</type>
      <months>60 Months</months>
      <miles>unlimited miles</miles>
    </warranty>
  </warranties>

  <photos>
    <photo>
      <url>https://imgset.info/a/2T1BR32E84C194054_20190205_0-36007?size=medium</url>
    </photo>
    <photo>
      <url>https://imgset.info/a/1NXBR32E34Z241831_20190205_0-141785?size=medium</url>
    </photo>
    <photo>
      <url>https://imgset.info/a/1NXBR32E04Z192720_20190205_0-46560?size=medium</url>
    </photo>
    <photo>
      <url>https://imgset.info/a/1NXBR38E74Z195377_20190205_0-43001?size=medium</url>
    </photo>
    <photo>
      <url>https://imgset.info/a/JTDBR32E042024060_20190205_0-44966?size=medium</url>
    </photo>
  </photos>

  <success>1</success>
  <error/>
</result>

Example 4: Get by VIN (invalid VIN request JSON)

REQUEST:

https://specifications.vinaudit.com/v3/specifications?
format=json
&key=YOUR_API_KEY_HERE
&vin=1NXBR32E85Z50590Q

RESPONSE:

{
"input": {
"key": "YOUR_API_KEY_HERE",
"vin": "1NXBR32E85Z50590Q"
},
"success": false,
"error": "invalid_vin"
}

FUNCTION #2: Get Vehicle Selections

Get a standardized list of year, make, model, trim, and style selections with names and IDs. To retrieve a full vehicle selection using GET or POST parameters, request:

GET
https://specifications.vinaudit.com/v3/selections?

Request Parameters

Parameter

key

required

Example

YOUR_API_KEY_HERE

Description

Your VinAudit API key

Parameter

list

optional

Example

list=year list=year+make list=year+make+model list=year+make+model+trim list=year+make+model+trim+style list=make list=make+model list=make+model+trim list=make+model+trim+style

Description

Dictates the attributes to be included in the response, each separated by the (+) sign

Parameter

id

optional

Example

id=2013 id=2013_subaru id=2013_subaru_outback id=2013_subaru_outback_base id=2013_subaru_outback_base_wagon id=subaru id=subaru_outback id=subaru_outback_base id=subaru_outback_base_wagon

Description

Unique identifier associated with each of the following attribute combinations: year year_make year_make_model year_make_model_trim year_make_model_trim_style make make_model make_model_trim make_model_trim_style

Parameter

year

optional

Example

2013

Description

The vehicle year

Parameter

make

optional

Example

subaru

Description

The vehicle make

Parameter

model

optional

Example

outback

Description

The vehicle model

Parameter

trim

optional

Example

base

Description

The vehicle trim

Parameter

style

optional

Example

wagon

Description

The selected vehicle sub trim

Parameter

format

optional

Example

json

Description

The output format: json, xml or csv

Parameter

collection

optional

Example

in-market

Description

The collection type. Available options include in-market, popular, and all.

In-market filters to YMMTs with 10+ active listings in the past 90 days from popular makes. Useful for real-time market insights.

Popular includes all YMMTs from 1980 onwards from a predefined list of popular makes.

All returns all YMMTs available in the Specs API. This includes both in-market and out-of-market vehicles, covering a complete spectrum of supported YMMTs.

Response Attributes

Parameter

selections

Example

<selections> <years>…</years> </selections>

Description

Contains the output elements (such as years, makes, model, trims) described below.

Parameter

years

Example

<years> <year> <name>2013</name> <id>2013</id> <makes>…</makes> </year> </years>

Description

Contains a list of “year” elements, each of which contain a name, id, and list of makes (see “makes” below)

Parameter

makes

Example

<makes> <make> <name>Subaru</name> <id>2013_subaru</id> <models>…</models> </make> </makes>

Description

Contains a list of “make” elements, each of which contain a name, id, and list of models (see “models” below)

Parameter

models

Example

<models> <model> <name>Outback</name> <id>2013_subaru_outback</id> <trims>…</trims> </model> </models>

Description

Contains the vehicle model name, id, and the element “trims”

Parameter

trims

Example

<trims> <trim> <name>Premium</name> <id>2013_subaru_outback-premium</id> </trim> </trims>

Description

Contains the vehicle trim name, id, and element “styles”

Parameter

styles

Example

<styles> <style> <name>Premium</name> <id>2013_subaru_outback_wagon</id> </style> </styles>

Description

Contains the vehicle style name and id

Parameter

result

Example

<result> <error>invalid_parameters</error> <details>please provide valid list</details> </result>

Description

Message received when using invalid parameters

Example 1: Get by list, year, make (successful request XML)

REQUEST:

https://specifications.vinaudit.com/v3/selections?
key=YOUR_API_KEY_HERE
&list=make+model
&year=2013
&make=subaru

RESPONSE:

<result>
  <selections>
    <makes>
      <make>
        <name>Subaru</name>
        <id>subaru</id>
        <models>
          <model>
            <name>BRZ</name>
            <id>subaru_brz</id>
          </model>
          <model>
            <name>Forester</name>
            <id>subaru_forester</id>
          </model>
          <model>
            <name>Impreza</name>
            <id>subaru_impreza</id>
          </model>
          <model>
            <name>Impreza WRX</name>
            <id>subaru_impreza-wrx</id>
          </model>
          <model>
            <name>Legacy</name>
            <id>subaru_legacy</id>
          </model>
          <model>
            <name>Outback</name>
            <id>subaru_outback</id>
          </model>
          <model>
            <name>Tribeca</name>
            <id>subaru_tribeca</id>
          </model>
          <model>
            <name>XV Crosstrek</name>
            <id>subaru_xv-crosstrek</id>
          </model>
        </models>
      </make>
    </makes>
  </selections>
</result>

Example 2: Get by ID (successful request JSON)

REQUEST:

https://specifications.vinaudit.com/v3/selections?
key=YOUR_API_KEY_HERE
&format=json
&id=2013_subaru_outback

RESPONSE:

{
  "selections": {
    "years": [
      {
        "name": 2013,
        "id": "2013",
        "makes": [
          {
            "name": "Subaru",
            "id": "2013_subaru",
            "models": [
              {
                "name": "Outback",
                "id": "2013_subaru_outback",
                "trims": [
                  {
                    "name": "2.5i",
                    "id": "2013_subaru_outback_25i"
                  },
                  {
                    "name": "2.5i Limited",
                    "id": "2013_subaru_outback_25i-limited"
                  },
                  {
                    "name": "2.5i Premium",
                    "id": "2013_subaru_outback_25i-premium"
                  },
                  {
                    "name": "3.6R",
                    "id": "2013_subaru_outback_36r"
                  },
                  {
                    "name": "3.6R Limited",
                    "id": "2013_subaru_outback_36r-limited"
                  },
                  {
                    "name": "3.6R Premium",
                    "id": "2013_subaru_outback_36r-premium"
                  },
                  {
                    "name": "Base",
                    "id": "2013_subaru_outback_base"
                  },
                  {
                    "name": "Limited",
                    "id": "2013_subaru_outback_limited"
                  },
                  {
                    "name": "Premium",
                    "id": "2013_subaru_outback_premium"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Example 3: Get by year, make, and model (successful request CSV)

REQUEST:

https://specifications.vinaudit.com/v3/selections?
format=csv
&key=YOUR_API_KEY_HERE
&year=2013
&make=subaru
&model=outback

RESPONSE:

YEAR,MAKE,MODEL,TRIM,ID
2013,subaru,outback,-,2013_subaru_outback
2013,subaru,outback,2.5i,2013_subaru_outback_25i
2013,subaru,outback,2.5i Limited,2013_subaru_outback_25i-limited
2013,subaru,outback,2.5i Premium,2013_subaru_outback_25i-premium
2013,subaru,outback,3.6R,2013_subaru_outback_36r
2013,subaru,outback,3.6R Limited,2013_subaru_outback_36r-limited
2013,subaru,outback,3.6R Premium,2013_subaru_outback_36r-premium
2013,subaru,outback,Base,2013_subaru_outback_base
2013,subaru,outback,Limited,2013_subaru_outback_limited
2013,subaru,outback,Premium,2013_subaru_outback_premium

Error Codes

Error Code Description
api_not_enabled The API key is invalid, disabled, or not authorized to access the Specifications service.
rate_limit_exceeded The account has reached its allowed API usage limit.
billing_limit_exceeded The account has reached its billing limit or has insufficient prepaid balance.
failed_request The request is missing required information or could not be validated.
service_unavailable The API service is temporarily unavailable. Please retry later.
invalid_country The country parameter is invalid. Use usa or canada .
invalid_inputs The request is missing required inputs or contains invalid values.
invalid_request The request format or encoding is invalid.
invalid_vin The VIN format is invalid.
invalid_vin_length The VIN has an invalid length.

Ready to build?

Access the VIN Decoder API with a free developer account. No credit card required.

Start Free TrialView API Docs