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

# Writing Data to TSPs

> Learn how to create and update resources on telematics service providers through the Catena API

The Catena API allows you to **write data back to telematics service providers (TSPs)** through a unified interface. Instead of integrating with each TSP's API individually, you send a single request to Catena, and the platform handles the translation, authentication, and delivery to the correct TSP on your behalf.

<Check>
  **Unified Write Interface:** Use the same request format regardless of which TSP a fleet uses. Catena automatically translates your request into the TSP-specific format and handles authentication.
</Check>

***

## How It Works

```mermaid theme={null}
flowchart LR
    partner[["Partner<br/>(You)"]]
    catena["Catena API"]
    tsp[["TSP API"]]

    partner -->|"1. POST resource"| catena
    catena -->|"2. Translate & forward"| tsp
    tsp -->|"3. Response"| catena
    catena -->|"4. Result"| partner

    style partner fill:#dc3545,stroke:none,color:#ffffff
    style catena fill:#0083bf,stroke:none,color:#ffffff
    style tsp fill:#28a745,stroke:none,color:#ffffff
```

When you make a write request to the Catena API:

1. **You send a request** using Catena resource IDs — no need to track TSP-specific identifiers
2. **Catena translates IDs** — references like `sender_id` and `recipient_id` are automatically mapped to their corresponding TSP-specific identifiers (e.g., `source_sender_id`, `source_recipient_id`)
3. **Catena authenticates** with the TSP using the connection's stored credentials
4. **The result is returned** either immediately (sync) or tracked asynchronously (async)

<Info>
  All IDs in your request payload should be **Catena IDs**, not TSP-specific source IDs. Catena handles the mapping automatically.
</Info>

***

## Key Concepts

### Connection ID

Every write request requires a `connection_id`. This identifies which TSP and fleet combination the data should be written to. A connection represents an authenticated link between a fleet and their telematics provider.

<Warning>
  The `connection_id` is always required because it determines the target TSP and fleet. Without it, Catena cannot route the request.
</Warning>

<Tip>
  **How to find the connection ID:** Query the List Connections endpoint filtered by `fleet_refs`, or read the `connection_id` from an existing resource's GET response. See [Filter & Query Data](/recipes/filtering-requests#how-to-find-the-connection-id) for details.
</Tip>

### Supported Resources

Write operations are available on the following Telematics API endpoints:

| Resource          |              Create (POST)              |            Update (PATCH)            |
| ----------------- | :-------------------------------------: | :----------------------------------: |
| Vehicles          |      `POST /v2/telematics/vehicles`     | `PATCH /v2/telematics/vehicles/{id}` |
| Trailers          |      `POST /v2/telematics/trailers`     | `PATCH /v2/telematics/trailers/{id}` |
| Users (Drivers)   |       `POST /v2/telematics/users`       |   `PATCH /v2/telematics/users/{id}`  |
| Messages          |      `POST /v2/telematics/messages`     |                   —                  |
| Group Messages    |   `POST /v2/telematics/group-messages`  |                   —                  |
| DVIR Logs         |     `POST /v2/telematics/dvir-logs`     |                   —                  |
| Fuel Transactions | `POST /v2/telematics/fuel-transactions` |                   —                  |

<Tip>
  Not all TSPs support every write operation. Check the [Integrations API](/api-reference/integrations-api) to verify which resources a specific TSP supports for write-back by looking at the `read_write` share level.
</Tip>

### Automatic ID Translation

When you reference other Catena resources in your payload (e.g., a `sender_id` when creating a message), Catena automatically resolves these to the TSP-specific identifiers before forwarding the request. You never need to look up or store TSP-side IDs yourself.

***

## Processing Modes

Catena supports two processing modes for write operations, controlled by the `is_sync` query parameter:

<CardGroup cols={2}>
  <Card title="Asynchronous (Default)" icon="clock" href="/get-started/writing-data-async">
    Fire-and-forget pattern. Returns immediately with a tracking ID. The operation is processed in the background with automatic retries and rate limiting.

    **Best for:** Bulk operations, non-critical writes, production workloads where you don't need an immediate TSP response.
  </Card>

  <Card title="Synchronous" icon="bolt" href="/get-started/writing-data-sync">
    Waits for the TSP response before returning. Slower, but gives you immediate feedback on success or failure.

    **Best for:** Interactive workflows, debugging, initial integration development, cases where you need the TSP's response immediately.
  </Card>
</CardGroup>

|                         | Async (`is_sync=false`)          | Sync (`is_sync=true`)            |
| ----------------------- | -------------------------------- | -------------------------------- |
| **Response time**       | Instant (202 Accepted)           | Depends on TSP response time     |
| **Success status code** | `202`                            | `200`                            |
| **Error handling**      | Via webhooks                     | Immediate in response            |
| **Retries**             | Automatic                        | Your responsibility              |
| **Rate limiting**       | Managed by Catena                | Your responsibility              |
| **TSP resource ID**     | Available via webhook on success | Available in response on success |
| **Use case**            | Production workloads             | Development & debugging          |

***

## Tracking Operations

Every write request — whether async or sync — creates a **resource operation** that tracks the lifecycle of the request. You can monitor operations through two channels:

### Webhooks (Recommended)

Subscribe to resource operation events to receive real-time status updates:

| Event                          | Description                                     |
| ------------------------------ | ----------------------------------------------- |
| `resource_operation.created`   | A new write operation was submitted             |
| `resource_operation.succeeded` | The operation completed successfully on the TSP |
| `resource_operation.failed`    | The operation failed after all retry attempts   |

Use the wildcard `resource_operation.*` to subscribe to all resource operation events at once.

<Info>
  See the [Webhook Setup Guide](/api-reference/webhooks/webhook-setup) for instructions on subscribing to events.
</Info>

### Polling

You can also query the status of resource operations directly through the Integrations API:

* **List operations:** `GET /v2/integrations/connections/resource-operations` — retrieve a paginated list of operations with flexible filtering by resource type, connection, status, and more
* **Get a single operation:** `GET /v2/integrations/connections/{connection_id}/resource-operations/{resource_operation_id}` — get the full details and logs for a specific operation

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Async Operations" icon="clock" href="/get-started/writing-data-async">
    Learn how asynchronous write operations work, including retry logic, webhook tracking, and best practices for production use.
  </Card>

  <Card title="Sync Operations" icon="bolt" href="/get-started/writing-data-sync">
    Learn how synchronous write operations work, including error handling, response codes, and when to use them.
  </Card>
</CardGroup>