Skip to content
HeyX API

Attach External Advanced Task

Required scope: advanced_task:attach

Attach a live advanced-task definition to a parent problem or work order, creating a new instance. Only external-type definitions can be attached through the public API. Supply exactly one of problemId or workOrderId; the parent must be visible to the API key creator and must not be in a terminal state (a completed or cancelled work order, or a resolved, closed, or archived problem).

Generated Reference
POST /public-api/publicapi.v1.AdvancedTaskService/AttachAdvancedTask

Attaches an external-type advanced-task definition to a problem or work order, creating a new pending instance. Exactly one parent must be given. Rejected when the parent is already terminal. Not idempotent.

Request AttachAdvancedTaskRequest
Response AttachAdvancedTaskResponse

AttachAdvancedTaskRequest

Field Type Description
advanced_task_id string External-type advanced-task definition to instantiate. Non-external definitions are rejected because they cannot be rendered publicly.
problem_id optional string Parent problem to attach to. Set exactly one of problem_id or work_order_id.
work_order_id optional string Parent work order to attach to. Set exactly one of problem_id or work_order_id.

AttachAdvancedTaskResponse

Field Type Description
instance AdvancedTaskInstance The newly created advanced-task instance.

Related Types

AdvancedTaskInstance

Field Type
id string
advanced_task_id optional string
name string
description string
external_key string
external_description string
status AdvancedTaskStatus
created_at int64
updated_at int64
completed_at optional int64
customer_id string
problem_id optional string
work_order_id optional string
parent_title string
customer_title string
customer_reference string
completion_evidence google.protobuf.Struct

Request

Section titled “Request”
{
  "advancedTaskId": "<advanced-task-definition-id>",
  "workOrderId": "<work-order-id>"
}

Response

Section titled “Response”
{
  "instance": {
    "id": "<instance-id>",
    "advancedTaskId": "<advanced-task-definition-id>",
    "completed": false
  }
}

The response contains the new instance in the same shape returned by the List External Tasks endpoint. This is not idempotent; do not blindly retry a timed-out call, as it may still have created the instance.

HeyX API