/tasks

Create a one-off work task bound to a platform entity (by ORN) and assigned to an organization, team, or user scope. The referenced entity must exist and belong to your organization; a dead reference is rejected. The optional form definition is snapshotted onto the task, and a completion is validated against that stored snapshot.

Author-facing strings (task name, description, form labels, descriptions, placeholders, display texts, select option labels, step titles, validator messages, and string presets) may contain Liquid template expressions. They are resolved against the referenced entity once, at creation; the stored task never changes when the entity changes afterwards. The available root variable follows the ORN type: tour, shipment, carrier, or draft; a load ORN provides shipment and load; a stop ORN (orn::tour/

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
assignee
required

Who the task is assigned to: an organization, team, or user scope on the operator, carrier, or shipper side.

string
required

ORN of the platform entity this task is about (e.g. orn::tour/QSU1Y). Supported types: tour, shipment, draft, carrier, load, stop. A stop ORN names the stop by its stable id (orn::tour/QSU1Y/stop/

boolean

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

string
required
length between 1 and 200

Short display name of the task (1-200 characters). May use Liquid variables of the referenced entity, and {{ occurrence.date }}, which resolves to the moment the task is created (epoch seconds; e.g. {{ occurrence.date | formatDate: "de" }}).

string
length ≤ 5000

Longer description of what needs to be done. Up to 5000 characters. May use Liquid variables of the referenced entity, and {{ occurrence.date }}, which resolves to the moment the task is created (epoch seconds).

integer
≤ 9007199254740991

Epoch-seconds timestamp the task is due at. Omit for no due date.

boolean

Whether the task may be skipped without being completed. Defaults to false.

boolean

Whether an open instance of this task blocks the flow it gates (e.g. advancing the referenced tour). Defaults to false.

string
enum

When the driver app and the carrier portal prompt the task: 'on-arrival' once the arrival at the stop is recorded, 'before-handling' when the departure begins, before load statuses 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 accepted when referencedEntityOrn names a stop; rejected with 400 otherwise. Defaults to 'on-arrival'.

Allowed:
notifications
object

When the assignee is notified about this task. Defaults to { onAssignment: true, onDueSoon: true, dueSoonLeadMinutes: 60 }.

form
object

The form to fill for completion, snapshotted onto the task at creation. Absent for tasks without a form; completion then takes no form output.

Responses

400

bad request - invalid task config or unknown referenced entity

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.

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