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

# IMS Feed Imports

> Ingest inventory data from IMS providers like vAuto, HomeNet, and VinCue via automated CSV feed processing.

## Overview

IMS (Inventory Management System) providers push CSV inventory files to AutoSnap's SFTP server. The IMS feed system automatically:

1. Polls for new/changed files every 60 seconds
2. Parses CSVs using provider-specific field mappings
3. Normalizes data into a unified vehicle schema
4. Tracks additions, updates, and removals between imports
5. Fires webhooks on updates and staleness

## Supported Providers

| Provider        | Description            |
| --------------- | ---------------------- |
| `vauto`         | vAuto                  |
| `homenet`       | HomeNet                |
| `vincue`        | VinCue                 |
| `promax`        | ProMax                 |
| `maxdigital`    | MaxDigital / Firstlook |
| `inventoryplus` | InventoryPlus          |
| `dealercenter`  | DealerCenter           |
| `idms`          | IDMS                   |
| `ansira`        | Ansira                 |

## How It Works

### 1. Provider pushes CSV to SFTP

Each provider pushes a CSV file to `files.autosnap.cloud` under `/import/{provider}/`. For example, vAuto files land in `/import/vauto/MP14015.csv`. Providers overwrite the same filename on each push.

### 2. Create a feed config

```bash theme={null}
curl -X POST "https://api.autosnap.com/v1/ims/feeds" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "dealership_id": "dlr_8cfc0b00a98b",
    "provider": "vauto",
    "ftp_path": "vauto",
    "file_name": "MP14015.csv",
    "staleness_threshold_hours": 48
  }'
```

The endpoint validates that the file exists and was updated within 48 hours before creating the config.

<Warning>
  The `provider` and `ftp_path` fields may differ. `provider` determines which field mapping is used to parse the CSV. `ftp_path` is the actual directory name on SFTP. For example, MaxDigital uses `provider: "maxdigital"` but `ftp_path: "firstlook"`.
</Warning>

### 3. Automatic polling

Once created, the system polls SFTP every 60 seconds. On each poll:

* Checks file mtime (modification time) -- skips download if unchanged
* Downloads and computes MD5 hash -- skips import if hash matches last import
* Parses CSV with the provider's field mapping
* Upserts vehicles into `ims_vehicle` (keyed on feed + VIN)
* Marks vehicles as removed if they were in the previous import but not in the current file
* Fires `ims.import.complete` webhook with import stats
* Fires per-vehicle webhooks (`ims.vehicle.created`, `ims.vehicle.updated`, `ims.vehicle.removed`)

### 4. Staleness detection

A separate check runs every 30 minutes. If a feed's file hasn't been updated within the `staleness_threshold_hours` (default 48), an `ims.feed.stale` webhook fires. Stale alerts are throttled to once per 24 hours per feed.

## Multi-Dealer Files

Some providers (like ProMax) send all dealers in a single CSV file. Use the `dealer_identifier` field to filter rows:

```bash theme={null}
curl -X POST "https://api.autosnap.com/v1/ims/feeds" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "dealership_id": "dlr_abc123",
    "provider": "promax",
    "ftp_path": "promax",
    "file_name": "Preownedplus.csv",
    "dealer_identifier": "9553"
  }'
```

The `dealer_identifier` is matched against the dealer ID column in the CSV (e.g., `ProMaxID` for ProMax, `DealerId` for vAuto).

## Webhook Events

Subscribe to IMS webhook events to get real-time notifications. See [Webhooks](/concepts/webhooks) for setup instructions.

| Event                 | Fires when                                                     |
| --------------------- | -------------------------------------------------------------- |
| `ims.import.complete` | An import cycle finishes for a feed                            |
| `ims.vehicle.created` | A new vehicle appears in a feed import                         |
| `ims.vehicle.updated` | An existing vehicle's data changes                             |
| `ims.vehicle.removed` | A vehicle is no longer in the feed (marked inactive)           |
| `ims.feed.stale`      | A feed file hasn't been updated within the staleness threshold |

<Note>
  The `ims.*` prefixed events are specific to IMS feed imports. The non-prefixed equivalents (`import.complete`, `vehicle.created`, `vehicle.updated`, `vehicle.removed`) cover website scraper events only. If a dealership has both a website scraper and an IMS feed, subscribe to both sets to receive events from both sources.
</Note>

### `ims.import.complete`

Fired after each successful import cycle. Includes counts for new, updated, and removed vehicles.

```json theme={null}
{
  "event": "ims.import.complete",
  "dealership_id": "dlr_8cfc0b00a98b",
  "timestamp": "2026-04-14T06:15:12+00:00",
  "data": {
    "feed_config_id": 1,
    "dealership_id": "dlr_8cfc0b00a98b",
    "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "file_name": "MP14015.csv",
    "vehicle_count": 381,
    "new_count": 3,
    "updated_count": 378,
    "removed_count": 2,
    "error_count": 0,
    "status": "success"
  }
}
```

### `ims.vehicle.created`

Fired for each new vehicle added during an import.

```json theme={null}
{
  "event": "ims.vehicle.created",
  "dealership_id": "dlr_8cfc0b00a98b",
  "timestamp": "2026-04-14T06:15:12+00:00",
  "data": {
    "vin": "1GCHSCEA7L1214921",
    "feed_config_id": 1,
    "dealership_id": "dlr_8cfc0b00a98b",
    "year": 2020,
    "make": "Chevrolet",
    "model": "Colorado 2WD",
    "condition": "Used",
    "price": 18999,
    "stock_number": "M1382"
  }
}
```

### `ims.vehicle.updated`

Same payload structure as `ims.vehicle.created`. Fired when an existing vehicle's data changes between imports.

### `ims.vehicle.removed`

Fired when a vehicle was in the previous import but is no longer in the current file.

```json theme={null}
{
  "event": "ims.vehicle.removed",
  "dealership_id": "dlr_8cfc0b00a98b",
  "timestamp": "2026-04-14T06:15:12+00:00",
  "data": {
    "vin": "1GCHSCEA7L1214921",
    "feed_config_id": 1,
    "dealership_id": "dlr_8cfc0b00a98b"
  }
}
```

### `ims.feed.stale`

Fired when a feed file hasn't been updated within the configured threshold.

```json theme={null}
{
  "event": "ims.feed.stale",
  "dealership_id": "dlr_8cfc0b00a98b",
  "timestamp": "2026-04-16T12:00:00+00:00",
  "data": {
    "feed_config_id": 1,
    "dealership_id": "dlr_8cfc0b00a98b",
    "provider": "vauto",
    "staleness_threshold_hours": 48,
    "hours_since_last_import": 53.2,
    "last_import_at": "2026-04-14T06:15:12+00:00"
  }
}
```

## API Reference

| Endpoint                     | Method  | Description                                                              |
| ---------------------------- | ------- | ------------------------------------------------------------------------ |
| `/v1/ims/feeds`              | `POST`  | [Create Feed Configuration](/api-reference/endpoints/create-ims-feed)    |
| `/v1/ims/feeds`              | `GET`   | [List Feed Configurations](/api-reference/endpoints/list-ims-feeds)      |
| `/v1/ims/feeds/{id}`         | `PATCH` | [Update Feed Configuration](/api-reference/endpoints/update-ims-feed)    |
| `/v1/ims/feeds/{id}/history` | `GET`   | [Get Feed Import History](/api-reference/endpoints/get-ims-feed-history) |
| `/v1/ims/vehicles`           | `GET`   | [Fetch IMS Inventory](/api-reference/endpoints/list-ims-vehicles)        |