Tasks

Workflow tasks attached to clients, consignments, items, sales, and orders. This resource powers the Tasks tab on entity pages in the backoffice.

Permissions: users without the view task content permission only receive tasks assigned to them that can start — the list and its count are silently restricted. Users with the permission see all tasks.
GET /tasks
Query Parameters
Parameter Type Description Example
filter[reference] integer Tasks attached to a specific node (client, consignment, item, sale, or order) ?filter[reference]=1890911
filter[status] integer Task status: 0 = can start, 1 = can't start, 2 = completed. A computed filter — it expands to conditions on the completed and can_start fields ?filter[status]=0
filter[completed] boolean Filter by the completed flag directly ?filter[completed]=0
filter[can_start] boolean Filter by the can-start flag directly ?filter[can_start]=1
filter[assignee] integer Tasks assigned to a staff user, by uid ?filter[assignee]=161
filter[assignee_uuid] string Tasks assigned to a staff user, by user UUID (resolved via field_uuid) ?filter[assignee_uuid]=2a66b8b2-...
filter[task_category] integer Filter by task type, as a task_types taxonomy term ID ?filter[task_category]=13480
sale_id / sale_uuid integer / string Sale context. When present (and no reference is given) the list is scoped to tasks related to that sale — including tasks on the sale's items, consignments and orders ?sale_uuid=live-68c8...
reference (top level) integer Scope the list to a sale by node ID, same mechanism as the sale context (this is not the same as filter[reference]) ?reference=792
referenced_bundle string Set to client to get only tasks whose reference is a client (client tasks have no sale context) ?referenced_bundle=client
sort string Sort order, prefix with - for descending. Sorting by status orders by completed + can-start ?sort=-created
range / page integer Standard pagination ?range=25&page=0
Example Request
GET /api/v1.0/tasks?filter[reference]=1890911&filter[status]=0&sort=-created
Response
{
  "data": [
    {
      "id": 2153810,
      "label": "1890911 - Client edited alert",
      "published": "1",
      "created": 1785957575000,
      "updated": 1785957575000,
      "author": {
        "id": "161",
        "label": "John Stewart",
        "mail": "john@circuitauction.com",
        "value": "161",
        "uuid": "2a66b8b2-2fae-4179-9989-f8e5b05c98ad"
      },
      "vid": "6472347",
      "task_category": "13480",
      "type": "Client edited alert",
      "completed": false,
      "can_start": true,
      "note": {
        "value": "Change log: ...",
        "summary": null,
        "format": "full_html",
        "safe_value": "
Change log: ...
",
        "safe_summary": ""
      },
      "status": 0,
      "row_class": "can_start",
      "due_date": "1786043976",
      "assignee_uid": "161",
      "assignee": "2a66b8b2-2fae-4179-9989-f8e5b05c98ad",
      "reference": {
        "id": "1890911",
        "uuid": "8f0e3c7a-d7f3-4750-b0b4-489dc9f92c8b",
        "label": "Adam Smith - 7246",
        "type": "client",
        "url_api": "/node/1890911",
        "app_url": "https://backoffice.example.com/app#dashboard/clients/1890911/client"
      },
      "sale": null
    }
  ],
  "count": 1,
  "self": {
    "title": "Self",
    "href": "https://backoffice.example.com/en/api/v1.0/tasks"
  }
}
Response Fields
Field Type Description
id integer Task node ID
label string Task title
published string Published status ("1" = published)
created / updated number Unix timestamps in milliseconds
author object User who created the task (id, label, mail, uuid)
vid string Node revision ID
task_category string Task type as a task_types taxonomy term ID
type string Task type label (e.g. "Describe item", "Under Extension Request", "Client edited alert")
completed boolean Whether the task is done
can_start boolean Whether the task can start. Dependent tasks are created with false and flip to true when the task they depend on completes
note object Task body (Drupal text field object with value / safe_value); may contain HTML, e.g. client-edit change logs
status integer Computed status: 0 = can start, 1 = can't start, 2 = completed
row_class string Computed CSS class for the tasks table: can_start, cant_start or completed
due_date string Due date as a Unix timestamp (seconds)
assignee_uid string Assigned staff user's uid (null when unassigned)
assignee string Assigned staff user's UUID (null when unassigned)
reference object Teaser of the node the task is attached to: id, uuid, label, type (client / consignment / item / sale / order), url_api, app_url. Order teasers add sub_type; sale teasers add sale_status and lots_locked
sale object|null Teaser of the related sale, resolved from the reference (the sale itself, or the item's sale). null for e.g. client tasks
POST /tasks

Create a task. This is what the Add a task form on entity pages submits.

Body Parameters
Parameter Type Description
label string Task title
task_category integer Task type — a task_types taxonomy term ID
reference integer Node ID of the entity the task belongs to (client, consignment, item, sale, order)
assignee_uid integer|null Assign by staff uid; null clears the assignee
assignee_uuid string|null Assign by staff user UUID. Validated: returns 400 if the UUID is unknown or the user is blocked. null clears the assignee
can_start boolean true = "Can start", false = "Can't start"
completed boolean Mark the task as completed
due_date integer Due date as a Unix timestamp (seconds)
note string Task body / note
Example Request
POST /api/v1.0/tasks
Content-Type: application/json

{
  "label": "Photograph item",
  "task_category": 13471,
  "reference": 1890911,
  "assignee_uid": 161,
  "can_start": true,
  "due_date": 1786043976
}
PATCH /tasks/{id}

Update a task — same fields as create. Typical uses: mark a task completed, re-assign it, or change the due date. The backoffice tasks table sends a PATCH when you click Save on a row.

Example Request
PATCH /api/v1.0/tasks/2153810
Content-Type: application/json

{
  "completed": true
}
DELETE /tasks/{id}

Delete a task. Returns 204 No Content on success. The backoffice tasks table sends this when you click Delete on a row.

DELETE /api/v1.0/tasks/2153810
Usage Notes