> ## 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.
# Sync Write Operations
> Use synchronous write operations for immediate TSP feedback when creating or updating resources
Synchronous mode couples your API call directly to the TSP's response. When you submit a request with `is_sync=true`, Catena forwards it to the TSP, waits for the response, and returns the result directly to you — all in a single HTTP round-trip.
**Best for development and debugging.** Sync mode lets you see TSP responses immediately, making it easy to iterate on payloads and troubleshoot field requirements across different providers.
***
## How It Works
```mermaid theme={null}
sequenceDiagram
participant You as Your App
participant Catena as Catena API
participant TSP as TSP API
You->>Catena: POST /v2/telematics/messages?is_sync=true
Catena->>TSP: Forward request
alt Success
TSP-->>Catena: 200 OK
Catena-->>You: 200 OK (resource operation with resource_id)
else TSP Error
TSP-->>Catena: Error
Catena-->>You: 502 Bad Gateway (resource operation with logs)
end
```
Send a `POST` or `PATCH` request to the Telematics API with the `is_sync=true` query parameter.
The request is translated and forwarded to the TSP immediately — no queuing, no background processing.
The response contains the complete resource operation, including the TSP's response data, error details, or the created resource's IDs.
Sync mode does **not** include automatic retries or rate limiting. If the TSP is temporarily unavailable or rate-limited, the error is returned directly to you and it's your responsibility to retry.
***
## Example: Sending a Message (Success)
### Request
```bash cURL theme={null}
curl -X POST 'https://api.catenatelematics.com/v2/telematics/messages?is_sync=true' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
"sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
"recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
"message_text": "Delivery confirmed at warehouse B",
"priority": "low"
}'
```
### Response (200 OK)
On success, the response contains the completed resource operation with `resource_id` and `source_id` populated:
```json theme={null}
{
"id": "019df230-a1b2-7890-cdef-1234567890ab",
"created_at": "2026-05-04T09:15:00.000000Z",
"updated_at": "2026-05-04T09:15:01.500000Z",
"deleted_at": null,
"partner_id": "9df92c50-d8a7-460e-aab2-a93f1de9280a",
"connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
"resource": "message",
"resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"source_id": "98765432",
"operation_type": "create",
"payload": {
"priority": "low",
"sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
"message_text": "Delivery confirmed at warehouse B",
"recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
"connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
"source_sender_id": "51477344",
"reply_to_message_id": null,
"source_recipient_id": "51477717",
"source_reply_to_message_id": null
},
"status": "success",
"logs": []
}
```
Key differences from the async response:
* **`status`** is `"success"` (not `"pending"`)
* **`resource_id`** contains the Catena ID of the newly created resource
* **`source_id`** contains the TSP-side ID of the newly created resource
***
## Example: Sending a Message (Failure)
When the TSP returns an error, Catena returns a `502 Bad Gateway` response because it acts as a gateway to the TSP and the error originated upstream.
### Response (502 Bad Gateway)
```json theme={null}
{
"id": "019df22e-f255-7a7c-b1d7-59f509071b6d",
"created_at": "2026-05-04T08:51:01.487639Z",
"updated_at": "2026-05-04T08:51:02.179210Z",
"deleted_at": null,
"partner_id": "9df92c50-d8a7-460e-aab2-a93f1de9280a",
"connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
"resource": "message",
"resource_id": null,
"source_id": null,
"operation_type": "create",
"payload": {
"priority": "low",
"sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
"message_text": "Delivery confirmed at warehouse B",
"recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
"connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
"source_sender_id": "51477344",
"reply_to_message_id": null,
"source_recipient_id": "51477717",
"source_reply_to_message_id": null
},
"status": "failed",
"logs": [
{
"id": "019df22f-093f-7949-908d-d5564941fdbe",
"created_at": "2026-05-04T08:51:02.079501Z",
"updated_at": "2026-05-04T08:51:02.079501Z",
"resource_operation_id": "019df22e-f255-7a7c-b1d7-59f509071b6d",
"status": "failed",
"error_type": "auth",
"error_details": "Client error '401 Unauthorized' for url 'https://api.samsara.com/v1/fleet/messages'\nFor more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401"
}
]
}
```
When a sync operation fails, `resource_id` and `source_id` are both `null` because the resource was never created on the TSP.
### Understanding Error Responses
| HTTP Status | Meaning |
| ----------------- | ------------------------------------------------------------------ |
| `200 OK` | The TSP accepted the request. The resource was created or updated. |
| `502 Bad Gateway` | The TSP returned an error. Check the `logs` array for details. |
The `logs` array contains one entry per attempt with:
| Field | Description |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `status` | `"success"` or `"failed"` |
| `error_type` | Category of error: `auth`, `validation`, `network`, or `tsp` |
| `error_details` | Human-readable description of what went wrong, often including the TSP's error message and HTTP status |
***
## When to Use Sync Mode
When you're first integrating write operations, sync mode lets you see TSP errors immediately. Different TSPs have different field requirements — sync mode helps you iterate quickly on your payload structure.
When your end user needs immediate confirmation that a resource was created. For example, a dispatcher sending a message who needs to see "Message sent" or an error right away.
When you need the TSP-assigned resource ID (`source_id`) or other response data immediately to continue your workflow.
**Recommended development workflow:** Start with `is_sync=true` while building your integration to quickly identify and fix payload issues. Once your payloads are stable, switch to async mode (`is_sync=false`) for production to benefit from automatic retries and rate limiting.
***
## Sync vs Async: Choosing the Right Mode
```mermaid theme={null}
flowchart TD
start["Write Operation"] --> question{"Need immediate
TSP feedback?"}
question -->|"Yes"| sync["Use Sync Mode
(is_sync=true)"]
question -->|"No"| async["Use Async Mode
(default)"]
sync --> dev{"Development or
Production?"}
dev -->|"Development"| keep_sync["Keep sync for
faster debugging"]
dev -->|"Production"| consider["Consider switching
to async"]
async --> webhooks["Set up webhooks for
resource_operation events"]
style start fill:#0083bf,stroke:none,color:#ffffff
style sync fill:#dc3545,stroke:none,color:#ffffff
style async fill:#28a745,stroke:none,color:#ffffff
style question fill:#ffc107,stroke:none,color:#00354d
style dev fill:#ffc107,stroke:none,color:#00354d
style keep_sync fill:#00bae6,stroke:none,color:#ffffff
style consider fill:#00bae6,stroke:none,color:#ffffff
style webhooks fill:#00bae6,stroke:none,color:#ffffff
```
***
## Next Steps
Learn about async mode with automatic retries and webhook tracking.
Configure webhooks to track resource operation outcomes.