> ## Documentation Index > Fetch the complete documentation index at: https://docs.autosnap.com/llms.txt > Use this file to discover all available pages before exploring further. # Resolve Dealership > Look up a dealership by URL, name and address, or VIN. `POST /v1/dealers/resolve` **v1.0 schema lock.** The response shape on this page is the locked v1.0 contract. We will never remove a documented field, never rename a field, and never change a field's type without bumping to v2 (see [Versioning](/get-started/versioning)). New fields may be added additively; your client must tolerate unknown keys. Look up a dealership by website URL, business name and address, or VIN. Returns dealer info, whether it's supported, and whether setup is required. You must provide one of: * `dealership_url` alone * `dealership_url` + `vin` (URL first, VIN fallback) * `dealer_name` + `vin` * `vin` alone * `dealer_name` + `dealer_address` ## Request Body | Field | Type | Required | Description | | ---------------- | ------ | -------- | --------------------------------------------------------------------- | | `api_key` | string | Yes | Your API key | | `dealership_url` | string | No | Dealership website URL (e.g. `https://www.carlblackroswell.com`) | | `dealer_name` | string | No | Business name of the dealership | | `vin` | string | No | 17-character VIN. Used to look up the selling dealer via MarketCheck. | | `dealer_address` | object | No | Address object with `street`, `city`, `state`, and/or `zip` fields | ## Resolution Methods | Input Combination | Method | How It Works | | --------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `dealership_url` only | `url` | Direct DB lookup. Returns immediately if found. | | `dealership_url` only (not in DB) | `url_serp_confirmed` or `url_serp_fallback` | Runs a web search. `url_serp_confirmed` if the search confirms the same URL; `url_serp_fallback` if it finds a different/corrected URL. | | `dealership_url` + `vin` | `url`, `url_serp_confirmed`, `url_serp_fallback`, or `url_vin_fallback` | Tries URL first (direct then SERP). If URL resolution fails entirely, falls back to VIN resolution. | | `vin` + `dealer_name` | `vin` | Looks up the VIN in active listings, finds the selling dealer, scores the name match. | | `vin` alone | `vin` | Same as above but uses the listing dealer name directly (name\_match\_confidence = 1.0). | | `vin` (dealer group detected) | `vin_group_match` | VIN found a dealer group. AI picks the specific dealership from the group. | | `dealer_name` + `dealer_address` | `address` | Runs a web search for the dealer, then uses AI to extract the correct website. Detects dealer groups and returns candidates if the name is ambiguous. | ## Example — URL ```bash theme={null} curl -X POST "https://api.autosnap.com/v1/dealers/resolve" \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY", "dealership_url": "https://www.carlblackroswell.com" }' ``` ## Example — VIN + Dealer Name ```bash theme={null} curl -X POST "https://api.autosnap.com/v1/dealers/resolve" \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY", "dealer_name": "Auto Solutions", "vin": "3TMLB5JN5SM127129" }' ``` ## Response ```json theme={null} { "success": true, "website_url": "carlblackroswell.com", "dealership": { "name": "Carl Black Buick Gmc", "website": "carlblackroswell.com", "street": "11225 Alpharetta Highway", "city": "Roswell", "state": "Georgia", "phone": "678-317-2740" }, "supported": true, "setup_required": false, "resolution": { "method": "url", "confidence": 1.0 } } ``` ### Additional Response Fields (VIN and Address Resolution Only) These fields appear only when resolving by VIN, name + address, or SERP fallback — not in direct URL lookups: | Field | Type | Description | | ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `resolution.reasoning` | string \| null | Human-readable explanation of how the dealer was resolved | | `resolution.matched_name` | string \| null | The dealer name that was matched | | `resolution.name_match_confidence` | float \| null | Confidence score for the name match, from 0 to 1 | | `resolution.resolution_source` | string \| null | Source of the resolution. Values: `"vin_match"`, `"vin_lookup"`, `"vin_fallback"`, `"vin_group_match"`, `"name_match"`, `"automated"` | ## Error Responses ### LOW\_CONFIDENCE\_MATCH Returned when the resolution finds candidates but confidence is below the threshold: ```json theme={null} { "success": false, "error": { "code": "LOW_CONFIDENCE_MATCH", "message": "Multiple potential matches found. Review candidates and retry with dealership_url.", "candidates": [ { "name": "Auto Solutions LLC", "website": "autosolutionsllc.com" } ], "reasoning": "VIN found in inventory but dealer name match confidence was 0.35" } } ``` ## Dealer Group Detection When resolving by name + address, if the name matches a dealer group with multiple brands (e.g. "Friendship" in Bristol, TN), the endpoint returns a `DEALER_GROUP_DETECTED` error with a list of candidates. Include the brand in the name (e.g. "Friendship Ford") to resolve to a specific dealership. ```json theme={null} { "success": false, "error": { "code": "DEALER_GROUP_DETECTED", "message": "Multiple dealerships detected under this dealer group. Specify a brand or use dealership_url.", "candidates": [ { "name": "Friendship Ford", "website": "friendshipford.com" }, { "name": "Friendship Chrysler Jeep Dodge Ram", "website": "friendshipchryslerjeepdodge.com" } ], "reasoning": "The name 'Friendship' matches a dealer group with multiple brands in Bristol, TN" } } ``` ## OpenAPI ````yaml POST /v1/dealers/resolve openapi: 3.0.3 info: title: AutosnapAI Origin API description: Dealer resolution, inventory management, and webhook APIs version: 1.0.0 servers: - url: https://api.autosnap.com description: Production security: [] paths: /v1/dealers/resolve: post: tags: - origin summary: Resolve Dealer description: |- Resolve a dealership identity. Supports 4 input modes: - dealership_url only - dealership_url + vin (URL first, VIN fallback) - dealer_name + vin - dealer_name + dealer_address operationId: resolve_dealer_v1_dealers_resolve_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ResolveRequest' required: true responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: ResolveRequest: properties: api_key: type: string title: Api Key dealership_url: type: string nullable: true title: Dealership Url dealer_name: type: string nullable: true title: Dealer Name vin: type: string nullable: true title: Vin dealer_address: additionalProperties: true type: object nullable: true title: Dealer Address type: object required: - api_key title: ResolveRequest HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````