API Documentation

offers a web-based Application Programming Interface (API) for access to NMVTIS vehicle history reports. This allows for our resellers to provide NMVTIS data through their websites or software systems. In particular, our API exposes the ability to:

  • Query a VIN for records
  • Retrieve the vehicle specifications only (no history data)
  • Retrieve the full raw data for a vehicle history report (both specs + history)
  • Retrieve a PDF for a VIN Report

This page provides the necessary documentation for developers to code against our API.


API Overview

The API requires a reseller account. Once you have an account, you can login to access your API key. From there, your application can access data by making a HTTP requests to our API server (api.). The output received can be either JSON or XML depending on the specified format. Below, we document details of the specific resources and parameters to use.


1. Query a VIN

To query whether data for a VIN exists, request:

  • https://api./query.php

With GET or POST parameters:

  • vin: The vehicle identification number
  • key: Your API key
  • format: Output format (either json or xml)
  • skipspec: Set “1” if vehicle specs aren’t needed (optional)
  • mode: Set to “test” for development (optional)
  • callback: Javascript callback method (optional)

Response attributes:

  • id: The report ID to use in future requests
  • vin: The vehicle identification number
  • attributes: A map of specifications about the VIN (Make, Model, Style, Engine, Made In, Type)
  • success: Whether records exist in NMVTIS
  • error: One of no_records (no NMVTIS records exists), invalid_vin (not a valid VIN), fail_nmvtis (failed to reach NMVTIS), fail_spec (failed to retrieve specifications), or blank if no error
Example (json)
https://api./query.php?vin=1VXBR12EXCP901213&key=YOUR_KEY&format=json

{“id”:”7742103371467″, “vin”:”1VXBR12EXCP901213″,”attributes”:{“VIN”:”1VXBR12EXCP901213″,”Make”:”TOYOTA”,”Model”:”COROLLA CE”,”Style”:”4 DOOR SEDAN”,”Engine”:”1.8L L4 DOHC 16V”,”Made In”:”JAPAN”,”Type”:”PASSENGER CAR”},”success”:true,”error”:””}
Implementation Notes:
  • Requests to the “query” API do not deduct from report credits.

2. Retrieve a vehicle’s full specification data

To retrieve a vehicle’s full specifications (e.g., make, model, etc.), request:
  • https://api./pullspecs.php

With GET or POST parameters:

  • vin: The vehicle identification number
  • key: Your API key
  • format: Output format (either json or xml)
  • callback: Javascript callback method (optional)

Response attributes:

  • id: The report ID to use in future requests
  • vin: The vehicle identification number
  • attributes: A map of specifications about the VIN (Make, Model, Style, Engine, Made In, Type)
  • success: Whether vehicle specifications data exists
  • error: One of…
    • no_data (no specifications available)
    • invalid_vin (not a valid VIN)
    • failed (temporary error)
    • or blank if no error
Example (json)
https://api./pullspecs.php?vin=1VXBR12EXCP901213&key=YOUR_KEY&format=json

{“vin”:”1VXBR12EXCP901213″,”attributes”:{“VIN”:”1VXBR12EXCP901213″,”Year”:”2005″,”Make”:”TOYOTA”,”Model”:”COROLLA”,”Trim Level”:”CE”,”Engine”:”1.8L L4 DOHC 16V”,”Style”:”4 DOOR SEDAN”,”Made In”:”JAPAN”,”Steering Type”:”R&P”,”Anti-Brake System”:”Non-ABS | 4-Wheel ABS”,”Tank Size”:”13.20 gallon”,”Overall Height”:”58.50 in.”,”Overall Length”:”178.30 in.”,”Overall Width”:”66.90 in.”,”Standard Seating”:”5″,”Optional Seating”:”No data”,”Highway Mileage”:”38 – 41 miles\\\/gallon”,”City Mileage”:”30 – 32 miles\\\/gallon”},”success”:true,”error”:””}
Implementation Notes:
  • Requests to the “pullspecs” API do not deduct from report credits.

3. Retrieve a full Vehicle History Report

To retrieve the NMVTIS data for a VIN (if such data exists), request:

  • https://api./pullreport.php

With GET or POST parameters:

  • id: A unique report ID for this report request
  • vin: The vehicle identification number
  • user: Your account username
  • pass: Your account password*
  • key: Your API key
  • format: Output format (either json or xml)
  • mode: Set to “test” for development (optional)
  • pdf: Set to “1” to download a PDF (optional)
  • brand: Set to “0” to produce unbranded PDF; requires pdf=”1″ (optional)
  • callback: Javascript callback method (optional)

Response attributes (if successful):

  • id: The report identifier
  • vin: The vehicle identification number
  • specs: A dynamic map of available vehicle specifications
  • titles: A list of title records with the format:
    • date: The title record date
    • state: The 2-letter code for the issuing
    • vin: The recorded VIN (may be old VIN)
    • meter: The odometer reading
    • meterUnit: ‘M’ for miles, ‘K’ for kilometers
    • current: Whether the title record is current, not historical
  • jsi: A list of Junk/Salvage/Insurance records, each with attributes:
    • date: The brand date.
    • recordType: The type of record.
    • branderName: The brander’s name.
    • branderCity: The brander’s city.
    • branderState: The brander’s state.
    • branderEmail: The brander’s email.
    • branderPhone: The brander’s phone.
    • vehicleDisposition: The vehicle’s reported disposition.
    • intendedForExport: Whether the vehicle is intended for export.
  • nvs: A list of lien, theft, impound, export, ebay records (requires NVS-enabled account):
    • recordType: One of: Lien, Theft, Impound, Export, Ebay
    • lienDate/lastEventDate/impoundDate/auctionDate: The date of the event.
    • state: The US State in which the event occurred (if available)
    • status: The status of the vehicle (if available)
    • lienholder: The entity holding the lien (if lien record)
    • vin: The VIN associated with the event (for confirmation)
  • checks: An list of brand records with the format:
    • date: The title brand date.
    • brandCode: The brand code
    • branderType: The brander’s type
    • branderName: The brander’s name
    • disposition: The vehicle’s reported disposition
  • clean: Whether the report is free of title brands, salvage, and insurance records
  • success: Whether the report has been generated
  • error: blank if no error (see below for possibilities)

Response attributes (if failure):

  • vin: The vehicle identification number
  • success: Whether the report has been generated
  • details: State information for debugging purposes
  • error: One of…
    • invalid_vin (not a valid VIN)
    • fail_nmvtis (failed to reach NMVTIS)
    • no_records (no NMVTIS records exists)
    • not_ready (retry)
    • vin_mismatch (ID is associated with a different VIN; use new ID)
    • failed (unexpected error)
    • expired (report no longer cached)
    • blank if no error
Example #1 (no records, xml):
http://api./pullreport.php?id=00000000000001&key=0V9CRCA32QARIIE&vin=4JGBB86E78A330935&mode=&user=vatest&pass=vatest222&format=xml

<result>
  <vin>4JGBB86E78A330935</vin>
  <id>515237647496</id>
  <attributes>
    <VIN>4JGBB86E78A330935</VIN>
  </attributes>
  <success>0</success>
  <error>no_records</error>
</result>
Example #2 (full report data, json):
http://api./pullreport.php?id=00000000000002&key=MY_KEY&vin=1VXBR12EXCP901213&mode=test&user=MY_USER&pass=MY_PASS&format=json

{“success”:true,”error”:””,”id”:”31919508431″,”vin”:”1VXBR12EXCP901213″,”date”:”2011-12-21 21:12:15 PST”,”specs”:{“Vin”:”1VXBR12EXCP901213″,”Year”:”2005″,”Make”:”Toyota”,”Model”:”Corolla”,”Trim”:”CE”,”Engine”:”1.8L L4 DOHC 16V”,”Style”:”SEDAN 4-DR”,”Made In”:”UNITED STATES”,”Steering Type”:”R&P”,”Anti-Brake System”:”4-Wheel ABS”,”Tank Size”:”13.20 gallon”,”Overall Height”:”58.50 in.”,”Overall Length”:”178.30 in.”,”Overall Width”:”66.90 in.”,”Standard Seating”:”5″,”Optional Seating”:”No data”,”Highway Mileage”:”38 – 41 miles\/gallon”,”City Mileage”:”30 – 32 miles\/gallon”},”jsi”:[{'date': '10/25/2007','recordType':'Junk And Salvage','branderName':'Insurance Salvage, Inc.','branderCity':'Milwalkee','branderState':'WI','branderEmail':'','branderPhone': '5556478921','vehicleDisposition':'Sold','intendedForExport':'No'}],”checks”:[ {'brandCode': '11', 'branderType': 'State', 'branderName': 'Ohio', 'disposition': 'Salvage', 'date': '08/02/2005' }, {'brandCode': '09', 'branderType': 'State', 'branderCode': '', 'branderName': 'Ohio', 'disposition': 'Rebuilt', 'date': '08/19/2005' } ],”titles”: [ {'date': '08/31/2011', 'state':'WA', 'vin':'', 'meter':'59,396', 'meterUnit':'M', 'current': true}, {'date': '02/23/2008', 'state':'WI', 'vin':'1VXBR12EXCP901213', 'meter':'37,398', 'meterUnit':'M', 'current': false}, {'date': '11/04/2007', 'state':'WI', 'vin':'1VXBR12EXCP901213', 'meter':'12,269', 'meterUnit':'M', 'current': false}, {'date': '08/19/2005', 'state':'OH', 'vin':'1VXBR12EXCP153842', 'meter':'3,220', 'meterUnit':'M', 'current': false}, {'date': '06/22/2005', 'state':'OH', 'vin':'1VXBR12EXCP153842', 'meter':'', 'meterUnit':'M', 'current': false} ]}
Example #3 (report PDF):
http://api./pullreport.php?id=00000000000003&key=MY_KEY&vin=1VXBR12EXCP901213&mode=test&user=MY_USER&pass=MY_PASS&format=json&pdf=1

  • This request can be re-issued repeatedly using the same ID and VIN.
  • Your API account is billed at most once for each unique report ID.
  • Once generated, re-issuing the request will return the cached report data.
  • An extended API is also available for finer-grained control.
  •  
     
    © 2014 LLC. Not affiliated with CARFAX®, a registered trademark of Carfax, Inc.