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.
When to use it
- Pricing inventory
- Estimating trade-in value
- Creating valuation workflows
- Comparing clean, average, rough, and extra-clean value ranges
- Adding valuation context after VIN decoding
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 mileage. Must be numeric |
condition | No | One of excellent, clean, average, or rough |
If condition is omitted, use the returned condition buckets to choose the value range that matches your workflow.
Example
Get market value
Response
Top-level shape
Click any value bucket 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.
- Name
uid- Type
- string
- Description
Valuation record identifier.
- Name
input- Type
- object
- Description
Echo of request inputs and inferred country.
- Name
publish_date- Type
- string
- Description
Provider valuation publish date.
- Name
state- Type
- string
- Description
Market region used for the valuation.
- Name
country- Type
- string
- Description
Country used for the valuation.
- 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.
- Name
class_name- Type
- string
- Description
Vehicle class.
- Name
whole_*- Type
- object
- Description
Wholesale values for a condition tier.
- Name
retail_*- Type
- object
- Description
Retail values for a condition tier.
How to read value buckets
Condition tiers - excellent, clean, average, and rough values
| Suffix | Meaning |
|---|---|
xclean | Excellent / extra-clean condition |
clean | Clean condition |
avg | Average condition |
rough | Rough condition |
The request parameter condition=excellent maps conceptually to the xclean tier in the response.
Value families - wholesale and retail buckets
| Prefix | Meaning |
|---|---|
whole_* | Wholesale-oriented valuation bucket |
retail_* | Retail-oriented valuation bucket |
Adjustment fields - base value plus mileage, add/deduct, and regional adjustments
The * is replaced by the value family and condition tier. For example, base_retail_clean is the base retail value for a clean vehicle.
- Name
base_*- Type
- number
- Description
Base valuation before mileage, equipment, or regional adjustments.
- Name
mileage_*- Type
- number
- Description
Mileage adjustment applied to the valuation.
- Name
add_deduct_*- Type
- number
- Description
Additions or deductions applied by the provider.
- Name
regional_*- Type
- number
- Description
Regional market adjustment.
Errors
| Status | When it happens |
|---|---|
400 | Missing VIN, wrong VIN length, 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 |
503 | Upstream market value provider unavailable |
Valid condition values:
excellent, clean, average, roughSee 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