Filter & Query Data - Catena Telematics API

Every Telematics API endpoint accepts a set of common query parameters that let you scope results to specific fleets, connections, or time windows. This guide explains the three main identifiers and when to use each one.

Fleet Identifiers

The Catena API uses several identifiers to reference fleets and their TSP connections.

Identifier	Description	Example
`fleet_id`	Catena’s internal UUID for a fleet. Assigned automatically.	`a1b2c3d4-...`
`fleet_ref`	Your organization’s external reference for a fleet. Set during onboarding.	`FLEET-42`
`connection_id`	UUID for a specific Fleet + TSP pairing. Assigned when a fleet connects to a provider.	`e5f6g7h8-...`

Why the distinction matters

A single fleet can connect to multiple telematics providers (e.g., Samsara for GPS tracking and Motive for ELD compliance). Each of these links is a separate connection.

Reading Data

When you query the Telematics API with a fleet_ref, Catena returns data from all providers the fleet is connected to. You don’t need to know which TSP sourced a specific record.

# Returns vehicles from ALL connected TSPs for this fleet
curl 'https://api.catenatelematics.com/v2/telematics/vehicles?fleet_refs=FLEET-42'

If you need data from a specific provider only, add the connection_id filter:

# Returns vehicles from Samsara only
curl 'https://api.catenatelematics.com/v2/telematics/vehicles?fleet_refs=FLEET-42&connection_id=<CONNECTION_A_UUID>'

You can also filter by fleet_ids (Catena’s internal UUID) instead of fleet_refs. Use whichever identifier your system stores.

Writing Data

When you write data (create or update a resource), Catena needs to know which TSP should receive the request. Since a fleet can have multiple connections, you must provide a connection_id in every write request.

Write endpoints always require a connection_id. Catena cannot send the same write to all TSPs — the target provider must be explicit.

For more details on write operations, see Writing Data to TSPs.

How to Find the Connection ID

There are two approaches depending on your use case:

Creating a new resource
Updating an existing resource

Query the List Connections endpoint and filter by fleet_refs to find the connection you need:

curl 'https://api.catenatelematics.com/v2/integrations/connections?fleet_refs=FLEET-42'

The response includes the connection_id, tsp_id, and source_name for each connection, so you can identify the correct TSP.

Retrieve the resource first — every resource returned by the Telematics API includes a connection_id field that tells you which TSP ingested it. Use that same connection_id in your update request.

# 1. Get the vehicle to find its connection_id
curl 'https://api.catenatelematics.com/v2/telematics/vehicles/{vehicle_id}'

# Response includes: "connection_id": "e5f6g7h8-..."

# 2. Use that connection_id in the update
curl -X PATCH 'https://api.catenatelematics.com/v2/telematics/vehicles/{vehicle_id}' \
  -H 'Content-Type: application/json' \
  -d '{"connection_id": "e5f6g7h8-...", "vehicle_name": "Truck 99"}'

Best practice: Store the connection_id alongside the fleet_ref in your system when you first discover it. This avoids an extra API call on every write operation.

​Fleet Identifiers

​Why the distinction matters

​Reading Data

​Writing Data

​How to Find the Connection ID

Fleet Identifiers

Why the distinction matters

Reading Data

Writing Data

How to Find the Connection ID