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.

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);
}

See Also

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