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

# 🧪 Update Workflow

PATCH https://api.catenatelematics.com/v2/telematics/workflows/{id}
Content-Type: application/json

Update an existing workflow resource operation.

Reference: https://catena.ferndocs.com/api-reference/telematics/fleet-operations-tracking/update-workflow

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `id` (string, required) — The unique identifier of the workflow

### Query parameters

- `is_sync` (boolean, optional, default: false) — Whether to process the request synchronously. If `true`, Catena will attempt to create or update the resource immediately with the TSP and return the result in the response. When performing synchronous operations, you are responsible for handling any necessary retries in case of transient failures.If `false` (default), Catena will create an asynchronous operation, and you can check the status of the operation using the returned operation ID.

### Body (application/json)

This endpoint expects a WorkflowUpdate.

- `connection_id` (string, required) — Unique identifier of the connection at Catena Telematics which will be used to create this resource. A connection represents a Fleet/TSP pairing.
- `source_workflow_id` (string, optional, nullable) — External system identifier for the workflow.
- `source_driver_id` (string, optional, nullable) — External system identifier for the driver.
- `source_vehicle_id` (string, optional, nullable) — External system identifier for the vehicle.
- `territory_name` (string, optional, nullable) — Name of the territory or region for the workflow.
- `workflow_status` (enum, optional, nullable) — Workflow status.
  - Allowed values: `PLANNED`, `ACTIVE`, `COMPLETED`, `CANCELLED`
- `started_at` (datetime, optional, nullable) — Datetime when the workflow started.
- `ended_at` (datetime, optional, nullable) — Datetime when the workflow ended.
- `total_distance` (double, optional, nullable) — Total workflow distance.
- `total_distance_unit` (enum, optional, nullable) — Unit for total_distance.
  - Allowed values: `m`, `km`, `mi`, `ft`, `nmi`
- `instructions` (string, optional, nullable) — Workflow-level instructions.
- `stops` (list of WorkflowStopCreate, optional, nullable) — Workflow stops.

## Response

### 200

The workflow was updated successfully.

- `partner_id` (string, required) — The ID of the partner that created the operation.
- `connection_id` (string, required) — The ID of the connection
- `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver).
  - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow`
- `operation_type` (enum, required) — The type of operation to perform (e.g., create, update).
  - Allowed values: `create`, `update`
- `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated.
- `id` (string, optional) — Unique identifier for the resource operation.
- `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics.
- `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics.
- `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics.
- `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet.
- `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations.
- `status` (enum, optional) — The status of the operation
  - Allowed values: `pending`, `success`, `failed`
- `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation.

### 202

The request to update the workflow has been accepted and is being processed.

- `partner_id` (string, required) — The ID of the partner that created the operation.
- `connection_id` (string, required) — The ID of the connection
- `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver).
  - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow`
- `operation_type` (enum, required) — The type of operation to perform (e.g., create, update).
  - Allowed values: `create`, `update`
- `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated.
- `id` (string, optional) — Unique identifier for the resource operation.
- `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics.
- `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics.
- `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics.
- `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet.
- `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations.
- `status` (enum, optional) — The status of the operation
  - Allowed values: `pending`, `success`, `failed`
- `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation.

## Errors

### 400 Bad Request Error

Bad Request

- `code` (integer, optional, default: 400)
- `message` (string, optional, default: Bad Request)
- `detail` (string, optional, nullable)

### 401 Unauthorized Error

Unauthorized

- `code` (integer, optional, default: 401)
- `message` (string, optional, default: Unauthorized)
- `detail` (string, optional, nullable)

### 403 Forbidden Error

Forbidden

- `code` (integer, optional, default: 403)
- `message` (string, optional, default: Forbidden)
- `detail` (string, optional, nullable)

### 404 Not Found Error

Not Found

- `code` (integer, optional, default: 404)
- `message` (string, optional, default: Not Found)
- `detail` (string, optional, nullable)

### 405 Method Not Allowed Error

Method Not Allowed

- `code` (integer, optional, default: 405)
- `message` (string, optional, default: Method Not Allowed)
- `detail` (string, optional, nullable)

### 409 Conflict Error

Conflict

- `code` (integer, optional, default: 409)
- `message` (string, optional, default: Conflict)
- `detail` (string, optional, nullable)

### 422 Unprocessable Entity Error

Unprocessable Entity

- `code` (integer, optional, default: 422)
- `message` (string, optional, default: Invalid Request Body)
- `detail` (list of ValidationErrorDetail, optional, nullable)

### 429 Too Many Requests Error

Too Many Requests

- `code` (integer, optional, default: 429)
- `message` (string, optional, default: Too Many Requests)
- `detail` (RetryAfterDetail, optional, nullable)

### 500 Internal Server Error

Internal Server Error

- `message` (string, optional, default: Internal Server Error)

### 501 Not Implemented Error

Not Implemented

- `code` (integer, optional, default: 501)
- `message` (string, optional, default: Not Implemented)
- `detail` (string, optional, nullable)

### 502 Bad Gateway Error

The request to update the workflow could not be processed at this time. Please see the response for more details.

- `partner_id` (string, required) — The ID of the partner that created the operation.
- `connection_id` (string, required) — The ID of the connection
- `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver).
  - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow`
- `operation_type` (enum, required) — The type of operation to perform (e.g., create, update).
  - Allowed values: `create`, `update`
- `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated.
- `id` (string, optional) — Unique identifier for the resource operation.
- `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics.
- `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics.
- `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics.
- `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet.
- `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations.
- `status` (enum, optional) — The status of the operation
  - Allowed values: `pending`, `success`, `failed`
- `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation.

## Types

### WorkflowStopCreate

Workflow stop payload for create operations.

- `source_stop_id` (string, optional, nullable)
- `sequence_number` (integer, optional, nullable)
- `stop_type` (enum, optional, nullable) — High-level classification of a stop within a workflow/trip.
  - Allowed values: `PICKUP`, `DELIVERY`, `TRANSFER`, `YARD`, `FUEL`, `REST`, `INSPECTION`, `MAINTENANCE`, `WAITING`, `OFFICE`, `OTHER`
- `activities` (list of enum, optional, nullable)
  - Allowed values: `START_TRIP`, `END_TRIP`, `ARRIVE`, `DEPART`, `PICKUP`, `DELIVERY`, `DRIVING`, `ON_DUTY`, `OFF_DUTY`, `SLEEPER`, `LOADING`, `UNLOADING`, `HOOK_DROP`, `YARD_MOVE`, `PERSONAL_CONVEYANCE`, `WAITING`, `BREAKDOWN`, `ACCIDENT`, `INSPECTION`, `DVIR`, `FUEL`, `OFFICE_WORK`, `OTHER`
- `location_name` (string, optional, nullable)
- `latitude` (double, optional, nullable)
- `longitude` (double, optional, nullable)
- `street` (string, optional, nullable)
- `city` (string, optional, nullable)
- `state` (string, optional, nullable)
- `postal_code` (string, optional, nullable)
- `country_code` (string, optional, nullable)
- `instructions` (string, optional, nullable)
- `scheduled_arrival` (datetime, optional, nullable)
- `scheduled_departure` (datetime, optional, nullable)

### ResourceOperationLog

API response model for a resource operation log entry.

- `id` (string, required) — Unique identifier for the log entry.
- `created_at` (datetime, required) — Timestamp when the log entry was created.
- `updated_at` (datetime, required) — Timestamp when the log entry was last updated.
- `resource_operation_id` (string, required) — The ID of the resource operation this log entry belongs to.
- `status` (enum, required) — The status of the operation attempt.
  - Allowed values: `success`, `failed`
- `error_type` (enum, optional, nullable) — The type of error that occurred, if any.
  - Allowed values: `auth`, `validation`, `network`, `tsp`
- `error_details` (string, optional, nullable) — Detailed information about the error, if any.
- `response_status_code` (integer, optional, nullable) — HTTP status code returned by the TSP, if available.
- `response_headers` (map from string to string, optional, nullable) — HTTP response headers from the TSP (e.g. rate limit state).

### ValidationErrorDetail

- `path` (string, required)
- `input` (string, required)
- `message` (string, required)
- `error_type` (string, required)

### RetryAfterDetail

- `retry_after_seconds` (integer, required)
- `message` (string, required)

## Examples

### Example 1

**Request**

```json
{
  "connection_id": "string"
}
```

**Response**

```json
{
  "partner_id": "string",
  "connection_id": "string",
  "resource": "asset",
  "operation_type": "create",
  "payload": {},
  "id": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "deleted_at": "2024-01-15T09:30:00Z",
  "resource_id": "string",
  "source_id": "string",
  "status": "pending",
  "logs": [
    {
      "id": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "resource_operation_id": "string",
      "status": "success",
      "error_type": "auth",
      "error_details": "string",
      "response_status_code": 1,
      "response_headers": {}
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.catenatelematics.com/v2/telematics/workflows/id"

payload = { "connection_id": "string" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.catenatelematics.com/v2/telematics/workflows/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"connection_id":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.catenatelematics.com/v2/telematics/workflows/id"

	payload := strings.NewReader("{\n  \"connection_id\": \"string\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.catenatelematics.com/v2/telematics/workflows/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_id\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.catenatelematics.com/v2/telematics/workflows/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_id\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.catenatelematics.com/v2/telematics/workflows/id', [
  'body' => '{
  "connection_id": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.catenatelematics.com/v2/telematics/workflows/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"connection_id\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["connection_id": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.catenatelematics.com/v2/telematics/workflows/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 2

**Request**

```json
{
  "connection_id": "string"
}
```

**Response**

```json
{
  "partner_id": "string",
  "connection_id": "string",
  "resource": "asset",
  "operation_type": "create",
  "payload": {},
  "id": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "deleted_at": "2024-01-15T09:30:00Z",
  "resource_id": "string",
  "source_id": "string",
  "status": "pending",
  "logs": [
    {
      "id": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "resource_operation_id": "string",
      "status": "success",
      "error_type": "auth",
      "error_details": "string",
      "response_status_code": 1,
      "response_headers": {}
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.catenatelematics.com/v2/telematics/workflows/id"

payload = { "connection_id": "string" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.catenatelematics.com/v2/telematics/workflows/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"connection_id":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.catenatelematics.com/v2/telematics/workflows/id"

	payload := strings.NewReader("{\n  \"connection_id\": \"string\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.catenatelematics.com/v2/telematics/workflows/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_id\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.catenatelematics.com/v2/telematics/workflows/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_id\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.catenatelematics.com/v2/telematics/workflows/id', [
  'body' => '{
  "connection_id": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.catenatelematics.com/v2/telematics/workflows/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"connection_id\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["connection_id": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.catenatelematics.com/v2/telematics/workflows/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```