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.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.
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_idandrecipient_idare 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 aconnection_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.
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 | — |
Automatic ID Translation
When you reference other Catena resources in your payload (e.g., asender_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 theis_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 |
resource_operation.* to subscribe to all resource operation events at once.
See the Webhook Setup Guide for instructions on subscribing to events, and the Subscribe to Webhooks recipe for a step-by-step walkthrough.
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.