NeoVIN Decoder

Enhanced VIN decoder providing comprehensive vehicle specifications and attributes from a 17-character VIN, including options, features, and installed equipment.

The NeoVIN Decoder API is an advanced VIN decoder that provides comprehensive vehicle specifications and attributes derived from a valid 17-character Vehicle Identification Number (VIN). This service is designed to return detailed information about a vehicle, including its make, model, year, trim, options packages, installed equipment, and more.

This API is particularly useful for applications that require in-depth vehicle information, including options and features, making it ideal for automotive marketplaces, inventory management systems, and other applications that need detailed vehicle specifications. For high-volume decoding workflows, the API also supports batch processing of 1,000 to 3,000 VINs in a single request—see the Batch API introduction for general batch concepts and best practices.

It is an enhanced version of the Basic VIN Decoder, offering more detailed data and additional features.

Base Path

GET https://api.marketcheck.com/v2/decode/car/neovin/{vin}/specs

Path Parameters:

vin: The 17-character VIN of the vehicle to decode.

The following example demonstrates a basic request to the NeoVIN Decoder API:

request.js

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/decode/car/neovin/1FTEW1C59LKE56394/specs',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Request

The NeoVIN Decoder API provides comprehensive vehicle specifications and detailed information using a valid 17-character Vehicle Identification Number (VIN). This enhanced decoder offers extensive data including options packages, installed equipment, features, and confidence scoring.

Parameters

Available parameters for enhanced VIN decoding requests:

3 Params

api_key

string required

Your MarketCheck API authentication key. Required for every request, unless OAuth is used.

include_generic

boolean

If true, includes generic VIN decode information in NeoVIN responses.

include_available_options

boolean

If true, includes available options details in NeoVIN responses.

Required Parameters

The following parameters are required for NeoVIN decoding requests:

vin - The 17-character VIN of the vehicle to decode (provided in URL path)
- Case-insensitive string that must be properly formatted
- Must be provided as a path parameter in the URL structure
- Squish VIN is not supported in this API

Special Parameters

include_generic

Use include_generic=true to include additional generic specifications alongside detailed NeoVIN data
When VIN decoding fails but generic specifications are available, they will be included automatically
Provides fallback data when comprehensive decoding is not possible

include_available_options

Use include_available_options=true to include available options details alongside detailed NeoVIN data
Provides factory-available options and packages for the decoded VIN

Response

The NeoVIN Decoder API returns comprehensive vehicle specifications and detailed information in a structured JSON format.

Schema

interface Response {
  vin: string; // Original VIN provided for decoding
  squish_vin: string; // Squish VIN representation
  year: number; // Model year of the vehicle
  make: string; // Vehicle manufacturer name
  model: string; // Vehicle model name
  vehicle_type: string; // Vehicle classification
  listing_confidence: string; // Confidence level for listing accuracy
  trim: string; // Trim level or variant
  trim_confidence: string; // Confidence score for trim identification
  version: string; // Specific version or sub-model
  version_confidence: string; // Confidence score for version identification
  transmission: string; // Transmission type
  transmission_confidence: string; // Confidence score for transmission
  transmission_description: string; // Detailed transmission description
  drivetrain: string; // Drivetrain configuration
  powertrain_type: string; // Powertrain classification
  engine: string; // Engine description
  fuel_type: string; // Fuel type
  doors: number; // Number of doors
  body_type: string; // Body style
  body_subtype: string; // Body substyle
  weight: number; // Vehicle weight
  width: number; // Vehicle width
  height: number; // Vehicle height
  length: number; // Vehicle length
  city_mpg: number; // City fuel economy
  highway_mpg: number; // Highway fuel economy
  manufacturer_code: string; // Manufacturer's internal code
  package_code: string; // Package code
  msrp: number; // Manufacturer's Suggested Retail Price
  delivery_charges: number; // Delivery and destination charges
  installed_options_msrp: number; // MSRP of installed options
  combined_msrp: number; // Total MSRP including options
  interior_color: Color; // Interior color information
  exterior_color: Color; // Exterior color information
  country: string; // Country of manufacture
  seating_capacity: number; // Number of seats
  options_packages: string; // Installed options packages
  installed_options_details: InstalledOption[]; // Detailed options information
  features: Record<string, Feature[]>; // Categorized features
  high_value_features: Record<string, HighValueFeature[]>; // High-value features
  installed_equipment: Record<string, InstalledEquipment[]>; // Installed equipment details
  available_options_details: AvailableOption[]; // Detailed available options information
  generic?: Record<string, string>; // Generic specifications if requested
  created_at: number; // Creation timestamp
  created_at_date: string; // Creation date string
  updated_at: number; // Last update timestamp
  updated_at_date: string; // Last update date string
  decode_version: number; // Version of decode algorithm used
  mc_msrp?: number; // MarketCheck computed MSRP value
  build_specs_msrp?: number; // MSRP derived from build specs / configuration data
  oem_msrp?: number; // OEM (Original Equipment Manufacturer) listed MSRP
  original_msrp?: number; // Original MSRP at time of vehicle release
  record_confidence?: number; // Confidence score for the decoded record (0-1 float)
  record_source?: string; // Source of the decoded record data

}

interface Color {
  code: string; // Color code
  name: string; // Color name
  confidence: string; // Confidence score for color identification
  base: string; // Base color family
}

interface AvailableOption {
  code: string; // Option code
  name: string; // Option name
  msrp: string; // Option MSRP
  type: string; // Option type
}

interface InstalledOption {
  code: string; // Option code
  name: string; // Option name
  msrp: string; // Option MSRP
  type: string; // Option type
  confidence: string; // Confidence score
  verified: boolean; // Whether option is verified
  rule: string; // Rule used for identification
  sale_price: string; // Sale price if different from MSRP
}

interface Feature {
  category: string; // Feature category
  feature_type: string; // Type of feature
  description: string; // Feature description
}

interface HighValueFeature {
  category: string; // Feature category
  description: string; // Feature description
}

interface InstalledEquipment {
  category: string; // Equipment category
  item: string; // Equipment item
  attribute: string; // Equipment attribute
  location: string; // Equipment location
  value: string; // Equipment value
}

Success Response

200 OK - Returns a JSON object containing detailed vehicle specifications derived from the VIN
- Includes comprehensive details such as year, make, model, trim, body type, and extensive additional data
- Contains options packages, installed equipment, features, and high-value features
- Provides confidence scores for various decoded attributes
- If include_generic=true, includes generic specifications alongside detailed data
- If include_available_options=true includes available options details alongside detailed NeoVIN data

Error Response

Status Code	Description	Common Causes
400	Bad Request	Invalid parameter values
401	Unauthorized	Missing/invalid API key
403	Forbidden	Access denied to resource
422	Unprocessable Entity	Invalid VIN or failed decoding
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Temporary server issues
502	Bad Gateway	Issues with upstream services
503	Service Unavailable	API maintenance or downtime

Use Cases & Examples

Comprehensive VIN Decode

Use the NeoVIN Decoder to get detailed vehicle specifications including options packages, installed equipment, and features. This is ideal for applications requiring complete vehicle information.

Example:

Here we're performing a comprehensive NeoVIN decode to get detailed specifications:

request.js

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/decode/car/neovin/WA1BBAFY7P2183119/specs',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

VIN Decode with Available Options

Includes available options details in NeoVIN responses.

Example:

Here we're requesting NeoVIN decode with available options details included:

request.js

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/decode/car/neovin/1FTEW1C59LKE56394/specs',
  params: {api_key: 'YOUR_API_KEY', include_available_options: 'true'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

VIN Decode with Generic Fallback

Include generic specifications as fallback data when detailed decoding might not be available. This ensures you always get some vehicle information.

Example:

Here we're requesting NeoVIN decode with generic specifications included:

request.js

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/decode/car/neovin/5TFUW5F16KX782196/specs',
  params: {api_key: 'YOUR_API_KEY', include_generic: 'true'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Options and Features Analysis

Retrieve detailed information about installed options, features, and equipment for vehicle valuation and configuration analysis.

Example:

Here we're focusing on options and features data from NeoVIN:

request.js

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/decode/car/neovin/5TFVC5DB1NX010363/specs',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Batch NeoVIN Decode

In addition to the single-VIN decode endpoint, you can decode 1,000 to 3,000 VINs in a single batch request. Submit a plain CSV file containing VINs, track processing progress, and download enriched decode results as a JSONL file.

Batch processing is an Enterprise package offering and is enabled on your account upon request.

Batch API Endpoints

API	Endpoint	Description
Submit Job	`POST /v2/batch/neovin/decode/jobs`	Submit a CSV file of VINs for batch decoding
Get Job Status	`GET /v2/batch/neovin/decode/jobs/{job_id}`	Check the status and progress of a specific job
List Jobs	`GET /v2/batch/neovin/decode/jobs`	List your batch decode jobs with filtering and pagination
Download Results	`POST /v2/batch/neovin/decode/jobs/{job_id}/download`	Download the decode results for a completed job

Submit Job

Create a new batch VIN decode job.

POST https://api.marketcheck.com/v2/batch/neovin/decode/jobs

request.js


  // Loading...

Parameters

Parameter	Type	Default	Description	Required
`api_key`	string	-	Your API key, passed as a URL query parameter	Y
`file`	file	-	Plain CSV file containing VINs (not gzip-compressed). Must have a `vin` column header. Maximum file size: 10 MB.	Y
`client_reference`	string	-	Your internal tracking identifier. Max 255 characters.	N
`webhook_url`	string	-	HTTPS URL to receive completion/failure notifications. Max 2,048 characters.	N
`webhook_secret`	string	-	Secret used to sign webhook payloads for verification. Max 512 characters.	N
`Idempotency-Key`	string (header)	-	Unique key for safe retries. Max 255 characters.	N

Submit the CSV file as-is — do not gzip-compress it. See Input File Format below for details.

Send the request as multipart/form-data.

Response

Status: 202 Accepted

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "client_reference": "my-batch-2026-03-15",
    "created_at": "2026-03-15T14:30:00Z"
}

item_count is not included in the initial response. It appears once processing begins and is visible in subsequent status checks.

Field	Type	Description
`job_id`	string	Unique job identifier (UUID). Use this for all subsequent requests.
`status`	string	Always `"PROCESSING"` for newly created jobs.
`item_count`	integer	Total number of VINs in the file. Absent immediately after submission; populated once processing begins.
`client_reference`	string	Your tracking identifier, if provided. Omitted if not provided.
`created_at`	string	Job creation timestamp (ISO 8601).

Errors

Status	Code	Description
400	`missing_file`	The `file` field is missing from the multipart form
400	`invalid_file_format`	The file is not a valid plain CSV (gzip files are rejected)
400	`invalid_webhook_url`	Webhook URL is not HTTPS or targets a non-routable address
400	`invalid_parameter`	A form field exceeds its maximum length
409	`active_job_exists`	You already have an active decode job
413	`file_too_large`	The uploaded file exceeds the maximum allowed size

For retry and error handling guidance, see Best Practices in the Batch API introduction.

Get Job Status

Retrieve the current status and details of a specific job.

GET https://api.marketcheck.com/v2/batch/neovin/decode/jobs/{job_id}

request.js

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/batch/neovin/decode/jobs/550e8400-e29b-41d4-a716-446655440000',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Parameters

Parameter	Type	Default	Description	Required
`api_key`	string	-	Your API key, passed as a URL query parameter	Y
`job_id`	string (path)	-	The job identifier returned by the Submit endpoint	Y

Response

Status: 200 OK

During processing:

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "progress_percent": 45,
    "item_count": 2500,
    "client_reference": "my-batch-2026-03-15",
    "created_at": "2026-03-15T14:30:00Z"
}

When completed:

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "progress_percent": 100,
    "item_count": 2500,
    "successful_count": 2450,
    "failed_count": 50,
    "client_reference": "my-batch-2026-03-15",
    "created_at": "2026-03-15T14:30:00Z",
    "completed_at": "2026-03-15T14:45:00Z",
    "download_available": true,
    "download_count": 0,
    "max_downloads": 3,
    "remaining_downloads": 3
}

When failed:

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "FAILED",
    "progress_percent": 45,
    "item_count": 2500,
    "client_reference": "my-batch-2026-03-15",
    "created_at": "2026-03-15T14:30:00Z",
    "error_code": "processing_failed",
    "error_message": "Job processing failed unexpectedly. Please resubmit."
}

Response Schema

Field	Type	Present	Description
`job_id`	string	Always	Unique job identifier (UUID)
`status`	string	Always	`PROCESSING`, `COMPLETED`, or `FAILED`
`progress_percent`	integer	Always	Processing progress from 0 to 100
`item_count`	integer	When available	Total VINs in the submitted file. May be absent briefly after submission.
`successful_count`	integer	COMPLETED only	Number of VINs successfully decoded
`failed_count`	integer	COMPLETED only	Number of VINs that could not be decoded
`client_reference`	string	If provided	Your tracking identifier
`created_at`	string	Always	Job creation timestamp (ISO 8601)
`completed_at`	string	COMPLETED only	Job completion timestamp (ISO 8601)
`download_available`	boolean	COMPLETED only	Whether the result file can be downloaded
`download_count`	integer	COMPLETED only	Number of times you have downloaded this job's results
`max_downloads`	integer	COMPLETED only	Maximum downloads allowed (3)
`remaining_downloads`	integer	COMPLETED only	Downloads remaining
`error_code`	string	FAILED only	Machine-readable error code
`error_message`	string	FAILED only	Human-readable error description

Errors

Status	Code	Description
404	`job_not_found`	Job does not exist or does not belong to your account

For retry and error handling guidance, see Best Practices in the Batch API introduction.

List Jobs

Retrieve a paginated list of your batch decode jobs.

GET https://api.marketcheck.com/v2/batch/neovin/decode/jobs

request.js

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/batch/neovin/decode/jobs',
  params: {api_key: 'YOUR_API_KEY', status: 'completed', rows: '10'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Parameters

Parameter	Type	Default	Description	Required
`api_key`	string	-	Your API key, passed as a URL query parameter	Y
`status`	string	`all`	Filter jobs by status: `all`, `active`, `completed`, `failed`	N
`rows`	integer	`20`	Number of jobs per page (1–100)	N
`cursor`	string	-	Opaque cursor from a previous response's `next_cursor`	N

Filter definitions:

Filter Value	Returns
`all`	All jobs
`active`	Jobs still processing (status = `PROCESSING`)
`completed`	Successfully completed jobs (status = `COMPLETED`)
`failed`	Failed jobs (status = `FAILED`)

Response

Status: 200 OK

{
    "jobs": [
        {
            "job_id": "550e8400-e29b-41d4-a716-446655440000",
            "status": "COMPLETED",
            "progress_percent": 100,
            "item_count": 2500,
            "successful_count": 2450,
            "failed_count": 50,
            "client_reference": "my-batch-2026-03-15",
            "created_at": "2026-03-15T14:30:00Z",
            "completed_at": "2026-03-15T14:45:00Z",
            "download_available": true,
            "download_count": 1,
            "max_downloads": 3,
            "remaining_downloads": 2
        },
        {
            "job_id": "660f9511-f3ac-52e5-b827-557766551111",
            "status": "PROCESSING",
            "progress_percent": 62,
            "item_count": 1800,
            "client_reference": "my-batch-2026-03-14",
            "created_at": "2026-03-14T09:15:00Z"
        }
    ],
    "total": 42,
    "next_cursor": "eyJjIjoiMjAyNi0wMy0xNFQwOToxNTowMFoiLCJqIjoiNjYwZjk1MTEtZjNhYy01MmU1LWI4MjctNTU3NzY2NTUxMTExIn0",
    "rows": 20
}

Field	Type	Description
`jobs`	array	Array of job status objects (same fields as Get Job Status)
`total`	integer	Total number of jobs matching the filter
`next_cursor`	string	Opaque cursor for the next page. Absent when no more pages exist.
`rows`	integer	Page size used for this response

Errors

Status	Code	Description
400	`invalid_parameter`	Invalid `status` filter value or malformed `cursor`

For retry and error handling guidance, see Best Practices in the Batch API introduction.

Download Results

Download the decode results for a completed job. Each call streams the result file directly.

POST https://api.marketcheck.com/v2/batch/neovin/decode/jobs/{job_id}/download

This endpoint uses POST (not GET) because each call consumes one of your 3 download slots.

request.js

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/batch/neovin/decode/jobs/550e8400-e29b-41d4-a716-446655440000/download',
  params: {api_key: 'YOUR_API_KEY'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Parameters

Parameter	Type	Default	Description	Required
`api_key`	string	-	Your API key, passed as a URL query parameter	Y
`job_id`	string (path)	-	The job identifier	Y

Response

Status: 200 OK

The response body is the raw binary file (gzip-compressed JSONL). Metadata is returned in response headers:

Header	Type	Description
`Content-Type`	string	`application/gzip`
`Content-Disposition`	string	`attachment; filename="output.jsonl.gz"`
`X-Download-Count`	integer	Number of downloads consumed, including this one
`X-Max-Downloads`	integer	Maximum downloads allowed (3)
`X-Remaining-Downloads`	integer	Downloads remaining after this one
`X-File-Checksum`	string	SHA-256 checksum of the file for integrity verification

Errors

Status	Code	Description
403	`download_limit_exceeded`	All 3 download slots have been consumed
404	`job_not_found`	Job does not exist or does not belong to your account
409	`job_not_completed`	Job has not finished processing yet

For retry and error handling guidance, see Best Practices in the Batch API introduction.

Input File Format

The input file must be a plain CSV (not gzip-compressed) with:

A header row containing at least the column vin
One VIN per data row
Between 1,000 and 3,000 VINs. Files outside this range return 202 Accepted at submission but the job will fail during processing with an error in the status response.
Maximum file size: 10 MB

vin
1HGCM82633A004352
5YJSA1E26MF123456
WBAJB0C51JB084264

Output File Format

Results are delivered as a gzip-compressed JSONL file (one JSON object per line, one line per submitted VIN).

Each line contains the NeoVIN decode result for that VIN. The http_status_code field indicates the decode outcome for each record.

For the complete list of decode fields (make, model, trim, features, equipment, colors, etc.), see the Response Schema above. The batch output includes all the same fields plus the batch-specific fields below.

Batch-Specific Fields

Field	Type	Description
`http_status_code`	integer	Decode outcome: `200` = success, `400` = invalid VIN, `422` = undecodable, `500` = processing error
`message`	string	Error description. Present when `http_status_code` is not `200`.
`reason`	string	Detailed failure reason. Present when `http_status_code` is `422`.

Examples

Successful decode (200):

{
  "http_status_code": 200,
  "vin": "1HGCM82633A004352",
  "make": "Honda",
  "model": "Accord",
  "year": 2003,
  "trim": "EX",
  "engine": "3L V6",
  "fuel_type": "Unleaded",
  "city_mpg": 21,
  "highway_mpg": 32,
  "msrp": 25900,
  "squish_vin": "1HGCM826A",
  "seating_capacity": 5,
  "width": 73.0,
  "height": 56.5,
  "length": 191.0,
  "country": "USA",
  "manufacturer_code": "CM8263JNW"
}

Invalid VIN (400):

{
  "http_status_code": 400,
  "vin": "ZPBUB3ZL9RLA33"
  "message": "Request validation failed: Parameter (vin) is too short (14 chars), minimum 17",
}

Undecodable VIN (422):

{
  "http_status_code": 422,
  "vin": "SUXWZ7C36H0X38975"
  "message": "Unable to decode SUXWZ7C36H0X38975",
  "reason": "NO SPECS|INVALID VIN",
}

Processing error (500):

{
  "http_status_code": 500,
  "vin": "5YJSA1E26MF123456",
  "message": "Something went wrong"
}

Webhook Payloads

When you register a webhook_url at submission time, you receive notifications when the job completes or fails.

job.completed:

{
    "event": "job.completed",
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "item_count": 2500,
    "successful_count": 2450,
    "failed_count": 50,
    "completed_at": "2026-03-15T14:45:00Z"
}

Field	Type	Description
`event`	string	`"job.completed"`
`job_id`	string	Job identifier (UUID)
`status`	string	`"COMPLETED"`
`item_count`	integer	Total VINs processed
`successful_count`	integer	VINs successfully decoded
`failed_count`	integer	VINs that could not be decoded
`completed_at`	string	Completion timestamp (ISO 8601)

job.failed:

{
    "event": "job.failed",
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "FAILED",
    "error_code": "processing_failed",
    "error_message": "Job processing failed unexpectedly. Please resubmit.",
    "completed_at": "2026-03-15T14:45:00Z"
}

Field	Type	Description
`event`	string	`"job.failed"`
`job_id`	string	Job identifier (UUID)
`status`	string	`"FAILED"`
`error_code`	string	Machine-readable error code
`error_message`	string	Human-readable error description
`completed_at`	string	Failure timestamp (ISO 8601)