Writing Data to TSPs | Catena Telematics 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.

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

When you make a write request to the Catena API:

You send a request using Catena resource IDs — no need to track TSP-specific identifiers
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)
Catena authenticates with the TSP using the connection’s stored credentials
The result is returned either immediately (sync) or tracked asynchronously (async)

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.

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

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 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`	—

Not all TSPs support every write operation. Check the 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)

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

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.

See the Webhook Setup Guide 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

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

Sync Operations

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