Skip to main content
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:
  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)
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 account the data should be written to. A connection represents an authenticated link between a fleet and their telematics provider. If several fleets share the same TSP credentials, they share one connection, so data written through it lands in that shared TSP account.
The connection_id is always required because it determines the target TSP account. 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:
Not all TSPs support every write operation. To see which providers Catena can write each resource to, filter the supported providers list by Can send, or check the Write Support section on a provider’s page. To check programmatically, List Integrations Per TSP returns each TSP’s write support per resource in its operations field, as operations.<resource>.create and operations.<resource>.update. Each value is implemented, not_implemented (in progress), not_supported or unknown (not yet verified).

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

​
Your Own Reference

When you create a message or a group message, you can include a reference from your own system in the optional partner_ref field, for example the ID of the record you saved before calling Catena. Catena does not interpret the value. It stores it on the resource operation and returns it to you trimmed (leading and trailing whitespace removed, see the rules below), so the result of every write carries a key that already means something in your system.
Catena returns partner_ref on:
  • The response to your POST, in both sync (200) and async (202) mode
  • GET /v2/integrations/connections/resource-operations and GET /v2/integrations/connections/{connection_id}/resource-operations/{resource_operation_id}
  • The resource_operation.created, resource_operation.succeeded and resource_operation.failed webhook events
Because resource_operation.succeeded carries both your partner_ref and the Catena ID of the created message or group message (resource_id), one event is enough to link your record to it in Catena. See Matching Results to Your Records for a worked example.
Use an identifier, not personal or sensitive data. The value appears in API responses and webhook payloads sent to your endpoints.
Resource operation endpoints and events are provisional. Adding partner_ref is a backward-compatible change: requests that leave it out behave exactly as before.

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

​
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: Subscribe to resource operation events to receive real-time status updates: Use the wildcard resource_operation.* to subscribe to all resource operation events at once. Every event includes the operation’s partner_ref if you supplied one when you created the message or group message.
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.