Skip to main content
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.

​
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:
EntityDescriptionID Prefix
VehicleTrucks, vans, cars, and other motorized assetsvcl_
DriverIndividuals who operate vehiclesdrv_
TrailerNon-motorized assets that attach to vehiclestrl_
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.
ValueDescription
activeThe entity is currently operational and tracked in the provider’s system
inactiveThe 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:
ProviderActive When
GeotabactiveTo date has not passed
SamsaraA gateway device is currently associated
MotiveProvider’s status field equals "active"
Driver status examples:
ProviderActive When
GeotabactiveTo date has not passed
MotiveProvider’s status field equals "active"
Most providersDirect mapping from the provider’s status field
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.

​
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.
ValueDescription
visibleDefault state. Entity data is actively ingested and returned by the API
hidden_by_include_listAn includeIds filter is configured but this entity is not in the list
hidden_by_exclude_listThis entity is in the excludeIds filter list
hidden_by_statusA status filter is configured and this entity’s status doesn’t match
deletedThe entity was previously synced but has been hard-deleted from the provider’s system
When includeIds is present and non-empty, it takes highest priority. All other filter criteria (status and excludeIds) are ignored.

​
Filtering by Entity Type

Filters are configured separately for vehicles and drivers on each connection: 
{
  "filters": {
    "vehicles": {
      "status": "active",
      "excludeIds": ["vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"]
    },
    "drivers": {
      "status": "active",
      "excludeIds": ["drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"]
    }
  }
}
See the Filtering Guide for complete configuration details.

​
Common Scenarios

​
Scenario 1: Offboarded Entity

A driver is deactivated in the provider’s system: 
{
  "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: 
{
  "id": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "status": "inactive",
  "name": "Truck 42",
  "metadata": {
    "visibility": "hidden_by_status"
  }
}
By default, hidden entities are not returned by the API. Use the hidden=true query parameter to include them.

​
Scenario 3: Hard-Deleted Entity

A vehicle was previously synced but has been permanently removed from the provider: 
{
  "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.
By default, deleted entities are not returned by the API. Use the deleted=true query parameter to include them.