Search the SYNTHETIC demo inventory (about 860 fictional vehicles at 20 fictional dealers in TX, CA, FL, GA, AZ,
IL, NY and OH). Results are not real vehicles for sale; say so when you show them.
Each result has listing_id (dealer_key:VIN), vehicle basics, headline_price (before tax, title and fees), dealer_name,
and selling_location: the store that holds the unit, with address and phone. link_status is linked, or ambiguous
when the listing does not say which of the dealer's stores holds it (see selling_location_candidates). A unit can
be held at a sister store run by another dealer in the same group; operated_by_dealer_id then differs from dealer_id.
Matching is exact on vocabularies, so a total of 0 often means a wrong value: check the parameter descriptions,
widen radius_miles or drop a filter; a zero total also returns hints.
The named parameters are shortcuts. filters reaches every other attribute: for example
{"field": "canonical.vin", "op": "eq", "value": "<VIN>"} finds a VIN, {"field": "price_summary.doc_fee", "op": "range",
"max": 300}, {"field": "incentives[].label_raw", "op": "eq", "value": "Military Appreciation"}.
Payment search: payment_max / payment_min filter on a DEMO monthly finance estimate computed per listing from its
itemized out-the-door estimate (tax, title, registration, dealer fees) for the buyer location, minus down payment and
trade equity, at a demo APR by credit tier unless apr is given. Each result then has estimated_payment (rounded to
$5, with a range) and dealer_advertised_payment when the listing shows one; the response has payment_assumptions
and a one-line assumptions_summary to read back to the shopper. For 'under $300/month' pass max_monthly_payment=300.
With a cap, near_misses lists up to 3 cars just above it, and a zero result returns to_reach_target (extra down
payment, or a 72 or 84 month term). To compare scenarios for one car, use compare_payment_scenarios.
Every result has estimated_out_the_door (exact, same as estimate_out_the_door for the buyer location), availability
(status, price_valid_until, last_updated, observed_at), seating_capacity, third_row and cargo_capacity_cu_ft
(synthetic demo specs). sort=best_value score = 0.35 * cost_score + 0.30 * age_score + 0.35 * mileage_score
(formula in best_value_formula). A zero result with zip returns coverage: nearest_store, nearest_new_inventory and
nearest_qualifying_inventory with distance, match count and lowest out the door, plus a coverage_note.
estimated_out_the_door on results and near_misses carries the same warnings and excluded_items (for example an
optional add-on's name and price) that estimate_out_the_door returns. Each result has group_id, region_id and store_id
(dealer hierarchy; also filterable) and dealer_segment / dealer_type,
third_row_type and sliding_doors. With payment inputs, estimated_payment has financing_eligibility, credit_tier and
credit_tier_source (default when not given), negative_equity_rolled_in, loan_to_value_pct and warnings; the response
has financing_summary. Pass financeable_only=true to drop listings the demo financing rules flag.
Estimate, not an offer; dealer sets price, lender sets rate. Not penny-accurate.
View input schema
{
"type": "object",
"properties": {
"make": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Make, case-insensitive, e.g. Honda, Ford, Tesla. 14 makes are present.",
"title": "Make"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Model with its punctuation, case-insensitive: CR-V, F-150, Model 3, Mustang Mach-E.",
"title": "Model"
},
"year_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Earliest model year.",
"title": "Year Min"
},
"year_max": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Latest model year.",
"title": "Year Max"
},
"trim": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trim name, e.g. LX, EX-L, Lariat.",
"title": "Trim"
},
"condition": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "new, used or cpo (certified pre-owned). used also returns cpo units.",
"title": "Condition"
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Two-letter code of the selling store's state: TX, CA, FL, GA, AZ, IL, NY or OH. Not the full name.",
"title": "State"
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Exact city of the selling store (for example Houston, Katy, Plano). Suburbs are separate cities, so for 'in or near a city' prefer zip plus radius_miles.",
"title": "City"
},
"dealer_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Dealer key from list_dealers, e.g. lonemesa.",
"title": "Dealer Key"
},
"price_min": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum headline price in USD (before tax, title and dealer fees).",
"title": "Price Min"
},
"price_max": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum headline price in USD (before tax, title and dealer fees). For a budget that includes taxes and fees, check estimate_out_the_door.",
"title": "Price Max"
},
"max_mileage": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum odometer miles.",
"title": "Max Mileage"
},
"body_style": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "suv, sedan, pickup, hatchback, minivan or wagon. Use pickup for trucks.",
"title": "Body Style"
},
"fuel_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "gasoline, hybrid, plug_in_hybrid or electric. Use electric for EV or BEV.",
"title": "Fuel Type"
},
"drivetrain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "fwd, awd, rwd or 4wd.",
"title": "Drivetrain"
},
"zip": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Five-digit US ZIP of the shopper. With radius_miles, filters by straight-line distance to the selling store and adds distance_miles to each result.",
"title": "Zip"
},
"radius_miles": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Radius in miles around zip.",
"title": "Radius Miles"
},
"exterior_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Exterior color family: white, black, silver, gray, blue, red, green or bronze.",
"title": "Exterior Color"
},
"filters": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/FieldFilter"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Generic filters on ANY ontology field (vehicle, listing, store, dealer, price, fee, incentive, media, payment). All filters must match. See list_searchable_fields.",
"title": "Filters"
},
"payment_min": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum estimated monthly finance payment in USD (demo estimate).",
"title": "Payment Min"
},
"payment_max": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "DEPRECATED alias of max_monthly_payment (still accepted; the lower wins if both are given).",
"title": "Payment Max"
},
"max_monthly_payment": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Canonical monthly payment cap: the shopper's monthly budget in USD, e.g. 300 for 'under $300/month' (demo estimate).",
"title": "Max Monthly Payment"
},
"max_out_the_door": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum estimated out-the-door total in USD for the buyer location (tax, title, registration, dealer fees, minus trade). Exact, unrounded, and the same figure estimate_out_the_door returns for the same inputs.",
"title": "Max Out The Door"
},
"min_out_the_door": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum estimated out-the-door total in USD (same basis as max_out_the_door).",
"title": "Min Out The Door"
},
"seating_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum seats, e.g. 7 for a third row family vehicle (synthetic demo spec).",
"title": "Seating Min"
},
"third_row": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True for third row seating only, false to exclude it (synthetic demo spec).",
"title": "Third Row"
},
"third_row_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "full (adult-usable, car-seat capable) or compact (small, occasional; e.g. Tiguan). Demo spec.",
"title": "Third Row Type"
},
"sliding_doors": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True for sliding rear doors (minivans).",
"title": "Sliding Doors"
},
"dealer_segment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "franchise, independent_used or bhph (buy-here-pay-here). Each result shows dealer_segment and dealer_type.",
"title": "Dealer Segment"
},
"group_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Dealer group id (hierarchy: Group, then Region, then Store), e.g. meridian. See list_dealers.",
"title": "Group Id"
},
"region_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Region inside a group, as group_id/region_id (e.g. meridian/dfw-metro) or a bare region id.",
"title": "Region Id"
},
"store_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Store id, dealer_key plus store ZIP, e.g. bluebonnetridge-75201.",
"title": "Store Id"
},
"financeable_only": {
"default": false,
"description": "True to drop listings whose payment estimate fails the demo financing rules (minimum amount financed, max term by age and mileage) at these terms. Recommended with max_monthly_payment; financing_summary counts what was dropped.",
"title": "Financeable Only",
"type": "boolean"
},
"best_value_needs": {
"anyOf": [
{
"items": {
"enum": [
"seats",
"cargo",
"full_third_row",
"sliding_doors",
"low_mileage",
"newer",
"budget_headroom"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "With sort=best_value, shopper needs that also score: seats, cargo, full_third_row, sliding_doors, low_mileage, newer, budget_headroom (needs max_out_the_door). Score = 0.70 x base + 0.30 x mean need score; ranking_rationale shows each part.",
"title": "Best Value Needs"
},
"include_near_misses": {
"default": true,
"description": "With a payment cap, also return up to 3 listings within $25 above it in near_misses, flagged above_target. Default true.",
"title": "Include Near Misses",
"type": "boolean"
},
"eligible_incentive_labels": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "label_raw values of conditional incentives the buyer says they qualify for; applied to payment estimates where a listing offers them. Off by default.",
"title": "Eligible Incentive Labels"
},
"scenarios": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/PaymentScenario"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional what-if finance scenarios (up to 6). Each returned listing gets payment_scenarios with payment, amount financed, total interest and total cost per scenario. Filter and sort still use the main inputs.",
"title": "Scenarios"
},
"include_payment": {
"default": false,
"description": "True to add estimated_payment to every result without filtering on it.",
"title": "Include Payment",
"type": "boolean"
},
"down_payment": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Cash down in USD for payment estimates. Default 0.",
"title": "Down Payment"
},
"trade_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Trade-in allowance in USD (gets the trade-in tax credit where the state allows it).",
"title": "Trade Value"
},
"payoff": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Loan payoff owed on the trade-in, USD.",
"title": "Payoff"
},
"trade_equity": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Net trade equity in USD if allowance and payoff are unknown (negative for upside-down); no tax credit is applied for it.",
"title": "Trade Equity"
},
"apr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "APR percent for payment estimates. If omitted, a demo APR by credit_tier is used.",
"title": "Apr"
},
"credit_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "excellent, good (default), fair or poor; picks the demo APR when apr is omitted. Credit tiers (demo APR new / used): excellent about 720 and up (6.0% / 8.5%); good about 660 to 719 (7.5% / 11.0%); fair about 620 to 659 (11.5% / 16.0%); poor below about 620 (15.5% / 20.0%).",
"title": "Credit Tier"
},
"term_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Loan term in months, 12 to 96. Default 60.",
"title": "Term Months"
},
"buyer_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Buyer's two-letter state for payment tax and fees. Default: the selling store's state.",
"title": "Buyer State"
},
"buyer_county": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Buyer's county (without 'County') for payment tax lines.",
"title": "Buyer County"
},
"buyer_city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Buyer's city for payment tax lines.",
"title": "Buyer City"
},
"buyer_zip": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Buyer's ZIP; fills any missing buyer state, county and city. If no buyer location is given, zip is used, then the selling store (see out_the_door_assumptions.buyer).",
"title": "Buyer Zip"
},
"sort": {
"default": "price_asc",
"description": "price_asc (default), price_desc, year_desc, mileage_asc, distance_asc (needs zip), payment_asc, payment_desc, otd_asc (estimated out the door) or best_value (documented score over out-the-door cost, age and mileage; each result gets ranking_rationale).",
"title": "Sort",
"type": "string"
},
"limit": {
"default": 20,
"description": "Results per page, 1 to 50. Each result is about 2 KB; 5 to 10 is usually enough.",
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"description": "Paging offset.",
"title": "Offset",
"type": "integer"
}
},
"$defs": {
"FieldFilter": {
"description": "One generic filter on any ontology field (see list_searchable_fields).",
"properties": {
"field": {
"description": "Dotted field path from list_searchable_fields, e.g. canonical.exterior_color.family, price_summary.doc_fee, incentives[].label_raw, store.name, payment.estimated_monthly. Shortcut names such as make, model, color, price, state also work.",
"title": "Field",
"type": "string"
},
"op": {
"default": "eq",
"description": "eq exact (case-insensitive text); any_of with values; contains (text substring); range with min and/or max (numbers or ISO dates, inclusive); bool with value true/false; exists.",
"enum": [
"eq",
"any_of",
"contains",
"range",
"bool",
"exists"
],
"title": "Op",
"type": "string"
},
"value": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Value for eq, contains, bool or exists.",
"title": "Value"
},
"values": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Values for any_of.",
"title": "Values"
},
"min": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound for range (inclusive).",
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound for range (inclusive).",
"title": "Max"
},
"negate": {
"default": false,
"description": "True to invert the filter.",
"title": "Negate",
"type": "boolean"
}
},
"required": [
"field"
],
"title": "FieldFilter",
"type": "object"
},
"PaymentScenario": {
"description": "One what-if finance scenario. Omitted fields use the call's defaults ($0 down, 60 months, good credit).",
"properties": {
"name": {
"anyOf": [
{
"maxLength": 60,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Short label, e.g. '3k down 72 mo'.",
"title": "Name"
},
"down_payment": {
"anyOf": [
{
"maximum": 500000,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Cash down in USD.",
"title": "Down Payment"
},
"term_months": {
"anyOf": [
{
"maximum": 96,
"minimum": 12,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Loan term in months, 12 to 96.",
"title": "Term Months"
},
"credit_tier": {
"anyOf": [
{
"enum": [
"excellent",
"good",
"fair",
"poor"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Picks the demo APR when apr is omitted. Credit tiers (demo APR new / used): excellent about 720 and up (6.0% / 8.5%); good about 660 to 719 (7.5% / 11.0%); fair about 620 to 659 (11.5% / 16.0%); poor below about 620 (15.5% / 20.0%).",
"title": "Credit Tier"
},
"apr": {
"anyOf": [
{
"maximum": 36,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "APR percent; overrides credit_tier.",
"title": "Apr"
},
"trade_value": {
"anyOf": [
{
"maximum": 500000,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Trade-in allowance in USD (gets the state's trade-in tax credit).",
"title": "Trade Value"
},
"payoff": {
"anyOf": [
{
"maximum": 500000,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Loan payoff owed on the trade-in, USD.",
"title": "Payoff"
},
"trade_equity": {
"anyOf": [
{
"maximum": 500000,
"minimum": -500000,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Net trade equity if allowance and payoff are unknown; no tax credit.",
"title": "Trade Equity"
},
"eligible_incentive_labels": {
"anyOf": [
{
"items": {
"type": "string"
},
"maxItems": 10,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "label_raw values of conditional incentives the buyer qualifies for.",
"title": "Eligible Incentive Labels"
},
"cash": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True to price paying cash: no loan or interest; omit apr, term_months, credit_tier and down_payment.",
"title": "Cash"
}
},
"title": "PaymentScenario",
"type": "object"
}
},
"title": "search_inventoryArguments"
}