> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://catena.ferndocs.com/get-started/writing-data/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server.

# Writing Data to TSPs

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.

---

## How It Works

```mermaid
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.

---

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

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

### 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/integrations-api) to verify which resources a specific TSP supports for write-back by looking at the `read_write` share level.

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

#### [Asynchronous (Default)](/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.

#### [Synchronous](/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.

|                         | 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/notifications/webhooks/webhook-setup) for instructions on subscribing to events.

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

#### [Async Operations](/get-started/writing-data-async)

Learn how asynchronous write operations work, including retry logic, webhook tracking, and best practices for production use.

#### [Sync Operations](/get-started/writing-data-sync)

Learn how synchronous write operations work, including error handling, response codes, and when to use them.

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

## Docs

- [Async Write Operations](https://catena.ferndocs.com/get-started/writing-data/async.md): Use asynchronous write operations for fire-and-forget resource creation and updates on TSPs
- [Sync Write Operations](https://catena.ferndocs.com/get-started/writing-data/sync.md): Use synchronous write operations for immediate TSP feedback when creating or updating resources