Skip to main content
POST
/
v2
/
telematics
/
workflows
Create Workflow
curl --request POST \
  --url https://api.catenatelematics.com/v2/telematics/workflows \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "partner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payload": {},
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "deleted_at": "2023-11-07T05:31:56Z",
  "resource_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source_id": "<string>",
  "status": "pending",
  "logs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "resource_operation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "error_details": "<string>",
      "response_status_code": 123,
      "response_headers": {}
    }
  ]
}
Provisional endpoint
This endpoint is available for early access. The core schema is stable, but minor details — such as field names or added fields — may change before it becomes generally available. Backward compatibility is not guaranteed.

See API Stability & Versioning for details on provisional endpoints.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
is_sync
boolean
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

Workflow model for creating planned jobs, routes, and dispatches.

​
connection_id
string<uuid>
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 | null

External system identifier for the workflow.

​
source_driver_id
string | null

External system identifier for the driver.

​
source_vehicle_id
string | null

External system identifier for the vehicle.

​
territory_name
string | null

Name of the territory or region for the workflow.

​
workflow_status
enum<string> | null

Workflow status.

Available options:
PLANNED,
ACTIVE,
COMPLETED,
CANCELLED
​
started_at
string<date-time> | null

Datetime when the workflow started.

​
ended_at
string<date-time> | null

Datetime when the workflow ended.

​
total_distance
number | null

Total workflow distance.

​
total_distance_unit
enum<string> | null

Unit for total_distance.

Available options:
m,
km,
mi,
ft,
nmi
​
instructions
string | null

Workflow-level instructions.

​
stops
WorkflowStopCreate · object[] | null

Workflow stops.

Response

The workflow was created successfully.

Resource operation model

​
partner_id
string<uuid>
required

The ID of the partner that created the operation.

​
connection_id
string<uuid>
required

The ID of the connection

​
resource
enum<string>
required

The type of resource to operate on (e.g., vehicle, driver).

Available options:
asset,
driver_association,
driver_vehicle_association,
driver_event_log,
driver_safety_event,
dvir_log,
dvir_log_defect,
engine_log,
engine_status,
fuel_transaction,
fleet_info,
hos_availability,
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<string>
required

The type of operation to perform (e.g., create, update).

Available options:
create,
update
​
payload
Operation Payload · object
required

The payload of the operation, containing the resource attributes to be created or updated.

​
id
string<uuid>

Unique identifier for the resource operation.

​
created_at
string<date-time>

Immutable: The datetime the record was created in Catena Telematics.

​
updated_at
string<date-time>

The datetime the record was last modified in Catena Telematics.

​
deleted_at
string<date-time> | null

The datetime the record was logically deleted from Catena Telematics.

​
resource_id
string<uuid> | null

Unique identifier of the record. Can be null for create operations where the source does not exist yet.

​
source_id
string | null

The unique identifier of the resource in the source system. Required for update operations.

​
status
enum<string>
default:pending

The status of the operation

Available options:
pending,
success,
failed
​
logs
ResourceOperationLog · object[]

Log entries for each attempt to execute this operation.