{"openapi":"3.1.0","info":{"title":"Car Handshake Inventory API","version":"1.0.0","description":"Anonymous US dealership-inventory search. Every endpoint is server-bound to WEBSITE_SEARCH; publication channels are never caller-selectable.","contact":{"email":"support@dealerhandshake.com"}},"servers":[{"url":"https://api.carhandshake.com"}],"security":[],"tags":[{"name":"Vehicles","description":"Anonymous search and detail reads for published inventory."},{"name":"Dealers","description":"Dealers and rooftops with website-published inventory."},{"name":"Leads","description":"Explicitly consented customer-to-dealership requests."},{"name":"Discovery","description":"Schemas, facets, taxonomies, and US location resolution."}],"paths":{"/v1/vehicles":{"get":{"operationId":"searchVehicles","tags":["Vehicles"],"summary":"Search published US inventory","parameters":[{"name":"q","in":"query","schema":{"type":"string","minLength":2}},{"name":"zip","in":"query","schema":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"}},{"name":"latitude","in":"query","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"radius_miles","in":"query","description":"Inclusive radius in miles; requires a ZIP or coordinate origin.","schema":{"type":"number","minimum":1,"maximum":500,"default":50}},{"name":"nationwide","in":"query","schema":{"type":"boolean","default":false}},{"name":"north","in":"query","description":"Northern latitude of a map viewport. Requires south, east, and west.","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"south","in":"query","description":"Southern latitude of a map viewport.","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"east","in":"query","description":"Eastern longitude. A value lower than west explicitly crosses the antimeridian.","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"west","in":"query","description":"Western longitude of a map viewport.","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"map_clusters","in":"query","description":"Return bounded map clusters. Requires a viewport and map_zoom.","schema":{"type":"boolean","default":false}},{"name":"map_zoom","in":"query","description":"Web map zoom used for geotile clustering.","schema":{"type":"integer","minimum":0,"maximum":22}},{"name":"vehicle_type","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Repeatable; comma-separated values are also accepted."},{"name":"make","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Repeatable; comma-separated values are also accepted."},{"name":"model","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Repeatable; comma-separated values are also accepted."},{"name":"trim","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"condition","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["new","used","cpo"]}}},{"name":"body","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"fuel","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"driveline","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"transmission","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"exterior_color","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"interior_color","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"feature","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"dealer_id","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"year_min","in":"query","schema":{"type":"integer","minimum":1886,"maximum":2200}},{"name":"year_max","in":"query","schema":{"type":"integer","minimum":1886,"maximum":2200}},{"name":"price_min","in":"query","schema":{"type":"integer","minimum":0}},{"name":"price_max","in":"query","schema":{"type":"integer","minimum":0}},{"name":"mileage_max","in":"query","schema":{"type":"integer","minimum":0}},{"name":"seats_min","in":"query","schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"seats_max","in":"query","schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"doors_min","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"doors_max","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"city_mpg_min","in":"query","schema":{"type":"integer","minimum":0}},{"name":"highway_mpg_min","in":"query","schema":{"type":"integer","minimum":0}},{"name":"electric_range_min","in":"query","schema":{"type":"number","minimum":0}},{"name":"delivery_available","in":"query","schema":{"type":"boolean"}},{"name":"status","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["available","intransit"]}}},{"name":"sort","in":"query","schema":{"$ref":"#/components/schemas/SortBy"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"facet","in":"query","style":"form","explode":true,"schema":{"type":"array","maxItems":8,"items":{"type":"string","enum":["vehicle_type","make","model","trim","condition","body","fuel","year"]}}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/Problem"}}}},"/v1/vehicles/search":{"post":{"operationId":"searchVehiclesWithBody","tags":["Vehicles"],"summary":"Search with a structured JSON request","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/Problem"}}}},"/v1/vehicles/{listing_id}":{"get":{"operationId":"getVehicle","tags":["Vehicles"],"summary":"Get one published listing","parameters":[{"$ref":"#/components/parameters/ListingId"}],"responses":{"200":{"description":"Listing detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleListingDetail"}}}},"404":{"$ref":"#/components/responses/Problem"}}}},"/v1/vehicles/compare":{"post":{"operationId":"compareVehicles","tags":["Vehicles"],"summary":"Compare two to four published listings","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listing_ids"],"properties":{"listing_ids":{"type":"array","minItems":2,"maxItems":4,"items":{"type":"string","format":"uuid"}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Visible listings in requested order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleComparisonResponse"}}}},"400":{"$ref":"#/components/responses/Problem"}}}},"/v1/vehicles/{listing_id}/similar":{"get":{"operationId":"findSimilarVehicles","tags":["Vehicles"],"summary":"Find similar published listings","parameters":[{"$ref":"#/components/parameters/ListingId"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":6}}],"responses":{"200":{"description":"Similar listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"404":{"$ref":"#/components/responses/Problem"}}}},"/v1/facets":{"get":{"operationId":"getVehicleFacet","tags":["Discovery"],"summary":"Get one search facet","parameters":[{"name":"dimension","in":"query","required":true,"schema":{"type":"string","enum":["vehicle_type","make","model","trim","condition","body","fuel","year"]}},{"name":"q","in":"query","schema":{"type":"string","minLength":2,"maxLength":500}},{"name":"zip","in":"query","schema":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"}},{"name":"radius_miles","in":"query","description":"Inclusive radius in miles; requires a ZIP or coordinate origin.","schema":{"type":"number","minimum":1,"maximum":500,"default":50}},{"name":"make","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"model","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"condition","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["new","used","cpo"]}}},{"name":"year_min","in":"query","schema":{"type":"integer","minimum":1886,"maximum":2200}},{"name":"year_max","in":"query","schema":{"type":"integer","minimum":1886,"maximum":2200}},{"name":"north","in":"query","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"south","in":"query","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"east","in":"query","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"west","in":"query","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Facet buckets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetResponse"}}}}}}},"/v1/suggestions":{"get":{"operationId":"getVehicleSuggestions","tags":["Discovery"],"summary":"Autocomplete vehicle and dealer vocabulary","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionResponse"}}}}}}},"/v1/taxonomies":{"get":{"operationId":"getVehicleTaxonomies","tags":["Discovery"],"summary":"Get the supported US vehicle taxonomy and units","responses":{"200":{"description":"Versioned taxonomy values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxonomyResponse"}}}}}}},"/v1/locations/resolve":{"get":{"operationId":"resolveLocation","tags":["Discovery"],"summary":"Resolve a US ZIP or validate supplied coordinates","parameters":[{"name":"zip","in":"query","schema":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"}},{"name":"latitude","in":"query","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Resolved US location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationResolutionResponse"}}}},"400":{"$ref":"#/components/responses/Problem"}}}},"/v1/dealers":{"get":{"operationId":"listDealers","tags":["Dealers"],"summary":"Search dealerships with published website inventory","parameters":[{"name":"q","in":"query","schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Dealerships","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealerListResponse"}}}}}}},"/v1/dealers/{dealer_id}":{"get":{"operationId":"getDealer","tags":["Dealers"],"summary":"Get one dealership with published website inventory","parameters":[{"$ref":"#/components/parameters/DealerId"}],"responses":{"200":{"description":"Dealership","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealerDetail"}}}},"404":{"$ref":"#/components/responses/Problem"}}}},"/v1/dealers/{dealer_id}/locations":{"get":{"operationId":"listDealerLocations","tags":["Dealers"],"summary":"Get eligible US rooftops for a published dealership","parameters":[{"$ref":"#/components/parameters/DealerId"}],"responses":{"200":{"description":"Exact public rooftop locations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealerLocationsResponse"}}}},"404":{"$ref":"#/components/responses/Problem"}}}},"/v1/leads/inquiries":{"post":{"operationId":"submitVehicleInquiry","tags":["Leads"],"summary":"Send a consented vehicle inquiry to the listing dealership","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/CaptchaToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleInquiry"}}}},"responses":{"202":{"description":"Inquiry accepted for consented delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadAcknowledgement"}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/leads/test-drives":{"post":{"operationId":"scheduleTestDrive","tags":["Leads"],"summary":"Request a test-drive time from the listing dealership","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/CaptchaToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestDriveRequest"}}}},"responses":{"202":{"description":"Request accepted for consented delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadAcknowledgement"}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/leads/trade-ins":{"post":{"operationId":"requestTradeInAppraisal","tags":["Leads"],"summary":"Request a trade-in appraisal from the listing dealership","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/CaptchaToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeInAppraisal"}}}},"responses":{"202":{"description":"Appraisal request accepted for consented delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadAcknowledgement"}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApiDocument","tags":["Discovery"],"summary":"This OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}}}}}},"components":{"parameters":{"ListingId":{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"DealerId":{"name":"dealer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique key (8–200 characters) used to safely retry this submission.","schema":{"type":"string","minLength":8,"maxLength":200}},"CaptchaToken":{"name":"X-Captcha-Token","in":"header","required":false,"description":"Required for submissions originating from the first-party Car Handshake browser app; connector and direct API clients do not send it.","schema":{"type":"string","minLength":1,"maxLength":4096}}},"responses":{"Problem":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"SortBy":{"type":"string","enum":["relevance","distance","price","mileage","year","freshness"]},"TextFilterValues":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":100}},"GeoViewport":{"type":"object","required":["north","south","east","west"],"description":"Strict WGS84 viewport. North must exceed south. East lower than west represents an antimeridian-crossing box.","properties":{"north":{"type":"number","minimum":-90,"maximum":90},"south":{"type":"number","minimum":-90,"maximum":90},"east":{"type":"number","minimum":-180,"maximum":180},"west":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false},"GeoBounds":{"type":"object","required":["north","south","east","west"],"description":"Bounds of the listing coordinates represented by a map cluster.","properties":{"north":{"type":"number","minimum":-90,"maximum":90},"south":{"type":"number","minimum":-90,"maximum":90},"east":{"type":"number","minimum":-180,"maximum":180},"west":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false},"MapClusterResult":{"type":"object","required":["zoom","clusters","truncated"],"properties":{"zoom":{"type":"integer","minimum":0,"maximum":22},"truncated":{"type":"boolean","description":"True when more than 500 occupied map tiles matched the search."},"clusters":{"type":"array","maxItems":500,"items":{"type":"object","required":["id","center","count","bounds"],"properties":{"id":{"type":"string"},"center":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false},"count":{"type":"integer","minimum":1},"bounds":{"$ref":"#/components/schemas/GeoBounds"}},"additionalProperties":false}}},"additionalProperties":false},"DealerIdentity":{"type":"object","required":["id","name","domain"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string"},"agent_card_url":{"type":"string","format":"uri"}}},"PublicDealer":{"allOf":[{"$ref":"#/components/schemas/DealerIdentity"}],"unevaluatedProperties":false},"PublicPhone":{"type":"object","required":["name","value"],"properties":{"name":{"type":["string","null"]},"value":{"type":"string"}},"additionalProperties":false},"BusinessHoursInterval":{"type":"object","required":["open","close"],"properties":{"open":{"type":"string"},"close":{"type":"string"}},"additionalProperties":false},"BusinessHoursSchedule":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"monday":{"oneOf":[{"$ref":"#/components/schemas/BusinessHoursInterval"},{"type":"null"}]},"tuesday":{"oneOf":[{"$ref":"#/components/schemas/BusinessHoursInterval"},{"type":"null"}]},"wednesday":{"oneOf":[{"$ref":"#/components/schemas/BusinessHoursInterval"},{"type":"null"}]},"thursday":{"oneOf":[{"$ref":"#/components/schemas/BusinessHoursInterval"},{"type":"null"}]},"friday":{"oneOf":[{"$ref":"#/components/schemas/BusinessHoursInterval"},{"type":"null"}]},"saturday":{"oneOf":[{"$ref":"#/components/schemas/BusinessHoursInterval"},{"type":"null"}]},"sunday":{"oneOf":[{"$ref":"#/components/schemas/BusinessHoursInterval"},{"type":"null"}]}},"additionalProperties":false},"PublicLocation":{"type":"object","required":["id","name","address_line_1","address_line_2","city","state","zip","country","latitude","longitude","geo_source","geocode_precision","geocode_confidence","timezone","website_url","public_phone","hours","capabilities"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address_line_1":{"type":["string","null"]},"address_line_2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"country":{"const":"US"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"geo_source":{"type":["string","null"]},"geocode_precision":{"type":["string","null"]},"geocode_confidence":{"type":["number","null"],"minimum":0,"maximum":1},"timezone":{"type":["string","null"]},"website_url":{"type":["string","null"],"format":"uri"},"public_phone":{"oneOf":[{"$ref":"#/components/schemas/PublicPhone"},{"type":"null"}]},"hours":{"type":"array","items":{"$ref":"#/components/schemas/BusinessHoursSchedule"}},"capabilities":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"VehicleListingBase":{"type":"object","required":["listing_id","vin","stock","year","make","model","trim","condition","body","fuel","driveline","transmission","exterior_color","interior_color","price","msrp","mileage","electric_range_miles","status","primary_photo_url","updated_at","distance_miles","dealer","location","canonical_url","dealer_vdp_url"],"properties":{"listing_id":{"type":"string","format":"uuid"},"vin":{"type":"string"},"stock":{"type":["string","null"]},"year":{"type":"integer","minimum":1886,"maximum":2200},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":["string","null"]},"condition":{"type":["string","null"],"enum":["new","used","cpo",null]},"body":{"type":["string","null"]},"fuel":{"type":["string","null"]},"driveline":{"type":["string","null"]},"transmission":{"type":["string","null"]},"exterior_color":{"type":["string","null"]},"interior_color":{"type":["string","null"]},"price":{"type":["integer","null"],"minimum":0,"description":"Current advertised amount in USD, or null when the dealer omits it."},"msrp":{"type":["integer","null"],"minimum":0},"mileage":{"type":["integer","null"],"minimum":0},"electric_range_miles":{"type":["number","null"],"minimum":0},"status":{"type":"string","enum":["available","intransit"]},"primary_photo_url":{"type":["string","null"],"format":"uri"},"updated_at":{"type":"string","format":"date-time","description":"Freshness timestamp supplied by the canonical listing projection."},"distance_miles":{"type":["number","null"],"minimum":0},"dealer":{"$ref":"#/components/schemas/PublicDealer"},"location":{"$ref":"#/components/schemas/PublicLocation"},"canonical_url":{"type":["string","null"],"format":"uri","description":"Canonical Car Handshake VDP URL when website publication is permitted."},"dealer_vdp_url":{"type":["string","null"],"format":"uri"}}},"VehicleListingSummary":{"allOf":[{"$ref":"#/components/schemas/VehicleListingBase"}],"unevaluatedProperties":false},"VehicleListingDetail":{"allOf":[{"$ref":"#/components/schemas/VehicleListingBase"},{"type":"object","required":["description","engine","city_mpg","highway_mpg","photos","features"],"properties":{"description":{"type":["string","null"]},"engine":{"type":["string","null"]},"city_mpg":{"type":["integer","null"],"minimum":0},"highway_mpg":{"type":["integer","null"],"minimum":0},"photos":{"type":"array","items":{"type":"string","format":"uri"}},"features":{"type":"array","items":{"type":"string"}}}}],"unevaluatedProperties":false},"VehicleComparisonResponse":{"type":"array","maxItems":4,"items":{"$ref":"#/components/schemas/VehicleListingDetail"}},"FacetBucket":{"type":"object","required":["value","count"],"properties":{"value":{"type":["string","number"]},"count":{"type":"integer","minimum":0}},"additionalProperties":false},"FacetResponse":{"type":"array","items":{"$ref":"#/components/schemas/FacetBucket"}},"SuggestionResponse":{"type":"array","maxItems":20,"items":{"type":"string"}},"TaxonomyResponse":{"type":"object","required":["release","units","condition","status","fuel","driveline","body","sort"],"properties":{"release":{"const":"us-v1"},"units":{"type":"object","required":["currency","distance","odometer"],"properties":{"currency":{"const":"USD"},"distance":{"const":"miles"},"odometer":{"const":"miles"}},"additionalProperties":false},"condition":{"type":"array","items":{"type":"string","enum":["new","used","cpo"]}},"status":{"type":"array","items":{"type":"string","enum":["available","intransit"]}},"fuel":{"type":"array","items":{"type":"string","enum":["gas","diesel","hybrid","phev","electric","other"]}},"driveline":{"type":"array","items":{"type":"string","enum":["FWD","RWD","AWD","4WD"]}},"body":{"type":"array","items":{"type":"string","enum":["suv","truck","sedan","van","coupe","hatchback","convertible","wagon","trailer","other"]}},"sort":{"type":"array","items":{"$ref":"#/components/schemas/SortBy"}}},"additionalProperties":false},"ZipLocationResolution":{"type":"object","required":["input","resolved"],"properties":{"input":{"type":"object","required":["zip"],"properties":{"zip":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"}},"additionalProperties":false},"resolved":{"type":"object","required":["zip","city","state","country","latitude","longitude","precision"],"properties":{"zip":{"type":"string","pattern":"^\\d{5}$"},"city":{"type":"string"},"state":{"type":"string"},"country":{"const":"US"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"precision":{"const":"postal_code_centroid"}},"additionalProperties":false}},"additionalProperties":false},"CoordinateLocationResolution":{"type":"object","required":["input","resolved"],"properties":{"input":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false},"resolved":{"type":"object","required":["country","latitude","longitude","precision"],"properties":{"country":{"const":"US"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"precision":{"const":"provided_coordinate"}},"additionalProperties":false}},"additionalProperties":false},"LocationResolutionResponse":{"oneOf":[{"$ref":"#/components/schemas/ZipLocationResolution"},{"$ref":"#/components/schemas/CoordinateLocationResolution"}]},"DealerDetail":{"allOf":[{"$ref":"#/components/schemas/DealerIdentity"},{"type":"object","required":["locations","vehicle_count"],"properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/PublicLocation"}},"vehicle_count":{"type":"integer","minimum":0}}}],"unevaluatedProperties":false},"DealerListResponse":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/DealerDetail"}},"DealerLocationsResponse":{"type":"object","required":["dealer_id","locations"],"properties":{"dealer_id":{"type":"string","format":"uuid"},"locations":{"type":"array","items":{"$ref":"#/components/schemas/PublicLocation"}}},"additionalProperties":false},"SearchFilters":{"type":"object","properties":{"vehicle_types":{"$ref":"#/components/schemas/TextFilterValues"},"makes":{"$ref":"#/components/schemas/TextFilterValues"},"models":{"$ref":"#/components/schemas/TextFilterValues"},"trims":{"$ref":"#/components/schemas/TextFilterValues"},"conditions":{"type":"array","minItems":1,"items":{"type":"string","enum":["new","used","cpo"]}},"bodies":{"$ref":"#/components/schemas/TextFilterValues"},"fuels":{"$ref":"#/components/schemas/TextFilterValues"},"drivelines":{"$ref":"#/components/schemas/TextFilterValues"},"transmissions":{"$ref":"#/components/schemas/TextFilterValues"},"exterior_colors":{"$ref":"#/components/schemas/TextFilterValues"},"interior_colors":{"$ref":"#/components/schemas/TextFilterValues"},"features":{"$ref":"#/components/schemas/TextFilterValues"},"dealer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"year_min":{"type":"integer","minimum":1886,"maximum":2200},"year_max":{"type":"integer","minimum":1886,"maximum":2200},"price_min":{"type":"integer","minimum":0},"price_max":{"type":"integer","minimum":0},"mileage_max":{"type":"integer","minimum":0},"seats_min":{"type":"integer","minimum":1,"maximum":30},"seats_max":{"type":"integer","minimum":1,"maximum":30},"doors_min":{"type":"integer","minimum":1,"maximum":12},"doors_max":{"type":"integer","minimum":1,"maximum":12},"city_mpg_min":{"type":"integer","minimum":0},"highway_mpg_min":{"type":"integer","minimum":0},"electric_range_min":{"type":"number","minimum":0},"delivery_available":{"type":"boolean"},"statuses":{"type":"array","minItems":1,"items":{"type":"string","enum":["available","intransit"]}}},"additionalProperties":false},"SearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":500},"location":{"oneOf":[{"type":"object","required":["zip"],"properties":{"zip":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"},"radius_miles":{"type":"number","minimum":1,"maximum":500,"default":50}},"additionalProperties":false},{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"radius_miles":{"type":"number","minimum":1,"maximum":500,"default":50}},"additionalProperties":false}]},"nationwide":{"type":"boolean","default":false},"viewport":{"$ref":"#/components/schemas/GeoViewport"},"map_clusters":{"type":"boolean","default":false},"map_zoom":{"type":"integer","minimum":0,"maximum":22},"filters":{"$ref":"#/components/schemas/SearchFilters"},"sort":{"type":"object","properties":{"by":{"$ref":"#/components/schemas/SortBy"},"direction":{"type":"string","enum":["asc","desc"]}},"additionalProperties":false},"cursor":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20},"facets":{"type":"array","maxItems":8,"items":{"type":"string","enum":["vehicle_type","make","model","trim","condition","body","fuel","year"]}}},"additionalProperties":false},"SearchResponse":{"type":"object","required":["items","facets","total","next_cursor","interpreted_query","applied_filters","suggested_relaxations","coverage","freshness","request_id","index_timestamp"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VehicleListingSummary"}},"facets":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/FacetBucket"}}},"map":{"$ref":"#/components/schemas/MapClusterResult"},"total":{"type":"object","required":["value","relation"],"properties":{"value":{"type":"integer"},"relation":{"type":"string","enum":["eq","gte"]}}},"next_cursor":{"type":["string","null"]},"interpreted_query":{"type":"object","required":["original","assumptions","location"],"properties":{"original":{"type":["string","null"]},"assumptions":{"type":"array","items":{"type":"string"}},"location":{"oneOf":[{"type":"object","required":["label","confidence"],"properties":{"label":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"applied_filters":{"$ref":"#/components/schemas/SearchFilters"},"suggested_relaxations":{"type":"array","items":{"type":"object","required":["action","field","suggestion"],"properties":{"action":{"type":"string","enum":["expand_radius","remove_filter","search_nationwide"]},"field":{"type":"string"},"suggestion":{"type":"string"}},"additionalProperties":false}},"coverage":{"type":"object","required":["country","mode","radius_miles"],"properties":{"country":{"const":"US"},"mode":{"type":"string","enum":["radius","viewport","nationwide"]},"radius_miles":{"type":["number","null"],"minimum":1,"maximum":500}},"additionalProperties":false},"freshness":{"type":"object","required":["catalog_snapshot_at","newest_listing_updated_at"],"properties":{"catalog_snapshot_at":{"type":"string","format":"date-time"},"newest_listing_updated_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"request_id":{"type":"string"},"index_timestamp":{"type":"string","format":"date-time"}},"additionalProperties":false},"Customer":{"type":"object","required":["first_name","last_name"],"anyOf":[{"required":["email"]},{"required":["phone"]}],"properties":{"first_name":{"type":"string","minLength":1,"maxLength":100},"last_name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","maxLength":254},"phone":{"type":"string","maxLength":32},"preferred_contact":{"type":"string","enum":["email","phone","sms","any"],"default":"email"}},"additionalProperties":false},"Consent":{"type":"object","required":["accepted"],"properties":{"accepted":{"const":true},"allowed_channels":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["email","phone","sms"]},"description":"Exact dealership-contact grants. Omission is a deprecated email-only compatibility path; phone and SMS are never inferred."},"disclosure_version":{"const":"carhandshake-dealer-contact-2026-07-13-v1","description":"Required with explicit allowed_channels. The server-owned disclosure is: By submitting this request, you authorize Car Handshake to share it with the selected dealership and authorize that dealership to contact you only through the communication channels you selected. Consent is not a condition of purchase. Message and data rates may apply to SMS."},"text":{"type":"string","maxLength":2000,"deprecated":true,"description":"Deprecated display copy. Car Handshake records its own versioned disclosure as consent evidence."}},"additionalProperties":false},"LeadRequestBase":{"type":"object","required":["listing_id","customer","consent"],"properties":{"listing_id":{"type":"string","format":"uuid"},"customer":{"$ref":"#/components/schemas/Customer"},"consent":{"$ref":"#/components/schemas/Consent"},"message":{"type":"string","maxLength":4000}}},"VehicleInquiry":{"allOf":[{"$ref":"#/components/schemas/LeadRequestBase"}],"unevaluatedProperties":false},"TestDriveRequest":{"allOf":[{"$ref":"#/components/schemas/LeadRequestBase"},{"type":"object","required":["requested_at"],"properties":{"requested_at":{"type":"string","format":"date-time"},"duration_minutes":{"type":"integer","minimum":15,"maximum":240,"default":30}}}],"unevaluatedProperties":false},"TradeInAppraisal":{"allOf":[{"$ref":"#/components/schemas/LeadRequestBase"},{"type":"object","required":["trade_in"],"properties":{"trade_in":{"type":"object","required":["year","make","model","mileage","condition"],"properties":{"vin":{"type":"string","minLength":11,"maxLength":17},"year":{"type":"integer","minimum":1886,"maximum":2200},"make":{"type":"string","minLength":1,"maxLength":100},"model":{"type":"string","minLength":1,"maxLength":100},"trim":{"type":"string","maxLength":100},"mileage":{"type":"integer","minimum":0,"maximum":2000000},"condition":{"type":"string","enum":["excellent","good","fair","poor"]}},"additionalProperties":false}}}],"unevaluatedProperties":false},"LeadAcknowledgement":{"type":"object","required":["lead_id","status","dealer","message"],"properties":{"lead_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["received","duplicate"]},"dealer":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"additionalProperties":false},"message":{"type":"string"}},"additionalProperties":false},"OpenApiDocument":{"type":"object","required":["openapi","info","servers","security","tags","paths","components"],"properties":{"openapi":{"const":"3.1.0"},"info":{"type":"object","required":["title","version","description","contact"],"properties":{"title":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"contact":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}},"additionalProperties":false}},"additionalProperties":false},"servers":{"type":"array","minItems":1,"items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}},"additionalProperties":false}},"security":{"type":"array","maxItems":0,"description":"The v1 inventory and consented-lead surface is anonymous."},"tags":{"type":"array","items":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false}},"paths":{"type":"object","minProperties":1,"additionalProperties":{"type":"object"}},"components":{"type":"object","required":["parameters","responses","schemas"],"properties":{"parameters":{"type":"object","additionalProperties":{"type":"object"}},"responses":{"type":"object","additionalProperties":{"type":"object"}},"schemas":{"type":"object","additionalProperties":{"type":"object"}}},"additionalProperties":false}},"additionalProperties":false},"Problem":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"request_id":{"type":"string"}}}}}}