MarketMatch

The MarketMatch API provides prescriptive vehicle-dealer matching using proprietary data science models. This powerful tool enables commercial sellers, dealers, and finance companies to optimize vehicle placement and sourcing decisions by identifying the best market fit between specific vehicles and dealerships.

MarketMatch analyzes dealer inventory patterns, sales velocity, and year-make-model affinity across tens of thousands of dealerships nationwide. Rankings are updated daily to reflect current market conditions, sold metrics, and active inventory status.

The API delivers actionable rankings at two levels:

• Dealer Ranking: Given a specific vehicle (VIN), rank potential dealer buyers by market fit
• Vehicle Ranking: Given a specific dealer, rank potential vehicle acquisitions by market fit

A VIN Rank of 1 indicates the strongest predicted match between vehicle and dealer, enabling data-driven decisions for vehicle sourcing, placement, and inventory optimization in wholesale and retail automotive markets. For high-volume workflows, MarketMatch also supports batch processing, allowing you to submit large files of vehicle data for asynchronous ranking—see the Batch API introduction for general batch concepts and best practices.

The Market Fit Problem

Inventory misfit represents one of the largest hidden costs in automotive retail. When vehicles are sold to or acquired by dealers that are not a natural market fit, the consequences are measurable:

• 16% of used dealer inventory is classified as misfit—roughly 1 in 6 vehicles
• $7.6B in annual industry impact from suboptimal vehicle-dealer matching
• 55 days average time to sale for mismatched vehicles vs. 34 days for well-matched
• $292 extra holding costs per mismatched unit
• $2,550 margin erosion per unit due to extended days on market

MarketMatch addresses this problem by providing quantitative market fit scores and prescriptive rankings, enabling data-driven placement and acquisition decisions.

How It Works

MarketMatch scores vehicles and dealers based on comprehensive inventory analytics derived from extensive retail market data. The API returns three key metrics:

API Endpoints

MarketMatch provides two complementary POST endpoints for different matching scenarios:

Base Path

Rank Dealers for a Vehicle

POST https://api.marketcheck.com/v2/marketmatch/dealers/rank

Use this endpoint when you have a specific vehicle and want to identify the best dealer matches. This is ideal for wholesale vehicle placement scenarios where you need to find optimal buyers for inventory.

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/marketmatch/dealers/rank',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    vin: {vin: 'WP1BE2AY5PDA28064', price: 20000, miles: 3000},
    dealers: [
      {source: 'mbofaugusta.com', zip: '30907'},
      {source: 'acceleride.mbofaugusta.com', zip: '30907'},
      {source: 'acceleride.esterobaychevrolet.com', zip: '33928'}
    ]
  }
};

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

Rank Vehicles for a Dealer

POST https://api.marketcheck.com/v2/marketmatch/vins/rank

Use this endpoint when you have a specific dealer and want to identify which vehicles are the best fit for their inventory. This is ideal for vehicle sourcing and acquisition scenarios.

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/marketmatch/vins/rank',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    dealer: {source: 'mbofaugusta.com', zip: '30907'},
    vins: [
      {vin: '5FNYF8H54SB000197', price: 37610, miles: 14428},
      {vin: 'JTJBM7FX1K5236458', price: 35087, miles: 73788},
      {vin: 'YV4L12RL4R1757085', price: 33085, miles: 45490}
    ]
  }
};

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

Request

Both MarketMatch endpoints accept JSON request bodies with vehicle and dealer specifications. The request structure differs based on whether you are ranking dealers or vehicles.

Authentication

Include your API key as a query parameter:

?api_key=YOUR_API_KEY

Request Body: Rank Dealers

When ranking dealers for a vehicle, provide a single VIN with a list of candidate dealers.

Schema

interface DealersRankRequest {
  vin: VINSpec; // Vehicle to match
  dealers: DealerSpec[]; // Candidate dealers (1-100 items)
}

interface VINSpec {
  vin: string; // 17-character VIN (required)
  price: number; // Vehicle price in USD (required)
  miles: number; // Vehicle mileage (required)
}

interface DealerSpec {
  source: string; // Dealer website domain (required)
  zip?: string; // 5-digit ZIP code (required for multi-location dealers)
  mc_location_id?: string; // MarketCheck location ID (alternative to zip)
}

Request Body: Rank Vehicles

When ranking vehicles for a dealer, provide a single dealer with a list of candidate VINs.

Schema

interface VINsRankRequest {
  dealer: DealerSpec; // Dealer to match
  vins: VINSpec[]; // Candidate vehicles (1-20 items)
}

The DealerSpec and VINSpec interfaces are the same as defined above for the dealers rank endpoint.

Field Constraints

Response

Both endpoints return the same response structure with ranked matches and any items that failed to process.

Schema

interface MarketMatchResponse {
  ranked_matches: RankedMatch[]; // Successfully ranked items, sorted by ranking
  failed_items: FailedMatch[]; // Items that could not be processed
}

interface RankedMatch {
  vin: string; // Vehicle Identification Number
  price: number; // Vehicle price
  miles: number; // Vehicle mileage
  source: string; // Dealer's domain/website
  zip: string; // Dealer's ZIP code
  mc_location_id: string; // MarketCheck location ID
  vin_score: number; // Score based on VIN matching (higher is better)
  dealer_ymm_score: number; // Dealer's Year/Make/Model expertise score
  vin_rank: number; // Overall ranking position (1 = best match)
}

interface FailedMatch {
  vin: string; // Vehicle Identification Number
  price: number; // Vehicle price
  miles: number; // Vehicle mileage
  source: string; // Dealer's domain/website
  zip: string; // Dealer's ZIP code
  mc_location_id: string; // MarketCheck location ID
  vin_score: null; // Null when matching failed
  dealer_ymm_score: null; // Null when matching failed
  vin_rank: null; // Null when matching failed
}

Key Metrics

Success Response

• 200 OK - Returns JSON object with ranked_matches and failed_items arrays
• Items in ranked_matches are sorted by vin_rank in ascending order (best match first)
• All monetary values are in USD
• Mileage values are in miles

Error Response

Error Response Format

Error responses include detailed information to help diagnose the issue:

{
  "code": <HTTP status code>,
  "message": "<Error message describing the issue>"
}

Use Cases & Examples

Wholesale Vehicle Placement

Commercial sellers, auction platforms, and wholesale marketplaces can optimize vehicle sales by identifying which dealers are the best fit for specific wholesale inventory. MarketMatch ranks potential dealer buyers based on their historical affinity for similar vehicles and current inventory levels.

Use the /dealers/rank endpoint with your vehicle details and a list of candidate dealer buyers.

Example:

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/marketmatch/dealers/rank',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    vin: {vin: 'WP1BE2AY5PDA28064', price: 20000, miles: 3000},
    dealers: [
      {source: 'mbofaugusta.com', zip: '30907'},
      {source: 'acceleride.mbofaugusta.com', zip: '30907'},
      {source: 'acceleride.esterobaychevrolet.com', zip: '33928'}
    ]
  }
};

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

Wholesale Vehicle Sourcing

Dealers can evaluate potential vehicle acquisitions from wholesale channels, trade-ins, auctions, or off-the-street purchases. MarketMatch ranks candidate vehicles based on how well they fit the dealer's inventory profile and market position.

Use the /vins/rank endpoint with your dealer details and a list of candidate vehicles.

Example:

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/marketmatch/vins/rank',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    dealer: {source: 'mbofaugusta.com', zip: '30907'},
    vins: [
      {vin: '5FNYF8H54SB000197', price: 37610, miles: 14428},
      {vin: 'JTJBM7FX1K5236458', price: 35087, miles: 73788},
      {vin: 'YV4L12RL4R1757085', price: 33085, miles: 45490}
    ]
  }
};

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

Dealer Network Inventory Optimization

Dealer groups can optimize inventory distribution across their network by identifying which rooftops are the best fit for specific vehicles. This enables data-driven inventory transfers that reduce days on market and improve overall network performance.

Use the /dealers/rank endpoint with multiple dealer locations from your network to identify underperforming inventory that should be relocated to stronger matches.

Example:

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/marketmatch/dealers/rank',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    vin: {vin: 'WP1BE2AY5PDA28064', price: 20000, miles: 3000},
    dealers: [
      {source: 'mbofaugusta.com', zip: '30907'},
      {source: 'acceleride.mbofaugusta.com', zip: '30907'},
      {source: 'acceleride.esterobaychevrolet.com', zip: '33928'}
    ]
  }
};

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

Wholesale Floor Plan Risk Assessment

Finance companies providing wholesale floor plan financing can assess dealer-vehicle fit as part of their risk evaluation. Vehicles with poor dealer fit may indicate higher risk of extended financing periods and potential margin compression.

Use the /vins/rank endpoint to evaluate a dealer's planned acquisitions and identify potential risk factors before extending credit.

Example:

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/marketmatch/vins/rank',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    dealer: {source: 'carvana.com', zip: '95765'},
    vins: [
      {vin: 'JTMDFREV7JJ214231', price: 25990, miles: 34307},
      {vin: '7YAKN4DA1SY001014', price: 38990, miles: 38990},
      {vin: 'KL79MPSL8SB184667', price: 20355, miles: 15313},
      {vin: '1FMCU0GD0JUD56190', price: 13790, miles: 73592},
      {vin: '4T1C11BKXNU065125', price: 22590, miles: 50947}
    ]
  }
};

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

Batch MarketMatch Rank

In addition to the single-vehicle ranking endpoint, you can submit large batches of vehicle data for ranking in a single request. Upload a gzip-compressed CSV file, track processing progress, and download the ranked results as a CSV file.

Batch API Endpoints

Submit Job

Create a new batch MarketMatch ranking job.

POST https://api.marketcheck.com/v2/batch/marketmatch/rank/jobs

  // Loading...

Parameters

Send the request as multipart/form-data.

Response

Status: 202 Accepted

{
    "job_id": "770a9622-a4bd-63f6-c938-668877662222",
    "status": "PROCESSING",
    "client_reference": "ranking-batch-2026-04",
    "created_at": "2026-04-01T10:00:00Z"
}

Errors

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/marketmatch/rank/jobs/{job_id}

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/batch/marketmatch/rank/jobs/770a9622-a4bd-63f6-c938-668877662222',
  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

Response

Status: 200 OK

During processing:

{
    "job_id": "770a9622-a4bd-63f6-c938-668877662222",
    "status": "PROCESSING",
    "progress_percent": 55,
    "item_count": 1200,
    "client_reference": "ranking-batch-2026-04",
    "created_at": "2026-04-01T10:00:00Z"
}

When completed:

{
    "job_id": "770a9622-a4bd-63f6-c938-668877662222",
    "status": "COMPLETED",
    "progress_percent": 100,
    "item_count": 1200,
    "successful_count": 1150,
    "failed_count": 0,
    "client_reference": "ranking-batch-2026-04",
    "created_at": "2026-04-01T10:00:00Z",
    "completed_at": "2026-04-01T10:12:00Z",
    "download_available": true,
    "download_count": 0,
    "max_downloads": 3,
    "remaining_downloads": 3
}

When failed:

{
    "job_id": "770a9622-a4bd-63f6-c938-668877662222",
    "status": "FAILED",
    "progress_percent": 55,
    "item_count": 1200,
    "client_reference": "ranking-batch-2026-04",
    "created_at": "2026-04-01T10:00:00Z",
    "error_code": "processing_failed",
    "error_message": "Job processing failed unexpectedly. Please resubmit."
}

Response Schema

Errors

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

List Jobs

Retrieve a paginated list of your batch ranking jobs.

GET https://api.marketcheck.com/v2/batch/marketmatch/rank/jobs

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/batch/marketmatch/rank/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

Filter definitions:

Response

Status: 200 OK

{
    "jobs": [
        {
            "job_id": "770a9622-a4bd-63f6-c938-668877662222",
            "status": "COMPLETED",
            "progress_percent": 100,
            "item_count": 1200,
            "successful_count": 1150,
            "failed_count": 0,
            "client_reference": "ranking-batch-2026-04",
            "created_at": "2026-04-01T10:00:00Z",
            "completed_at": "2026-04-01T10:12:00Z",
            "download_available": true,
            "download_count": 1,
            "max_downloads": 3,
            "remaining_downloads": 2
        },
        {
            "job_id": "881ba733-b5ce-74a7-d049-779988773333",
            "status": "PROCESSING",
            "progress_percent": 30,
            "item_count": 800,
            "client_reference": "ranking-batch-2026-03",
            "created_at": "2026-03-28T15:00:00Z"
        }
    ],
    "total": 15,
    "next_cursor": "eyJjIjoiMjAyNi0wMy0yOFQxNTowMDowMFoiLCJqIjoiODgxYmE3MzMtaDVjZS03NGc3LWQwNDktNzc5OTg4NzczMzMzIn0",
    "rows": 20
}

Errors

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

Download Results

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

POST https://api.marketcheck.com/v2/batch/marketmatch/rank/jobs/{job_id}/download

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/v2/batch/marketmatch/rank/jobs/770a9622-a4bd-63f6-c938-668877662222/download',
  params: {api_key: 'YOUR_API_KEY'}
};

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

Parameters

Response

Status: 200 OK

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

Errors

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

Input File Format

The input file must be a gzip-compressed CSV (.csv.gz) with:

• A header row with the required columns: vin, price, miles, source, zip
• UTF-8 encoding
• No minimum or maximum record count — the file size limit (100 MB compressed) is the practical constraint

Your CSV must include the following columns: vin, price, miles, source (dealer website domain), and zip (dealer ZIP code). Each row represents a vehicle-dealer pair to be ranked. Files with missing or invalid columns will cause the job to fail during processing.

Create the CSV first:

vin,price,miles,source,zip
vin_1,185000,31450,dealer_source_1.com,43056
vin_2,52000,12000,dealer_source_2.com,10001
vin_3,35000,32000,dealer_source_3.com,60601

Then gzip-compress it before uploading:

gzip vehicles.csv

Output File Format

Results are delivered as a gzip-compressed CSV file (.csv.gz). The output CSV contains the same columns as the input, with additional ranking columns added by the MarketMatch engine.

Decompress the file to view the results:

gunzip results.csv.gz

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": "770a9622-a4bd-63f6-c938-668877662222",
    "status": "COMPLETED",
    "item_count": 1200,
    "successful_count": 1150,
    "failed_count": 0,
    "completed_at": "2026-04-01T10:12:00Z"
}

job.failed:

{
    "event": "job.failed",
    "job_id": "770a9622-a4bd-63f6-c938-668877662222",
    "status": "FAILED",
    "error_code": "processing_failed",
    "error_message": "Job processing failed unexpectedly. Please resubmit.",
    "completed_at": "2026-04-01T10:12:00Z"
}

See Also

• Market Days Supply
• Inferred Sales Stats
• MarketCheck Price
• Inventory Search