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

# Filter & Query Data

> How to filter and query telematics data using fleet refs, fleet IDs, and connection IDs

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

```mermaid theme={null}
flowchart LR
    fleet["Fleet\nfleet_ref = FLEET-42"]
    conn1["Connection A\n(Samsara)"]
    conn2["Connection B\n(Motive)"]

    fleet --- conn1
    fleet --- conn2

    style fleet fill:#ffc107,stroke:none,color:#00354d
    style conn1 fill:#00bae6,stroke:none,color:#ffffff
    style conn2 fill:#00bae6,stroke:none,color:#ffffff
```

***

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

```bash theme={null}
# 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:

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

<Info>
  You can also filter by `fleet_ids` (Catena's internal UUID) instead of `fleet_refs`. Use whichever identifier your system stores.
</Info>

***

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

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

For more details on write operations, see [Writing Data to TSPs](/get-started/writing-data).

***

## How to Find the Connection ID

There are two approaches depending on your use case:

<Tabs>
  <Tab title="Creating a new resource">
    Query the [List Connections](/api-reference/integrations-api) endpoint and filter by `fleet_refs` to find the connection you need:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Updating an existing resource">
    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.

    ```bash theme={null}
    # 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"}'
    ```
  </Tab>
</Tabs>

<Tip>
  **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.
</Tip>