Estimate a vehicle's current market value from a VIN. Use /v2/marketvalue for new integrations: it returns vehicle identity plus wholesale and retail values across condition tiers. Add mileage, state, and condition when you want the estimate adjusted for a specific vehicle and market.

Who uses this API

Dealerships, lenders, fleet operators, and warranty providers call this endpoint to price a vehicle from a VIN — wholesale, retail, and condition-adjusted bands for appraisals, trade-ins, and loan-to-value.

Use cases

B2B

Dealerships — trade-in and retail pricing: Adjust wholesale and retail bands by mileage, state, and condition before making an offer.
Lenders — loan-to-value: Use wholesale and retail buckets to size a loan or lease residual.
Fleet — asset valuation: Track depreciation and end-of-life value across a VIN list.

B2C

Consumer “what’s my car worth?” widgets: Show a private seller or buyer a condition-tiered estimate from a VIN.
Marketplace asking-price hints: Suggest a listing price after the seller enters a VIN and mileage.

Parameters

Parameter	Required	Description
`vin`	Yes	The 17-character vehicle identification number
`key`	Yes	Your CarsXE API key
`state`	No	US state used for regional adjustment. Example: `CA`
`mileage`	No	Current odometer reading (miles in the US, kilometers in Canada). Must be numeric. When you pass `mileage` with `condition`, the API selects the matching `mileage_list` band and writes that band into the `mileage_` fields, then recalculates `adjusted_`. Omit `mileage` to apply bands yourself from `mileage_list`.
`condition`	No	One of `excellent`, `clean`, `average`, or `rough`. `excellent` maps to the `xclean` response tier. Used with `mileage` to apply the matching mileage band.

If condition is omitted, use the returned condition buckets to choose the value range that matches your workflow.

Example

Get market value

Code

curl -G https://api.carsxe.com/v2/marketvalue \
  -d key=YOUR_API_KEY \
  -d vin=WBAFR7C57CC811956 \
  -d mileage=50000 \
  -d state=CA \
  -d condition=clean

Response

Top-level shape

{

"uid": "6AA32D4C",// valuation record identifier

"publish_date": "8/29/2025",// provider valuation publish date

"data_freq": "D",// daily refresh

"state": "CA",

"country": "US",

"uvc": "2017485075",

"group_num": "4163",

"model_year": "2017",

"make": "Kia",

"model": "Forte",

"series": "LX",

"style": "4D Sedan",

"mileage_cat": "B",

"class_code": "A",

"class_name": "Small Car",

"description_score": "",

"first_values_flag": false,

"risk_score": "",

"region2": 50,// raw regional amounts; selected state copies onto regional_*

"region3": 25,

"region4": -25,

"region5": 0,

"region6": 0,

"msrp": 17600,

"retail_equipped": 18820,

"price_includes": "AC",

"wheel_base": 106.3,

"tire_size": "195/65R15",

"seat_cap": "5",

"fuel_type": "Gas",

"fuel_cap": "13.2",

"fuel_delivery": "MPI",

"hwy_mpg": "38",

"city_mpg": "29",

"engine_description": "2.0L I-4 MPI DOHC ",

"cylinders": "4",

"engine_displacement": "2.0L",

"base_hp": "147 @ 6200",

"taxable_hp": 16.7,

"torque": "132 @ 4500",

"drivetrain": "FWD",

"num_gears": "6",

"ext_doors": "4",

"airbags": "Side Curtain",

"anti_corrosion_warranty": "5-year/100,000-mile, Limited",

"basic_warranty": "5-year/60,000-mile, Limited",

"road_assist_warranty": "5-year/60,000-mile",

"retail": 6550,// summary scalars

"trade_in": 5055,

"rough_trade_in": 2205,

"average_trade_in": 3705,

"loan_value": 8575,

"trade_in_values": [],

}

Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference.

All response fields are optional. Missing value buckets mean the provider did not return that valuation for the VIN or market context. Some vehicles also return extra spec fields such as gvw, payload_cap, seats, transmission, engine_turbocharged, oil_cap, or navigation.

How mileage and options affect values

Each condition object is built the same way:

adjusted_* = base_* + mileage_* + add_deduct_* + regional_*

Mileage. mileage_list is the full table of odometer bands. If you pass the mileage query parameter with condition, the API selects the band where range_begin <= mileage <= range_end and writes that band's condition amount into the matching mileage_* fields, then recalculates adjusted_*. excellent maps to xclean. If you omit mileage, mileage_* stays at the provider default (often 0) and you can apply a band yourself from mileage_list.
Options / equipment. add_deduct_list is the table of option adds and deducts (uoc, name, amounts by condition, auto, residual months). These adjust market value based on options the vehicle may have or lack (for example w/o Auto Trans). The add_deduct_* fields on each condition object hold the option adjustment already applied to that bucket.
Region. Passing state selects a regional market. region2–region6 are the raw regional amounts; the selected region's amount also appears on each condition object as regional_*.

Identity and request echo

Name
uid
Type
string
Description
Valuation record identifier.
Name
input
Type
object
Description
Echo of request inputs: vin, plus state and country when they were used.
Name
publish_date
Type
string
Description
Provider valuation publish date. Example: "8/29/2025".
Name
data_freq
Type
string
Description
How often the provider refreshes this valuation. "D" means daily.
Name
state
Type
string
Description
Market region used for the valuation.
Name
country
Type
string
Description
Country used for the valuation.
Name
uvc
Type
string
Description
Unique vehicle code for this configuration.
Name
group_num
Type
string
Description
Provider grouping used to associate the vehicle with a market segment.
Name
model_year
Type
string
Description
Vehicle model year.
Name
make
Type
string
Description
Manufacturer.
Name
model
Type
string
Description
Model name.
Name
series
Type
string
Description
Trim or series.
Name
style
Type
string
Description
Body style. Example: "4D Sedan".
Name
mileage_cat
Type
string
Description
Mileage category for this configuration. Matches mileage_cat on mileage_list rows.
Name
class_code
Type
string
Description
Vehicle class code.
Name
class_name
Type
string
Description
Human-readable vehicle class. Example: "Small Car".
Name
description_score
Type
string
Description
Provider description-quality score when supplied.
Name
first_values_flag
Type
boolean
Description
Whether this is the first published value set for the vehicle.
Name
risk_score
Type
string
Description
Provider risk score when supplied.

Condition valuation objects

Wholesale (whole_*), retail (retail_*), and trade-in (trade_in_*) objects use the same five nested fields. The * is replaced by the family and condition, for example base_retail_clean.

Family	Objects
Wholesale	`whole_xclean`, `whole_clean`, `whole_avg`, `whole_rough`
Retail	`retail_xclean`, `retail_clean`, `retail_avg`, `retail_rough`
Trade-in	`trade_in_clean`, `trade_in_avg`, `trade_in_rough`

Name
base_*
Type
number
Description
Base valuation before mileage, equipment, or regional adjustments.
Name
mileage_*
Type
number
Description
Mileage-band adjustment. Auto-applied when you pass mileage and condition; otherwise often 0.
Name
add_deduct_*
Type
number
Description
Option/equipment adjustment already applied to this bucket. See add_deduct_list for the per-option rows.
Name
regional_*
Type
number
Description
Regional market adjustment from the selected state.
Name
adjusted_*
Type
number
Description
Final value for the bucket: base_* + mileage_* + add_deduct_* + regional_*.

The request parameter condition=excellent maps to the xclean tier.

mileage_list

Table of mileage or kilometer bands with value adjustments per condition. Live responses include many rows covering 1 through 999999. Use a band yourself when you did not pass mileage.

Name
model_year
Type
string
Description
Model year this band applies to.
Name
range_begin
Type
number
Description
Inclusive start of the odometer band.
Name
range_end
Type
number
Description
Inclusive end of the odometer band.
Name
xclean
Type
number
Description
Adjustment for extra-clean / excellent condition.
Name
clean
Type
number
Description
Adjustment for clean condition.
Name
avg
Type
number
Description
Adjustment for average condition.
Name
rough
Type
number
Description
Adjustment for rough condition.
Name
finadv
Type
number
Description
Finance-advance adjustment for this band, when the provider supplies one.
Name
mileage_cat
Type
string
Description
Mileage category for the band. Matches top-level mileage_cat.

add_deduct_list

Option and equipment adds and deducts. These adjust market value based on options the vehicle may have. Each row is one option (or the absence of an option).

Name
uoc
Type
string
Description
Unique option code.
Name
name
Type
string
Description
Option or equipment name. Example: "w/o Auto Trans".
Name
xclean
Type
number
Description
Add/deduct amount for extra-clean / excellent condition.
Name
clean
Type
number
Description
Add/deduct amount for clean condition.
Name
avg
Type
number
Description
Add/deduct amount for average condition.
Name
rough
Type
number
Description
Add/deduct amount for rough condition.
Name
auto
Type
string
Description
Whether the option is treated as automatic / default (Y or N).
Name
resid12
Type
number
Description
Residual amount at 12 months. The same pattern continues as resid24, resid30, resid36, resid42, resid48, resid60, and resid72.

Summary scalars and auction values

Name
retail
Type
number
Description
Typical retail asking value. Sourced from base_retail_avg.
Name
trade_in
Type
number
Description
Typical clean trade-in value. Sourced from base_trade_in_clean.
Name
rough_trade_in
Type
number
Description
Rough-condition trade-in value. Sourced from base_trade_in_rough.
Name
average_trade_in
Type
number
Description
Average-condition trade-in value. Sourced from base_trade_in_avg.
Name
loan_value
Type
number
Description
Typical loan / finance value. Sourced from base_retail_clean.
Name
trade_in_values
Type
array
Description
Historical trade-in series when the provider supplies one. Often an empty array on v2.
Name
auction_values
Type
object
Description
Auction price band for the vehicle.
Name
auction_values.low_auction_value
Type
number
Description
Low auction / wholesale-rough value.
Name
auction_values.average_auction_value
Type
number
Description
Average auction / wholesale-average value.
Name
auction_values.high_auction_value
Type
number
Description
High auction / wholesale-clean value.
Name
auction_values.date_range
Type
string
Description
Date the auction band applies. Typically the same as publish_date.
Name
model_number_list
Type
array of strings
Description
Factory model numbers associated with this configuration.

Regions

Name
region2
Type
number
Description
Regional adjustment amount for region 2.
Name
region3
Type
number
Description
Regional adjustment amount for region 3.
Name
region4
Type
number
Description
Regional adjustment amount for region 4.
Name
region5
Type
number
Description
Regional adjustment amount for region 5.
Name
region6
Type
number
Description
Regional adjustment amount for region 6.

The selected state determines which regional amount is copied onto each condition object's regional_* field.

Vehicle specs

Name
msrp
Type
number
Description
Manufacturer’s suggested retail price.
Name
retail_equipped
Type
number
Description
Retail price with typical factory equipment.
Name
price_includes
Type
string
Description
Options included in the priced configuration. Example codes: AC (air conditioning), AT (automatic transmission), LTH (leather), SR (sunroof).
Name
wheel_base
Type
number
Description
Wheelbase in inches.
Name
tire_size
Type
string
Description
Factory tire size. Example: "195/65R15".
Name
seat_cap
Type
string
Description
Seating capacity.
Name
fuel_type
Type
string
Description
Fuel type. Example: "Gas".
Name
fuel_cap
Type
string
Description
Fuel tank capacity in gallons.
Name
fuel_delivery
Type
string
Description
Fuel-delivery system. Example: "MPI".
Name
hwy_mpg
Type
string
Description
Highway fuel economy.
Name
city_mpg
Type
string
Description
City fuel economy.
Name
engine_description
Type
string
Description
Engine descriptor. Example: "2.0L I-4 MPI DOHC ".
Name
cylinders
Type
string
Description
Cylinder count.
Name
engine_displacement
Type
string
Description
Engine displacement. Example: "2.0L".
Name
base_hp
Type
string
Description
Base horsepower at RPM. Example: "147 @ 6200".
Name
taxable_hp
Type
number
Description
Taxable horsepower rating.
Name
torque
Type
string
Description
Engine torque at RPM. Example: "132 @ 4500".
Name
drivetrain
Type
string
Description
Drivetrain. Example: "FWD".
Name
num_gears
Type
string
Description
Number of transmission gears.
Name
ext_doors
Type
string
Description
Exterior door count.
Name
airbags
Type
string
Description
Airbag configuration. Example: "Side Curtain".
Name
anti_corrosion_warranty
Type
string
Description
Corrosion / rust warranty. Example: "5-year/100,000-mile, Limited".
Name
basic_warranty
Type
string
Description
Basic limited warranty. Example: "5-year/60,000-mile, Limited".
Name
road_assist_warranty
Type
string
Description
Roadside-assistance warranty. Example: "5-year/60,000-mile".

Errors

Status	When it happens
`400`	Missing VIN, wrong VIN length, invalid VIN, invalid mileage, or invalid condition
`401`	Missing or invalid API key
`404`	No market value data found for this VIN
`429`	Usage limit exceeded
`500`	Internal server error or non-retryable upstream authentication failure
`502`	Upstream market value provider returned an error; response includes `retryable: true` and `Retry-After`
`504`	Upstream market value provider timed out; response includes `retryable: true` and `Retry-After`

Valid condition values:

excellent, clean, average, rough

See the Errors guide for general error handling guidance.

Legacy v1 endpoint

Use /v2/marketvalue for new integrations. Legacy /marketvalue still exists for older integrations and returns simpler fields such as retail, tradeIn, roughTradeIn, averageTradeIn, loanValue, msrp, tradeInValues, and auctionValues.

curl -G https://api.carsxe.com/marketvalue \
  -d key=YOUR_API_KEY \
  -d vin=WBAFR7C57CC811956