> ## 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.

# Dealerships

> The dealership object and how to resolve dealers

A **dealership** represents a single physical automotive dealer — one name, one address, one inventory of vehicles. Every [vehicle](/concepts/vehicles) belongs to exactly one dealership, identified by its `dealership_id` (a public ID in the format `dlr_xxxxxxxxxxxx`).

## Object shape

The dealership object varies slightly depending on the endpoint. The resolve endpoint returns the core identity fields:

```json Resolve response theme={null}
{
  "name": "Carl Black Buick Gmc",
  "website": "carlblackroswell.com",
  "street": "11225 Alpharetta Highway",
  "city": "Roswell",
  "state": "Georgia",
  "phone": "678-317-2740"
}
```

The list-dealers and get-dealer endpoints return additional fields including `dealership_id`:

```json List dealers response theme={null}
{
  "dealership_id": "dlr_8cfc0b00a98b",
  "name": "Carl Black Buick Gmc",
  "website": "carlblackroswell.com",
  "street_address": "11225 Alpharetta Highway",
  "city": "Roswell",
  "state": "Georgia",
  "phone": "678-317-2740",
  "provider": "CarsCommerce",
  "inventory_type": "all",
  "schedule": "0 */12 * * *",
  "vehicle_count": 872,
  "last_import": "2026-04-13T13:07:06.763767+00:00",
  "last_scraped": null,
  "active": true
}
```

## Core fields

| Field            | Type        | Present on               | Description                                                                         |
| ---------------- | ----------- | ------------------------ | ----------------------------------------------------------------------------------- |
| `dealership_id`  | `string`    | list-dealers, get-dealer | Public dealership ID (`dlr_xxxx`). Use this on vehicle lookups and other endpoints. |
| `name`           | `string`    | all                      | Dealer name as published                                                            |
| `website`        | `string`    | all                      | Canonical dealer website domain                                                     |
| `street`         | `string`    | resolve                  | Street address (resolve endpoint)                                                   |
| `street_address` | `string`    | list-dealers, get-dealer | Street address (list/get endpoints)                                                 |
| `city`, `state`  | `string`    | all                      | Physical location                                                                   |
| `phone`          | `string`    | all                      | Primary contact number                                                              |
| `provider`       | `string`    | list-dealers, get-dealer | Website provider (e.g. "CarsCommerce", "DealerInspire")                             |
| `vehicle_count`  | `integer`   | list-dealers, get-dealer | Count of active vehicles in inventory                                               |
| `last_import`    | `timestamp` | list-dealers, get-dealer | Most recent successful inventory refresh                                            |
| `last_scraped`   | `timestamp` | list-dealers, get-dealer | Most recent scrape attempt                                                          |
| `active`         | `boolean`   | list-dealers, get-dealer | `false` if the dealership has been deactivated                                      |

<Note>
  The resolve endpoint uses `street` while the list-dealers and get-dealer endpoints use `street_address`. This is an intentional difference — resolve returns a lightweight identity object, while the management endpoints return the full dealership record.
</Note>

## Resolving a dealership

You rarely know a `dealership_id` up front. Use `POST /v1/dealers/resolve` to find it from what you do know. The endpoint supports 5 input modes:

### By URL

The simplest path. If the URL is in our system, returns immediately with `supported: true`.

```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"
  }'
```

If the URL is **not** in our system, the resolver searches the web to find the correct dealer website. This handles stale or incorrect URLs — for example, `carlblackbuickgmc.com` resolves to `carlblackroswell.com`.

### By VIN only

When you have a vehicle VIN but nothing else. The resolver looks up the VIN in active inventory databases to find which dealer currently has it.

```bash theme={null}
curl -X POST "https://api.autosnap.com/v1/dealers/resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "vin": "3TMLB5JN5SM127129"
  }'
```

### By VIN + dealer name

More precise than VIN alone. The dealer name is scored against inventory database results to pick the best match.

```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": "Carl Black Buick GMC",
    "vin": "1GKS2DKL8TR322035"
  }'
```

### By dealer name + address

When you know the dealer's name and location but not their website.

```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": "Carl Black Buick GMC",
    "dealer_address": {
      "city": "Roswell",
      "state": "Georgia"
    }
  }'
```

The `dealer_address` object accepts `street`, `city`, `state`, and `zip` — all optional, but include as many as you have for better accuracy.

### By URL + VIN

Combines both: tries the URL first, falls back to VIN if the URL isn't in our system.

```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.carlblackbuickgmc.com",
    "vin": "1GKS2DKL8TR322035"
  }'
```

## Response

A successful resolution returns:

```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
  }
}
```

| Field                   | Description                                                                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `supported`             | `true` if the dealer is already in our system and has active inventory                                                                 |
| `setup_required`        | `true` if the dealer was found but needs onboarding via `POST /v1/dealers/setup`                                                       |
| `resolution.method`     | How the dealer was resolved: `url`, `url_serp_confirmed`, `url_serp_fallback`, `url_vin_fallback`, `vin`, `vin_group_match`, `address` |
| `resolution.confidence` | 0-1 confidence score. 1.0 for exact URL matches, 0.7-0.95 for VIN/address/SERP matches                                                 |

<Note>
  For non-URL resolution methods (VIN, address), the `resolution` object may include additional fields like `matched_name` and `reasoning` when available. These are not present for direct URL matches.
</Note>

## Dealer groups

Some organizations operate multiple dealerships under the same name (e.g. "Friendship Ford", "Friendship Chrysler", "Friendship Hyundai"). The resolver detects this automatically.

**If the input name has no brand** (just "Friendship"), the resolver returns a `DEALER_GROUP_DETECTED` response with all group members:

```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 of Bristol", "website": "https://www.friendshipford.com/", "city": "Bristol", "state": "TN"},
      {"name": "Friendship Hyundai of Bristol", "website": "https://www.hyundaitn.com/", "city": "Bristol", "state": "TN"},
      {"name": "Friendship Chrysler Jeep Dodge RAM", "website": "https://www.friendshipchryslerjeepdodge.com/", "city": "Bristol", "state": "TN"}
    ]
  }
}
```

**If the input name includes a brand** (e.g. "Friendship Ford"), the resolver picks that specific dealership and returns a single result.

## Fetching inventory

Once you have a dealer in the system (`supported: true`), pull their inventory:

```bash theme={null}
curl -X POST "https://api.autosnap.com/v1/inventory/fetch" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "dealership_url": "carlblackroswell.com",
    "page": 1,
    "per_page": 50,
    "condition": "new"
  }'
```

See [the inventory fetch endpoint](/api-reference/endpoints/fetch-inventory) for full details.

## Related

<CardGroup cols={2}>
  <Card title="Vehicles" icon="car" href="/concepts/vehicles">
    The vehicle object that belongs to a dealership
  </Card>

  <Card title="Pricing Breakdown" icon="receipt" href="/concepts/pricing-breakdown">
    Structured pricing with itemized discounts, fees, and final price
  </Card>
</CardGroup>