🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Vehicle Selector and VIN Decoder Setup Guide

Updated 8 min read Gravity Forms Fields & Inputs
On this page
  1. Video walkthrough
  2. What you need
  3. Step 1: install and activate the licence
  4. The settings explained
  5. Step 2: add the Vehicle Selector field
  6. Step 3: add the VIN Decoder field
  7. Choosing which fields the decoder fills
  8. How a VIN is checked
  9. Where the data comes from, and how lookups stay fast
  10. What is saved on the entry
  11. Troubleshooting
  12. A worked example: a trade-in form
  13. Merge tags, notifications and exports
  14. Accessibility and the no-script case
  15. Performance notes
  16. Good to know

Video walkthrough

Gravity Forms Vehicle Selector Setup Guide: Year, Make & Model Dropdowns + VIN Decoder
Video setup guide: Gravity Forms Vehicle Selector Watch on YouTube

The Gravity Forms Vehicle Selector Premium Add-on lets a visitor tell you exactly which vehicle they have, without typing it wrong. It adds two fields to the Gravity Forms editor: a Vehicle Selector with Year, Make and Model dropdowns that fill in from each other, and a VIN Decoder where the visitor types a 17-character VIN and the make, model, year, body class, engine and more are read back and dropped into the fields you choose. The vehicle data comes from the free NHTSA vPIC dataset, read through your own site with caching, so the browser never calls the dataset directly and your form stays fast.

What you need

  • WordPress 5.8 or newer, PHP 7.4 or newer and Gravity Forms 2.5 or newer. Tested with Gravity Forms 3.1.2 on PHP 8.3 and Gravity Forms 2.9.8 on PHP 7.4.
  • Your GravityExtra licence key. Without an active licence the lookups are off and the dropdowns stay empty.
  • No account and no API key for the vehicle data. The NHTSA vPIC dataset is a United States government open dataset that is free to read and asks for no sign-up.
  • Your site must be able to make an outgoing HTTPS request to vpic.nhtsa.dot.gov. That is the only host the add-on ever contacts.

Step 1: install and activate the licence

  1. Upload and activate the add-on in Plugins.
  2. Open Forms → Settings → Vehicle Selector and activate your licence key.
  3. Review the Vehicle data options. The defaults are good for most sites; you can change the cache length, the rate guard and the VIN check at any time.
The Vehicle Selector settings screen in Gravity Forms: the licence box, the cache hours for the make and model lists, the lookups-per-minute rate guard and the VIN check-digit option
The settings: the licence box and the cache, rate guard and VIN check for the lookups.

The settings explained

  • Cache the make and model lists for (hours): how long a make or model list is kept before it is fetched again, from 1 to 168. Decoded VINs are cached for a day. Model lists rarely change, so 12 to 24 hours is plenty and keeps the form quick.
  • Lookups per minute per visitor: a gentle guard so one browser cannot flood the lookups, from 5 to 600. Answers served from the cache do not count against it.
  • VIN check digit: tick this to refuse a VIN that fails its check-digit test before the add-on tries to decode it. Left off, any well-formed 17-character VIN is sent to the dataset, which decodes what it can.

Step 2: add the Vehicle Selector field

Open a form and, from the Advanced Fields group in the editor, add the Vehicle Selector field. On the published form it shows three dropdowns. The visitor picks the Year first; the Make dropdown then fills with the makes in the dataset; after a make is chosen, the Model dropdown fills with the models for that make and year. The three choices are stored together on the entry as one value, for example “2003 Honda Accord”.

The Gravity Forms form editor with a Vehicle Selector field and a VIN Decoder field added from the Advanced Fields group, plus plain text fields marked with the gfvs CSS classes to be filled
Both fields in the editor, with plain fields marked by CSS class for the decoder to fill.

Step 3: add the VIN Decoder field

Add the VIN Decoder field from the same Advanced Fields group. On the published form it shows a box for a 17-character VIN and a Decode VIN button. When the visitor types a VIN and presses the button, the add-on asks your site to decode it and then fills the matching fields in the form. The VIN itself is also saved on the entry, cleaned and upper-cased.

Choosing which fields the decoder fills

The decoder fills any field in the same form that carries a matching CSS class. Add the fields you want (ordinary Single Line Text fields work well), and give each one a CSS class in Appearance → Custom CSS Class. Use the class for the detail you want in that field:

  • gfvs-make, gfvs-model, gfvs-year — make, model and model year
  • gfvs-trim, gfvs-series, gfvs-body_class, gfvs-vehicle_type, gfvs-doors, gfvs-drive_type
  • gfvs-engine_cylinders, gfvs-displacement_l, gfvs-engine_model, gfvs-engine_hp, gfvs-fuel_type, gfvs-transmission
  • gfvs-gvwr, gfvs-plant_country, gfvs-manufacturer

You only need the classes for the details you care about; leave the rest out. A field can be a Single Line Text field, a drop down or a hidden field. The decoder sets the value and leaves everything else to Gravity Forms, so required rules, conditional logic and calculations all keep working.

The published form: the Year, Make and Model dropdowns and a VIN box with a Decode VIN button, with the make, model, year and body class filled in after decoding a VIN
The published form after a VIN is decoded: the make, model, year and body class are filled in.

How a VIN is checked

A Vehicle Identification Number is 17 characters, uses letters and digits, and never contains the letters I, O or Q, which are left out to avoid confusion with 1 and 0. The add-on cleans the value (it upper-cases it and removes spaces and dashes), then checks the length and the characters. The ninth character is a check digit, worked out from the other sixteen; if you turn on the VIN check-digit option, a VIN whose check digit does not match is refused before any lookup, which catches most typos. The same length and character check runs again when the form is submitted, so a bad VIN cannot be stored.

Where the data comes from, and how lookups stay fast

The vehicle data is the free NHTSA vPIC dataset. The add-on reads three parts of it: the list of all makes, the models of a make for a model year, and the decoded details of a VIN. Every one of these runs on your own server, not in the visitor’s browser: the browser asks your site, your site reads the dataset and returns the answer. The make and model lists and each decoded VIN are cached, so the dataset is asked only once per make, year or VIN for the cache period, and repeat visitors get an instant answer. The add-on only ever calls the one dataset host, so nothing a visitor types can redirect a request anywhere else.

What is saved on the entry

The Vehicle Selector field stores the chosen “Year Make Model” line. The VIN Decoder field stores the VIN, cleaned and upper-cased. Any field you marked with a gfvs class stores the decoded detail that was filled into it, exactly like a value the visitor typed. Because these are ordinary Gravity Forms fields, they appear in the entry, in notifications, in exports and in merge tags like any other answer.

Troubleshooting

  • The dropdowns stay empty. Check that the licence key is active under Forms → Settings → Vehicle Selector, and that your server can reach vpic.nhtsa.dot.gov over HTTPS.
  • Decode says the VIN is not valid. A VIN is exactly 17 characters with no I, O or Q. If you turned on the check-digit option, a VIN with a typo is refused; re-check it against the car.
  • Some details are blank after decoding. Older or imported vehicles are not always fully described in the dataset. The add-on fills only the details the dataset returns and leaves the rest untouched.
  • “Too many lookups” appears. That is the per-visitor rate guard. Raise the lookups-per-minute setting if your forms are busy.

A worked example: a trade-in form

Say you run a trade-in valuation form and want a clean vehicle on every entry. Build the form like this. Add a Vehicle Selector field at the top so a visitor who knows their car can pick the year, make and model in three taps. Below it, add a VIN Decoder field for visitors who would rather read the number off the windscreen or the logbook. Then add four Single Line Text fields labelled Make, Model, Year and Body class, and give them the CSS classes gfvs-make, gfvs-model, gfvs-year and gfvs-body_class. You can set those four fields to be read-only or hidden if you only want them filled by the decoder. Finally add your own fields for the mileage, condition and contact details.

Now a visitor has two easy paths. If they use the picker, you get “2016 Ford F-150” in one tidy value. If they decode a VIN, the Make, Model, Year and Body class fields fill in at once, and the VIN itself is stored too. Either way, your team opens the entry and sees exactly which vehicle to price, with no guessing and no misspellings to clean up.

Merge tags, notifications and exports

Because the Vehicle Selector and VIN Decoder are ordinary Gravity Forms fields, everything that works with a normal field works with them. Use their merge tags in a notification so the e-mail to your team shows the chosen vehicle and the VIN. Add them to a confirmation message so the visitor sees a summary of what they submitted. Include them in a CSV export or send them to any other add-on that reads entry values. The fields marked with a gfvs class are just as ordinary: their decoded values are stored and exported like anything the visitor typed.

Accessibility and the no-script case

The cascade uses three real dropdowns with proper labels, so a keyboard or a screen reader moves through them as it would any select. The VIN box is a plain text input with a clearly labelled button next to it. If a visitor has JavaScript turned off, the dropdowns and the VIN box still appear and the form still submits; only the live filling and decoding need JavaScript, which nearly every visitor has. A visitor can always type a value into a marked field by hand if they prefer.

Performance notes

The first time anyone on your site chooses a make, your server fetches the full make list once and caches it; everyone after that gets it instantly. The same is true for the models of a given make and year, and for each decoded VIN. On a busy site this means the vehicle dataset sees a handful of requests a day rather than one per visitor, your pages stay fast, and you are a good citizen of a free public dataset. If you ever need fresher data, lower the cache hours in the settings; if your forms are very busy, raise the lookups-per-minute guard.

Good to know

The add-on works with Gravity Forms 2.5 and newer, on PHP 7.4 through 8.3. The two fields support required rules, conditional logic, confirmations and notifications. No personal data is sent to the vehicle dataset; only the make, year or VIN needed for the lookup is sent, and the VIN describes the vehicle, not the person. When you remove the add-on, its settings and its cached lookups are deleted; the entries and their stored values stay.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr