Tasks
Tasks provide a shared backlog for work such as contacting a customer or inspecting equipment.
A task has a title, open or done status, an optional user assignee, and zero or more record
links. A Task may also require a human response through its optional interaction. These Tasks
appear in the same backlog and filters as ordinary work.
Each task has an immutable, server-assigned positive sequence number. REST and MCP responses
expose natural_id as a string, including the definition's current optional natural_id_key
prefix: "INS-123", or "123" without a prefix. Do not add the prefix again on the client.
Numbers are unique within a tenant and shared across all task types, including workflow questions.
They are never reused after deletion; gaps are permitted. The UUID id continues to identify
API resources and relationships. Create and update requests cannot choose or change the number.
Interleaved definitions might display INS-41, VIS-42, INS-43: prefixes share the same
numeric sequence. Changing or clearing a prefix changes subsequent representations without
changing record UUIDs, numbers, versions or timestamps. There are no per-definition sequence
starts or resets. The numeric natural_id filter and numeric sorting use the underlying number.
GraphQL also exposes the formatted string. Task webhook snapshots retain their numeric contract.
Task types
The execution_type discriminator identifies the execution behavior of a task response.
type identifies its concrete definition: a built-in name or a custom definition slug:
| Execution type | Work |
|---|---|
simple | Ordinary work completed by marking the task done |
visit | Work at a required location, exposed through visit.location |
workflow_free_text_question | A workflow question answered with free text |
workflow_single_choice_question | A workflow question answered by selecting one option |
Creation requires one type selector: simple, visit, a custom Task definition slug, or a
concrete Task definition UUID. The server resolves the definition and derives its execution type.
A Visit requires visit.location; a Simple Task rejects a non-null visit. Missing, unknown,
wrong-family or workflow-question selectors return field-level 422 errors at #/type.
Do not send definition_id or execution_type on instance creation.
Workflows create question tasks and their interactions. Response schemas use oneOf so clients
can narrow by execution_type before reading variant-specific fields.
For a visit task, include its location:
{
"type": "visit",
"title": "Inspect the rooftop HVAC unit",
"visit": {"location": {"lat": 48.2082, "lon": 16.3738}}
}
Visit locations use the same fixed value fields as custom-object locations:
lat, lon, street, street_additional, city, region, postal_code, country_code,
address_label, and located_at. Supply both coordinates, or at least street and country_code.
A label alone is not a destination. An address-only visit is valid; map markers and distance estimates
need coordinates. Tourfold does not silently geocode addresses.
Copy the complete fixed value between a record's location attribute and visit.location without
renaming fields. For a tracked source, read the resolved value and remove tracking before copying;
an unresolved source needs a concrete address or coordinates first. Preserve located_at as the
source observation time. A copy is independent of later source movement.
Task PATCH merges nested location fields: omitted fields stay unchanged and explicit null clears
a field. The resulting location must remain complete. For example, changing only lat preserves
lon and the full address. Clear both coordinates together when switching to an address-only value.
Custom-object writes instead replace a supplied location attribute as a whole. To copy over an
existing Task location, also explicitly clear destination fields absent from the source; the
first-party editor does this when submitting its complete location value.
Tour membership is managed through a separate tour task assignment. It does not add tour fields to the task or replace its individual assignee.
CRUD
| Method | Path | Result |
|---|---|---|
POST | /api/v2/tasks | 201, complete task and absolute Location header |
GET | /api/v2/tasks | 200, items and page metadata |
GET | /api/v2/tasks/{task_id} | 200, complete task |
PATCH | /api/v2/tasks/{task_id} | 200, complete updated task |
DELETE | /api/v2/tasks/{task_id} | 204, no body |
Create requires a definition selector in type and a nonblank title of at most 255 characters:
{"type":"simple","title":"Inspect the rooftop HVAC unit"}
The server assigns a UUID and a task number, defaults status to open, and returns linked_records: [].
Ordinary creation does not add an interaction.
An unassigned task omits assignee_user_id. Tasks are scoped to the authenticated tenant.
Use Content-Type: application/merge-patch+json for updates (application/json is also accepted):
{"status":"done","lock_version":0}
Omitted fields remain unchanged. assignee_user_id: null clears the assignee. Null title, status,
record arrays and roles are rejected. linked_records replaces the entire array; [] clears it.
A supplied stale lock_version returns 409; omitted or null skips this precondition. An unchanged
patch preserves the version and produces no update event.
A Task assigned to a finished Tour cannot be updated or deleted: these operations return
409 tours/finished. Deleting an ordinary Task in an editable Tour removes its assignment in the
same transaction; deleting the last Task at an automatic Stop removes that Stop too.
Task and Stop locations are independent snapshots: editing either one does not update the other.
Task definitions
GET /api/v2/definitions/tasks lists the four protected system definitions first: Simple, Visit,
single-choice question and free-text question. Tenant definitions follow, ordered by slug and UUID.
Use page, size (1–100) and optional search; search matches slugs and localized names before
pagination. The internal Task family root is not a selectable definition.
Read with tasks:read or schemas:write; author with schemas:write. Schema administration does
not grant Task record access. A caller with only tasks:write can create a Task with a known
definition ID without gaining definition browsing permission.
Method and path, relative to /api/v2 | Result |
|---|---|
GET /definitions/tasks/{definition_ref} | 200, concrete definition by UUID or slug |
POST /definitions/tasks | 201, complete definition and absolute Location |
PATCH /definitions/tasks/{definition_ref} | 200, merge names, slug, optional prefix or presentation |
PUT /definitions/tasks/{definition_ref} | 200, replace the full authored schema |
POST /definitions/tasks/{definition_ref}/attributes | 201, updated definition; Location identifies that definition |
PATCH /definitions/tasks/{definition_ref}/attributes/{attribute_ref} | 200, merge one authored attribute |
DELETE /definitions/tasks/{definition_ref}/attributes/{attribute_ref} | 200, updated definition |
DELETE /definitions/tasks/{definition_ref} | 204, delete an unused tenant definition |
Both references accept UUIDs or slugs within the routed Task definition family. These operations
are exposed only under /api/v2, with matching task_definitions_* / task_attributes_* MCP tools.
Lists place the four system definitions first, followed by custom definitions ordered by slug, then ID.
Create a Simple-based inspection definition:
{
"slug": "inspection",
"natural_id_key": "INS",
"execution_type": "simple",
"name": {"en": {"singular": "Inspection", "plural": "Inspections"}},
"attributes": [{"slug": "notes", "type": "text", "name": {"en": "Notes"}}]
}
Only system Simple and Visit have is_extendable: true. Question bases and tenant definitions
cannot be extended. execution_type is immutable. Responses use the canonical definition representation, including
resource_type: "task", icon/color, map_marker_fields,
managed_by (tenant, system, or plugin), optional managed_by_plugin, schema_policy, and
one effective attributes list containing native and authored fields. Native fields have
is_system_managed: true; is_readonly independently describes value writability. Structured native
fields use the response-only type json. Use the Task request schemas for their value requirements.
See shared definition metadata. Native fields, the numeric allocator and
display templates cannot be redefined by a custom schema. Relationships may target Objects or the Vehicle family;
Task targets and reverse fields are unsupported.
PUT requires slug, execution_type, name and attributes. Omitted attributes fail validation;
[] deliberately removes authored fields subject to usage protection. Retain field/choice IDs to
preserve identity. PATCH omission preserves values; root name: null and slug: null are rejected.
A null language removes its translation, but at least one localized name must remain. Both writes
accept an optional lock_version; a stale value returns 409 resource-conflict.
natural_id_key is optional on every concrete system/custom definition. A supplied prefix contains
1–16 uppercase letters/digits, starts with a letter and is unique across Object, Vehicle and Task
definitions in the workspace. Blank strings are invalid. PATCH omission preserves the prefix;
{"natural_id_key": null} clears it. PUT omission or null also clears it. GET omits the key when
unconfigured. Prefix and presentation PATCH are allowed on system definitions and definitions already in use.
A definition is in use when a Task (including completed Tasks) or stored configuration references it.
While used, labels, descriptions, presentation order and the optional prefix may change. Optional additions are allowed
only without new indexing or uniqueness obligations; defaults apply to new Tasks without backfilling
existing ones. Structural changes, required additions and deletion return
409 tasks/definition-in-use. Its data.definition_id identifies the blocked definition and
data.usage_examples includes bounded examples of blocking templates and Workflow versions the caller
may read. Retained publications remain blocking after Workflow deletion; retirement/purge is separate
from deleting a Workflow. An empty examples list does not mean the definition is unused. System definitions return 409 definitions/schema-locked on
schema/name writes; their optional prefix is the sole editable metadata field.
Deleting an Object or Vehicle selected by a required Task relationship returns
409 tasks/required-target-in-use, even after Task completion or when other targets remain selected.
Saved Tour-template and retained Workflow inputs also protect required Tag, Skill and tracked-location
references, even before any Task has been created. Optional references deleted later are removed from
editable copies and execution inputs; immutable Workflow publications keep their original values. Optional references are cleared atomically and produce one owning Task or template
revision/update event, including when the same record also has an ordinary Task link.
Definition changes emit task_definition.created, task_definition.updated and
task_definition.deleted. Created and updated events carry the frozen definition representation; updates also include
previous_attributes for changed fields. Deleted events carry the definition ID. No-op edits emit no event.
Definition Settings is available to authorized generic workspaces and is hidden by BW/ÖAMTC. The operational Task editor, Tour-template item editor and typed Workflow authoring support custom definitions. Question Tasks remain Workflow-only.
Custom Task values
Value-validation errors use JSON pointers such as #/data/customer or #/data/rating, matching
the submitted custom attribute slug. Map these errors to the corresponding custom field.
Every Task response includes its immutable definition_id, canonical type (built-in name or
custom slug), and execution_type. Creation selects the definition through type alone; this field
is required. UUID input is normalized to the canonical name in responses. The definition and
execution behavior cannot change after creation. Workflow questions always use their protected
system definition and do not accept custom values. Read and author definitions through the
Task definition endpoints. Definition creation keeps slug, name, and
execution_type; it does not accept an instance type selector. Built-in execution names are
reserved as custom definition slugs.
Filter instances with GET /api/v2/tasks?type=vehicle_inspections (slug, UUID or built-in name).
Use execution_type=visit to select all Visit tasks across definitions. The existing definition_id
filter remains available; if combined with type, both must identify the same definition.
Simple and Visit responses include data, keyed by custom attribute slug. To-many relationships
use nested {items, page} collections with at most 50 compact record views and full totals; later
pages are available at GET /api/v2/tasks/{task_id}/related/{attribute_ref}. System Tasks return
empty data objects. Custom attributes cannot override native fields such as
title or visit.
{
"type": "vehicle_inspections",
"title": "Inspect delivery van",
"visit": {"location": {"lat": 48.2, "lon": 16.3}},
"data": {"serial": "INSPECT-1", "passed": false}
}
Creation applies defaults to omitted custom fields and validates required values. PATCH accepts a
partial data object: omitted attributes stay unchanged, an attribute's explicit null clears it
when allowed, and {} preserves every value. data: null, unknown attributes and writes to
read-only attributes return 422. Completion without a custom value patch does not introduce a
second required-field validation gate.
Native fields and custom values commit atomically. A real change advances lock_version once and
emits one update event, including for a custom-field-only edit. An unchanged patch emits no event.
The same optional version check and finished-Tour restrictions apply.
Relationship previews require target read permission. To load the complete linked collection, use
GET /api/v2/tasks/{task_id}/related/{attribute_ref}?page=0&size=20, where attribute_ref is the
attribute UUID or slug. It returns canonical target records in {items, page}, ordered by UUID,
and requires both Task and target read permission before returning records or totals. Page size is
1–100. The corresponding MCP tool is tasks_related_list.
Human interactions
A workflow approval creates a Task with a single_choice interaction. The interaction has its own
UUID, distinct from the Task ID, and freezes the question and its options when created. Task detail
contains the information needed to render and answer it; no workflow graph request or workflow
authoring permission is needed. Ordinary Task creation and updates cannot inject an interaction.
{
"id": "54b31ce1-7b2d-4423-97e1-72eaf344e251",
"natural_id": "123",
"title": "Approve roadside assistance",
"status": "open",
"lock_version": 0,
"interaction": {
"id": "fbab0b62-fbbb-4731-86cf-dba29b4ab985",
"type": "single_choice",
"status": "pending",
"prompt": "Approve roadside assistance",
"options": [
{"id": "approved", "label": "Approve"},
{"id": "rejected", "label": "Reject"}
],
"created_at": "2026-09-09T10:00:00Z",
"expires_at": "2026-09-16T10:00:00Z"
}
}
Answer with POST /api/v2/tasks/{task_id}/interaction/answer:
{
"type": "single_choice",
"interaction_id": "fbab0b62-fbbb-4731-86cf-dba29b4ab985",
"option_id": "approved",
"comment": "The customer confirmed the details.",
"lock_version": 0
}
The required type is single_choice or free_text and must match the interaction.
The required interaction_id must identify this Task's interaction. A single-choice answer selects
one published option_id; an optional comment must be nonblank and at most 2000 characters.
A type: free_text answer instead requires nonblank text within its declared bound. Do not combine text
with an option or choice comment. Invalid field values and incompatible payloads return 422.
The response is 200 with the updated Task: status done, interaction status answered, and the
accepted response, respondent and time. The answer, Task completion and durable continuation
intent commit atomically. A workflow resumes asynchronously from the committed response.
A repeated identical answer by the same currently authorized human returns the accepted result,
even with the original lock_version. A different answer or respondent, the wrong interaction ID,
a stale supplied version on a pending interaction, expiry, or cancellation returns 409. Expired
and cancelled interactions remain distinguishable from answered interactions; a late response
cannot reopen them.
Answering requires an active human with tasks:write. API-only users and service accounts cannot
answer. Task grants remain tenant-wide: assignment identifies responsibility and does not restrict
answering to that assignee. Reading requires tasks:read.
An authenticated caller who does not qualify as an active human receives 403 with type
https://problems.tourfold.com/tasks/interaction-human-required and data.reason: not_member.
This denial does not include data.required_grants; adding grants cannot make an API-only user
or service account a human respondent. A caller missing tasks:write receives the usual
403 access-denied with data.reason: missing_grant and data.required_grants: ["tasks:write"].
Requests without usable credentials receive the shared 401 authentication-required response
and WWW-Authenticate challenge.
Ordinary PATCH {"status":"done"} cannot supply a required answer, and
PATCH {"status":"open"} cannot reopen it. Both return 409 resource-conflict, including when
the requested status already matches. Deletion also returns 409 after the interaction closes,
so the accepted response remains traceable.
The Task's title and record context cannot be changed through Task CRUD. Reassignment and clearing
assignee_user_id remain available with the usual optional lock_version check. An unchanged
title or record-link array may be retained in the same patch. Automatic record/object deletion
still removes obsolete Task links; the interaction retains its frozen question.
See Workflow approvals for publication, timeout and branch behavior.
Record links and permissions
Reading tasks requires tasks:read; creating, editing or deleting them requires tasks:write.
These grants apply across the tenant, independently of linked-record permissions. Admin and Owner
roles receive both grants by default; other roles can receive them through normal role management.
The same operations are available as tasks_list, tasks_get, tasks_create, tasks_update and
tasks_delete MCP tools. tasks_interaction_answer mirrors the answer action and preserves its
active-human requirement. All are subject to the same Task grants and the workspace's MCP controls.
Each link contains object_id, record_id and an optional role such as customer or equipment.
Roles are lowercase snake_case slugs, at most 64 characters. Multiple records may share a role;
one record may have different roles. Duplicate object/record/role combinations are rejected.
Roles describe the task's links and do not define custom-object relationship attributes.
New links require an existing, readable record. Custom-object links require objects:records:read
and the object type's access policy; vehicle links require vehicle-read permission and must name
the vehicle's concrete definition in object_id. Other read-only built-in system record types
remain unsupported.
Restricted links remain in task responses, retaining IDs and role with is_accessible: false.
They omit display_name; clients should display “You don't have access to this record”. Accessible
links include is_accessible: true and the current display name. A task editor can retain or remove
an existing restricted link and edit its role without gaining access to the record's contents.
Deleting a record removes its links from tasks while preserving the tasks and their other links. Deleting an object or vehicle definition performs the same cleanup for all its records. This cleanup commits atomically with deletion and increments each affected task's version once. Object renames preserve stable links.
Filtering the backlog
Filters combine with AND:
search: case-insensitive literal title substring or an exact number such as123orTask-123; blank is rejected.natural_id: exact positive task number.status:openordone; omitted includes both.definition_id: exact concrete Task definition UUID.type: one concrete definition, selected by built-in name, custom slug, or definition UUID.execution_type: execution behavior, including every custom definition with that behavior.has_visit: true for Visit Tasks and false for other types.assignee_user_id: exact tenant user UUID; omitted includes assigned and unassigned tasks.object_idandrecord_id: supply together using the Object or concrete Vehicle definition UUID and a readable record UUID. Matches ad hoc links (regardless of role) and named custom relationships, including relationships targeting the Vehicle family. The target resource's own read policy applies. A Task matching both kinds of link appears only once in the page and total.
“My tasks” uses the current user's UUID as assignee_user_id. Pagination uses page (default 0)
and size (default 20, maximum 100). sort accepts one field:asc or field:desc pair for
natural_id, created_at, updated_at, title, status or id; a bare field means ascending order.
The default is created_at:desc. An ID tie-breaker
keeps pages stable, and multiple matching links never duplicate tasks or inflate totals.
Lifecycle events
Subscribe to task.created, task.updated and task.deleted through the existing webhook API.
Updates include old values of changed fields in data.previous_attributes. Automatic record-link
cleanup produces a task update too. Webhook references contain only IDs and roles; caller-specific
record names and access flags are not persisted in webhook payloads.
Created and updated payloads include definition_id; Simple and Visit payloads also include frozen
custom data. Custom reference fields contain complete sorted ID arrays, independent of the
writer's read permissions. Named locations retain their stored fixed value or tracking reference.
When custom values change, previous_attributes.data contains the previous custom-value snapshot.
Created and updated Task payloads include interaction metadata when present. Accepting an answer
closes the Task and emits the normal task.updated lifecycle event in the same transaction.
Answer metadata includes the selected option, respondent and answer time. Free-text answers and
comments are available through Task detail and are excluded from webhook payloads, including
previous_attributes.
Native workflows can read Tasks, create visits and copy complete locations to or from custom-object records. See Workflow location copying.