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

# Entity Status & Visibility

This guide explains two important fields found on all Terminal entities: `status` and `metadata.visibility`. Understanding the difference is essential for correctly interpreting data and configuring [filtering](/guides/filtering).

## What is an Entity?

In Terminal, an **entity** is a core data model that represents a real-world object tracked by telematics providers. The three main entities are:

| Entity                     | Description                                    | ID Prefix |
| -------------------------- | ---------------------------------------------- | --------- |
| [Vehicle](/models/vehicle) | Trucks, vans, cars, and other motorized assets | `vcl_`    |
| [Driver](/models/driver)   | Individuals who operate vehicles               | `drv_`    |
| [Trailer](/models/trailer) | Non-motorized assets that attach to vehicles   | `trl_`    |

All entities share the same `status` and `metadata.visibility` fields described below.

## Entity Status

The `status` field reflects whether an entity is currently active in the fleet's telematics provider account.

| Value      | Description                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `active`   | The entity is currently operational and tracked in the provider's system                          |
| `inactive` | The entity has been offboarded, archived, deactivated, or soft-deleted from the provider's system |

### How Status is Determined

The `status` value comes directly from provider data during sync. Terminal normalizes each provider's representation into the standard `active`/`inactive` enum.

**Vehicle status examples:**

| Provider | Active When                                 |
| -------- | ------------------------------------------- |
| Geotab   | `activeTo` date has not passed              |
| Samsara  | A gateway device is currently associated    |
| Motive   | Provider's `status` field equals `"active"` |

**Driver status examples:**

| Provider       | Active When                                     |
| -------------- | ----------------------------------------------- |
| Geotab         | `activeTo` date has not passed                  |
| Motive         | Provider's `status` field equals `"active"`     |
| Most providers | Direct mapping from the provider's status field |

<Note>
  Terminal does not modify or compute this value beyond normalizing the
  provider's representation. The status reflects the entity's state in the
  provider system at the time of the last sync.
</Note>

## Entity Visibility

The `metadata.visibility` field is a Terminal-specific concept that indicates whether an entity's data is being ingested and returned by the API. This is computed at query time based on your connection's [filtering configuration](/guides/filtering).

| Value                    | Description                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `visible`                | Default state. Entity data is actively ingested and returned by the API               |
| `hidden_by_include_list` | An `includeIds` filter is configured but this entity is not in the list               |
| `hidden_by_exclude_list` | This entity is in the `excludeIds` filter list                                        |
| `hidden_by_status`       | A `status` filter is configured and this entity's status doesn't match                |
| `deleted`                | The entity was previously synced but has been hard-deleted from the provider's system |

<Note>
  When `includeIds` is present and non-empty, it takes highest priority. All
  other filter criteria (`status` and `excludeIds`) are ignored.
</Note>

### Filtering by Entity Type

Filters are configured separately for vehicles and drivers on each connection:

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

See the [Filtering Guide](/guides/filtering) for complete configuration details.

## Common Scenarios

### Scenario 1: Offboarded Entity

A driver is deactivated in the provider's system:

```json theme={null}
{
  "id": "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "status": "inactive",
  "firstName": "John",
  "lastName": "Smith",
  "metadata": {
    "visibility": "visible"
  }
}
```

The driver is still visible (returned by the API) but marked as inactive.

### Scenario 2: Filtered by Status

A connection is configured to only sync active vehicles, but an inactive vehicle exists:

```json theme={null}
{
  "id": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "status": "inactive",
  "name": "Truck 42",
  "metadata": {
    "visibility": "hidden_by_status"
  }
}
```

<Note>
  By default, hidden entities are not returned by the API. Use the `hidden=true`
  query parameter to include them.
</Note>

### Scenario 3: Hard-Deleted Entity

A vehicle was previously synced but has been permanently removed from the provider:

```json theme={null}
{
  "id": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "status": "active",
  "name": "Truck 42",
  "metadata": {
    "visibility": "deleted",
    "deletedAt": "2024-01-15T10:30:00Z"
  }
}
```

Terminal retains the record for historical reference. The `status` reflects the last known state before deletion.

<Note>
  By default, deleted entities are not returned by the API. Use the
  `deleted=true` query parameter to include them.
</Note>

## Related Resources

* [Vehicle & Driver Filtering](/guides/filtering) - Configure which entities are ingested
* [Common Models Overview](/models/overview) - Introduction to Terminal's data models
* [Vehicle Model](/models/vehicle) - Full vehicle schema reference
* [Driver Model](/models/driver) - Full driver schema reference
* [Trailer Model](/models/trailer) - Full trailer schema reference