> ## 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.
# Setup Dealership
> Onboard a new dealership for inventory data collection.
`POST /v1/dealers/setup`
**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. This endpoint has two distinct success-response variants: async job creation (HTTP 202 — the standard flow) and reactivation (HTTP 200 — when an inactive subscription exists for the URL).
Onboard a new dealership. Detects the website provider, generates the configuration, creates the subscription, and triggers the first inventory import.
If the dealership was previously deleted (subscription deactivated), calling setup again will reactivate the existing subscription instead of creating a duplicate.
## How It Works
1. **POST** this endpoint. You get back HTTP 202 with a `setup_id` in well under a second.
2. The setup job (provider detection, AI config validation, subscription creation) runs in the background — typically 60 seconds, up to \~10 minutes for heavily bot-protected sites.
3. **Poll** `GET /v1/dealers/setup/{setup_id}` until `status` is `"completed"` or `"failed"`. Recommended polling interval: **5 seconds**.
4. Or skip polling: subscribe to the `setup.complete` webhook before calling setup.
## Request Body
| Field | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api_key` | string | Yes | — | Your API key. Accepted in body (canonical) or `?api_key=…` query string. |
| `dealership_url` | string | Yes | — | The dealership's website URL (e.g. `https://www.baydodge.net`) |
| `dealer_name` | string | No | — | Override the detected dealer name |
| `city` | string | No | — | Dealer city (used if auto-detection can't determine location) |
| `state` | string | No | — | Dealer state |
| `street_address` | string | No | — | Dealer street address |
| `phone_number` | string | No | — | Dealer phone number |
| `condition_filter` | string | No | `null` | Filter inventory by condition. Values: `"new"`, `"used"`, or `null` (all conditions). When set, only vehicles matching this condition are included in imports for this subscription. |
| `async_mode` | boolean | No | — | **Deprecated, ignored.** Setup is always asynchronous. The field is tolerated for backward compatibility. |
## Example
```bash theme={null}
curl -X POST "https://api.autosnap.com/v1/dealers/setup" \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"dealership_url": "https://www.baydodge.net"
}'
```
### Response — HTTP 202 Accepted
```json theme={null}
{
"success": true,
"setup_id": "setup_6420ad759b71",
"status": "pending",
"message": "Setup job created. Poll GET /v1/dealers/setup/{setup_id} for status, or wait for the setup.complete webhook.",
"poll_url": "/v1/dealers/setup/setup_6420ad759b71"
}
```
Poll for completion (every 5 seconds):
```bash theme={null}
curl "https://api.autosnap.com/v1/dealers/setup/setup_6420ad759b71?api_key=YOUR_API_KEY"
```
See [Get Setup Status](/api-reference/endpoints/get-setup-status) for the full response shape of every status value (`pending`, `running`, `completed`, `failed`). When `status` is `"completed"`, the poll response carries the detected `provider`, `provider_confidence`, `config`, `vehicle_counts`, and the new `dealership_id` / `configuration_id` / `subscription_id`.
`setup_status` on the completed poll response is `"active"` when detection and validation both pass. If detection succeeds but the test scrape has issues (e.g. missing critical fields), the status is `"needs_manual_review"` — imports are still created but may need attention, and the poll response includes a human-readable `requires_review_reason`.
`status: "completed"` means detection and configuration are done — NOT that inventory is available. Poll until `inventory_status: "available"`, or subscribe to the `import.complete` webhook. See [Get Setup Status](/api-reference/endpoints/get-setup-status) for details.
Inventory is automatically refreshed every 12 hours. This is the default schedule for all new dealerships and is not configurable via the API.
## Reactivation
If you previously deleted a dealership and call setup again with the same URL, the existing subscription is reactivated. This completes inline (no detection runs) and returns **HTTP 200**:
```json theme={null}
{
"success": true,
"reactivated": true,
"subscription_id": 221,
"configuration_id": 9,
"website_url": "baydodge.net",
"message": "Dealership subscription reactivated"
}
```
## Errors
| Status | Description |
| ------ | ----------------------------------------------------------------------- |
| 409 | Dealership is already actively subscribed under your account |
| 422 | Request body failed validation (e.g. missing `dealership_url`) |
| 503 | Setup queue unavailable — the job could not be enqueued. Safe to retry. |
Detection failures (e.g. the website provider could not be identified) no longer surface as POST errors — the POST succeeds with 202, and the failure is reported on the poll response as `status: "failed"` with an `error` message and, when available, a `failure_mode` classification.
## OpenAPI
````yaml POST /v1/dealers/setup
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/setup:
post:
tags:
- origin
summary: Setup Dealer
description: |-
Detect provider, generate config, subscribe client, start billing.
If async_mode=true, returns immediately with a setup_id. The setup
runs in the background and fires a webhook on completion. Poll
GET /v1/dealers/setup/{setup_id} for status.
If async_mode=false (default), blocks until setup completes and
returns the full result inline. This is what the admin UI uses.
operationId: setup_dealer_v1_dealers_setup_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetupRequest'
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:
SetupRequest:
properties:
api_key:
type: string
title: Api Key
dealership_url:
type: string
title: Dealership Url
dealer_name:
type: string
nullable: true
title: Dealer Name
city:
type: string
nullable: true
title: City
state:
type: string
nullable: true
title: State
street_address:
type: string
nullable: true
title: Street Address
phone_number:
type: string
nullable: true
title: Phone Number
async_mode:
type: boolean
nullable: true
title: Async Mode
default: false
type: object
required:
- api_key
- dealership_url
title: SetupRequest
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
````