search_inventory
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": ""} 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| apr | No | APR percent for payment estimates. If omitted, a demo APR by credit_tier is used. | |
| zip | No | 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. | |
| city | No | 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. | |
| make | No | Make, case-insensitive, e.g. Honda, Ford, Tesla. 14 makes are present. | |
| sort | No | 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). | price_asc |
| trim | No | Trim name, e.g. LX, EX-L, Lariat. | |
| limit | No | Results per page, 1 to 50. Each result is about 2 KB; 5 to 10 is usually enough. | |
| model | No | Model with its punctuation, case-insensitive: CR-V, F-150, Model 3, Mustang Mach-E. | |
| state | No | Two-letter code of the selling store's state: TX, CA, FL, GA, AZ, IL, NY or OH. Not the full name. | |
| offset | No | Paging offset. | |
| payoff | No | Loan payoff owed on the trade-in, USD. | |
| filters | No | Generic filters on ANY ontology field (vehicle, listing, store, dealer, price, fee, incentive, media, payment). All filters must match. See list_searchable_fields. | |
| group_id | No | Dealer group id (hierarchy: Group, then Region, then Store), e.g. meridian. See list_dealers. | |
| store_id | No | Store id, dealer_key plus store ZIP, e.g. bluebonnetridge-75201. | |
| year_max | No | Latest model year. | |
| year_min | No | Earliest model year. | |
| buyer_zip | No | 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). | |
| condition | No | new, used or cpo (certified pre-owned). used also returns cpo units. | |
| fuel_type | No | gasoline, hybrid, plug_in_hybrid or electric. Use electric for EV or BEV. | |
| price_max | No | Maximum headline price in USD (before tax, title and dealer fees). For a budget that includes taxes and fees, check estimate_out_the_door. | |
| price_min | No | Minimum headline price in USD (before tax, title and dealer fees). | |
| region_id | No | Region inside a group, as group_id/region_id (e.g. meridian/dfw-metro) or a bare region id. | |
| scenarios | No | 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. | |
| third_row | No | True for third row seating only, false to exclude it (synthetic demo spec). | |
| body_style | No | suv, sedan, pickup, hatchback, minivan or wagon. Use pickup for trucks. | |
| buyer_city | No | Buyer's city for payment tax lines. | |
| dealer_key | No | Dealer key from list_dealers, e.g. lonemesa. | |
| drivetrain | No | fwd, awd, rwd or 4wd. | |
| buyer_state | No | Buyer's two-letter state for payment tax and fees. Default: the selling store's state. | |
| credit_tier | No | 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%). | |
| max_mileage | No | Maximum odometer miles. | |
| payment_max | No | DEPRECATED alias of max_monthly_payment (still accepted; the lower wins if both are given). | |
| payment_min | No | Minimum estimated monthly finance payment in USD (demo estimate). | |
| seating_min | No | Minimum seats, e.g. 7 for a third row family vehicle (synthetic demo spec). | |
| term_months | No | Loan term in months, 12 to 96. Default 60. | |
| trade_value | No | Trade-in allowance in USD (gets the trade-in tax credit where the state allows it). | |
| buyer_county | No | Buyer's county (without 'County') for payment tax lines. | |
| down_payment | No | Cash down in USD for payment estimates. Default 0. | |
| radius_miles | No | Radius in miles around zip. | |
| trade_equity | No | Net trade equity in USD if allowance and payoff are unknown (negative for upside-down); no tax credit is applied for it. | |
| sliding_doors | No | True for sliding rear doors (minivans). | |
| dealer_segment | No | franchise, independent_used or bhph (buy-here-pay-here). Each result shows dealer_segment and dealer_type. | |
| exterior_color | No | Exterior color family: white, black, silver, gray, blue, red, green or bronze. | |
| third_row_type | No | full (adult-usable, car-seat capable) or compact (small, occasional; e.g. Tiguan). Demo spec. | |
| include_payment | No | True to add estimated_payment to every result without filtering on it. | |
| best_value_needs | No | 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. | |
| financeable_only | No | 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. | |
| max_out_the_door | No | 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. | |
| min_out_the_door | No | Minimum estimated out-the-door total in USD (same basis as max_out_the_door). | |
| include_near_misses | No | With a payment cap, also return up to 3 listings within $25 above it in near_misses, flagged above_target. Default true. | |
| max_monthly_payment | No | Canonical monthly payment cap: the shopper's monthly budget in USD, e.g. 300 for 'under $300/month' (demo estimate). | |
| eligible_incentive_labels | No | label_raw values of conditional incentives the buyer says they qualify for; applied to payment estimates where a listing offers them. Off by default. |