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.

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	Trucks, vans, cars, and other motorized assets	`vcl_`
Driver	Individuals who operate vehicles	`drv_`
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

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.

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

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.

Vehicle & Driver Filtering - Configure which entities are ingested
Common Models Overview - Introduction to Terminal’s data models
Vehicle Model - Full vehicle schema reference
Driver Model - Full driver schema reference
Trailer Model - Full trailer schema reference

About Us

Implementation Guides

Use Case Guides

Data Destinations

Terminal Platform

Advanced

Entity Status & Visibility

What is an Entity?

Entity Status

How Status is Determined

Entity Visibility

Filtering by Entity Type

Common Scenarios

Scenario 1: Offboarded Entity

Scenario 2: Filtered by Status

Scenario 3: Hard-Deleted Entity

​What is an Entity?

​Entity Status

​How Status is Determined

​Entity Visibility

​Filtering by Entity Type

​Common Scenarios

​Scenario 1: Offboarded Entity

​Scenario 2: Filtered by Status

​Scenario 3: Hard-Deleted Entity

​Related Resources

What is an Entity?

Entity Status

How Status is Determined

Entity Visibility

Filtering by Entity Type

Common Scenarios

Scenario 1: Offboarded Entity

Scenario 2: Filtered by Status

Scenario 3: Hard-Deleted Entity

Related Resources