/tasktemplates

Create a task template: a configuration that creates tasks automatically when a platform trigger fires, or on a schedule (see below). A platform trigger names a business fact (tour created, tour assigned, each stop of a tour, tour completed, shipment created). 'tour-stop' is the stop trigger: it creates one task per stop when the tour is planned, not when a driver arrives. Each trigger provides data objects (tour; additionally stop for the stop trigger; shipment for shipment triggers) that the template's task name, description, and form may reference in Liquid expressions, resolved once per created task; the same objects' fields are available to the optional rule-group filter that narrows which occurrences fire (dotted paths, e.g. 'tour.carrier' or 'stop.address.city'), together with the tenant's tour or shipment properties at 'tour.properties.

Liquid syntax, unknown root variables, and filter fields/operators are validated at save time, property rules against the tenant's current property definitions; a broken definition is rejected with per-field issues. Tasks created by a template carry origin 'template', the template's id in templateId, and the resolved form snapshot; a stop task references its STOP by the stop's stable id (orn::tour/

A template on the stop trigger may set placement, which says at which point of the stop the driver app and the carrier portal prompt its tasks: 'on-arrival' (once the arrival is recorded), 'before-handling' (when the departure begins, before load statuses, barcode scans included, and proofs are captured), 'after-loads' (during the departure, after the driver marks or scans the loads and before a signature, photo or other proof is captured; a proof the driver starts by hand does not bring it up, and the carrier portal prompts it with the other departure placements) or 'before-departure' (after every other step, directly before the departure is recorded). Omitted, the tasks are prompted on arrival. placement on any other trigger is rejected with 400. It is copied onto each task at creation, so changing it later does not move tasks that already exist. It only decides when a task is prompted: a task can be opened at any time, and a blocking task holds its stop's departure whatever its placement.

A schedule trigger (type: 'schedule') fires on a cadence (daily, on chosen weekdays, or monthly on a day or the last day) at a time in a time zone, optionally between a start and an end day. It refers to one vehicle, carrier or carrier user, or to a set of them (the active vehicles of a carrier or of the organization, every active carrier, the active users of a carrier) narrowed by optional conditions, and creates one task per object at every occurrence, at most 500. Its data objects are the object ('vehicle', 'carrier' or 'carrierUser') and 'occurrence' (the scheduled time as occurrence.date). It may assign each task relative to its object and set a due time of day; its tasks never block. A schedule template whose one object is deleted or set inactive deactivates itself and says why in autoDeactivation.

An optional key gives the template a stable routing label that created tasks carry as templateKey. It must be unique per organization (deleted templates keep theirs, so a key is never reused for a different template) and cannot be changed after creation. The template's identity stays id.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
length between 1 and 200

Operator-facing name of the template (1-200 characters). Not required to be unique.

string
^[a-z0-9][a-z0-9-]{1,62}$

Optional stable routing label for integrators, e.g. 'pallet-check': 2-63 lowercase letters, digits, or hyphens, starting with a letter or digit. Unique per organization, also against deleted templates, and IMMUTABLE once set: a PATCH carrying it is rejected, and a taken key is never released, so choose it deliberately. Tasks created from the template carry it as templateKey. Never the template's identity; that is id.

string
enum

Initial lifecycle status. 'inactive' creates the template paused. Defaults to 'active'.

Allowed:
trigger
required

When this template fires: a curated platform trigger naming a business fact (tour created, tour assigned, each stop of a tour, tour completed, shipment created), a schedule that creates one task per vehicle, carrier or carrier user at every occurrence, or a setting that opens the tasks itself, such as a carrier's task on price change.

string
enum

When the driver app and the carrier portal prompt the created tasks within their stop, copied onto each task at creation: 'on-arrival' once the arrival is recorded, 'before-handling' when the departure begins, before load statuses (barcode scans included) and proofs are captured, 'after-loads' during the departure after the driver marks or scans the loads and before a signature, photo or other proof is captured (the scan proof belongs to the load step and comes first; a proof the driver starts by hand does not bring the task up; the carrier portal prompts it with the other departure placements), 'before-departure' directly before the departure is recorded. Only valid with the 'tour-stop' trigger; rejected with 400 on any other trigger. Omitted, the tasks are prompted on arrival. Changing it does not move tasks that already exist.

Allowed:
filter
object

Optional condition narrowing which trigger occurrences fire this template. A react-querybuilder rule group: { combinator: 'and' | 'or', rules: [...] }, where each rule is { field, operator, value } or a nested group. Rule fields are dotted paths into the trigger's data objects (e.g. 'tour.regionId'). A tenant property is '.properties.

string
required
length between 1 and 200

Name of the created tasks (1-200 characters). May contain Liquid template expressions over the trigger's data objects, resolved when the task is created (e.g. 'Check pallets for {{ tour.name }}').

string
length ≤ 5000

Description of the created tasks. Up to 5000 characters; may contain Liquid template expressions over the trigger's data objects.

form
object

The form the created tasks carry, snapshotted onto each task with its Liquid expressions resolved against the trigger's data objects. Absent for tasks without a form.

assigneeRule
required

Who the created tasks are assigned to.

dueDateRule

How the created tasks' due date is derived. Omit for no due date.

boolean

Whether the created tasks may be skipped. Defaults to false.

boolean

Whether open tasks from this template block the flow they gate (e.g. stop completion in the driver app). Defaults to false.

notifications
object

When the assignees of created tasks are notified. Defaults to notifying on assignment and not sending due reminders; the lead time defaults to 60 minutes.

boolean

When true, completion of the created tasks is accepted only from a signed-in human user; machine actors (API keys, automations, agents) are rejected. Defaults to false.

string

Internal DocumentTemplate id rendered when a task created from this template completes. The document template must exist and may declare only task and the trigger's own data object (tour or shipment); saving is rejected otherwise. The rendered PDF is linked to the task and its referenced entity and announced via the document-link-action-created webhook; completion itself never waits for or fails on the render.

Responses

400

bad request - invalid template definition

401

unauthorized

403

The role of the API key does not allow this action. The key needs a role with the matching permission, for example full access.

409

conflict - the key is already used by another template (internalCode TASK_TEMPLATE_KEY_TAKEN; the body names the holder in holderId and its status in holderStatus when the caller may read that template)

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json