/tasktemplates

post

https://api.dev.orbit.do/v5/tasktemplates

Create a task template: a configuration that creates tasks automatically when a platform trigger fires. The trigger names a business fact (tour created, tour assigned, stop arrived, tour completed, shipment created); 'stop-arrived' covers driver arrival steps and integrated-carrier arrival reports alike. Each trigger provides data objects (tour; additionally stop for stop arrival; 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').

Liquid syntax, unknown root variables, and filter fields/operators are validated at save time; 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/

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

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

name

string

required

length between 1 and 200

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

key

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.

status

string

enum

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

Allowed:

trigger

required

When this template is considered: a curated platform trigger naming a business fact (tour created, tour assigned, stop arrived, tour completed, shipment created).

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'). Omit to fire on every occurrence. A filter that fails to evaluate creates no task.

taskName

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 }}').

taskDescription

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.

isSkippable

boolean

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

isBlocking

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

Per-template notification behavior for created tasks. Defaults to notifying on assignment and not sending due-soon reminders.

requiresHuman

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.

documentTemplateId

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

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

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The created task template