> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vehicle & Driver Filtering

## Overview

Terminal allows you to filter vehicle and driver data by status (active/inactive) and by specific Terminal IDs. These filters enable you to limit the data pulled from provider systems to only what is relevant to you.

## Common Use Cases

* **Reducing Data Volume and Costs**: Limit ingestion to only active vehicles/drivers. This is especially valuable for fleets with many inactive vehicles.
* **Multi-Fleet TSP Accounts**: For fleets that share TSP (Telematics Service Provider) accounts with other fleets, you can selectively ingest only vehicles/drivers which are part of the relevant fleet.
* **Precise Control**: Use `includeIds` to specify exactly which vehicles/drivers should be ingested, regardless of their status.

## Filter Structure

You can set filters on a given connection using a JSON structure that specifies filter criteria.

**Available Filter Options:**

* `status`: Filter by vehicle/driver status (e.g. `active` to include only active vehicles/drivers)
* `excludeIds`: Array of Terminal Vehicle/Driver IDs to exclude from data ingestion
* `includeIds`: Array of Terminal Vehicle/Driver IDs to include in data ingestion (takes priority over other filters)

```json theme={null}
{
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": ["vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"],
      "includeIds": ["vcl_01D8ZQFGHVJ858NBF2Q7DV9MND"]
    },
    "drivers": {
      "status": "active",
      "excludeIds": ["drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"],
      "includeIds": ["drv_01D8ZQFGHVJ858NBF2Q7DV9MND"]
    }
  }
}
```

## Filter Priority Rules

The filtering system follows a specific priority order:

1. **`includeIds` takes highest priority**: If `includeIds` is present and non-empty, all other filter criteria (`status` and `excludeIds`) are ignored, and only the specified IDs are ingested.

2. **Standard filtering**: If `includeIds` is absent or empty, the system applies:
   * First: `status` filtering (if specified)
   * Then: Remove any IDs listed in `excludeIds`

### Examples

**Include-only filtering (highest priority):**

```json theme={null}
{
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": ["vcl_123"],
      "includeIds": ["vcl_456", "vcl_789"]
    }
  }
}
```

In this case, only vehicles `vcl_456` and `vcl_789` will be ingested, regardless of their status or the exclude list.

**Standard filtering:**

```json theme={null}
{
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": ["vcl_123"]
    }
  }
}
```

In this case, all active vehicles will be ingested except for `vcl_123`.

## Applying Filters

### For Existing Connections via API

You can add or update filters on existing connections using the [`PATCH /connections/current`](https://docs.withterminal.com/api-reference/connections/update-current-connection) endpoint. Include the `filters` object in your request body with the desired configuration.

To view the current filters applied to a connection, use the [`GET /connections/current`](https://docs.withterminal.com/api-reference/connections/get-current-connection) endpoint.

### For Existing Connections via Terminal Dashboard

1. Navigate to the [Connections](https://dashboard.withterminal.com/) page in the Terminal Dashboard.

<Frame>
  <img src="https://mintcdn.com/terminal-docs/apkZfhNH8UPMk4Rj/images/filtering/manage-connections.png?fit=max&auto=format&n=apkZfhNH8UPMk4Rj&q=85&s=3cd9ceeab4693573ef66a5ddd141fa58" width="1304" height="824" data-path="images/filtering/manage-connections.png" />
</Frame>

2. Click on the desired connection to open the connection details page.

<Frame>
  <img src="https://mintcdn.com/terminal-docs/apkZfhNH8UPMk4Rj/images/filtering/select-connection.png?fit=max&auto=format&n=apkZfhNH8UPMk4Rj&q=85&s=269f54f835615d34fa0c5d5a6087e4d6" width="1324" height="580" data-path="images/filtering/select-connection.png" />
</Frame>

3. Click `Visibility` above the Vehicle or Driver table.

<Frame>
  <img src="https://mintcdn.com/terminal-docs/apkZfhNH8UPMk4Rj/images/filtering/visibility.png?fit=max&auto=format&n=apkZfhNH8UPMk4Rj&q=85&s=cb4ecdbce15d5d2c9fa930f9270aeb9e" width="1246" height="845" data-path="images/filtering/visibility.png" />
</Frame>

4. Click `Manage Vehicle/Driver Filtering`.

<Frame>
  <img src="https://mintcdn.com/terminal-docs/n0GwCNXL7J4hJe2a/images/filtering/manage-filtering.png?fit=max&auto=format&n=n0GwCNXL7J4hJe2a&q=85&s=8d678312580a125e977f074131e7fdc8" width="1742" height="842" data-path="images/filtering/manage-filtering.png" />
</Frame>

5. Configure filtering to include/exclude specific vehicles or drivers.

<Frame caption="Exclude vehicles / drivers explicitly">
  <img src="https://mintcdn.com/terminal-docs/apkZfhNH8UPMk4Rj/images/filtering/dashboard-exclude.png?fit=max&auto=format&n=apkZfhNH8UPMk4Rj&q=85&s=6b7b246a4f9d81c308eb08fb4307c8b0" width="2196" height="876" data-path="images/filtering/dashboard-exclude.png" />
</Frame>

<Frame caption="Include vehicle / drivers explicity">
  <img src="https://mintcdn.com/terminal-docs/apkZfhNH8UPMk4Rj/images/filtering/dashboard-include.png?fit=max&auto=format&n=apkZfhNH8UPMk4Rj&q=85&s=6c1062c9b519f19b753b8f91ab3321bb" width="2190" height="862" data-path="images/filtering/dashboard-include.png" />
</Frame>

6. Click `Save Changes`.

You can also view the vehicles or drivers that are currently filtered by enabling the `Visibility` column in the Vehicle or Driver table via the `View` button above the table.

### For New Connections

1. **Initial Setup**: When creating a new connection with filtering, Terminal first needs to perform an initial sync to identify all vehicles and drivers. To prevent ingesting unnecessary data before applying filters: - Set sync mode to `manual` - Set `backfill` days to `0`

   <Note>
     Configure these sync settings through the \[\`Link

     Component\`]\([https://docs.withterminal.com/link-component](https://docs.withterminal.com/link-component)) or in the

     Terminal Dashboard under `Add Connections`->`Advanced Options`.
   </Note>

2. **Complete Initial Discovery**: Allow the first sync to complete. This identifies all vehicles and drivers without pulling their historical data.

3. **Apply Your Filters**: After the initial sync, use the `PATCH /connections/current` endpoint to set relevant vehicle and driver filters.

4. **Historical Data (Optional)**: If you need historical data, request a backfill after applying filters. This ensures you only retrieve historical data for filtered vehicles and drivers.

5. **Enable Automatic Syncing**: For ongoing data collection, change the sync mode to `automatic`. This keeps your data current while respecting your filters.

This approach ensures you only ingest data for vehicles and drivers that match your filter criteria, both for historical and future data collection.