Complete a human task

POST /v1/human-tasks/{human_task_id}/complete

Property	Value
Operation	`complete_human_task`
Group	Human tasks
Scope	`processes:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Audited `processes.human_task.complete` (mutation)
Released in	1.62.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Completes an open task or one the calling Member claimed, with an outcome and fields validated against the form (HumanTaskIssueCode), and answers it completed (1.62.0); the completion, its Audit event and the instance's task_completed command commit in one transaction, and the node takes the outcome's outlet. An API key or a Member who is not the assignee is forbidden (assignee_required); a task another Member claimed, or one that is not open, human_task_conflict.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the processes:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/human-tasks/htk_.../complete" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "<outcome>" }'

const response = await fetch(`${process.env.VOCAL_API}/v1/human-tasks/htk_.../complete`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "outcome": "<outcome>"
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/human-tasks/htk_.../complete",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "outcome": "<outcome>",
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`human_task_id`	path	HumanTaskId	yes	The id of a human task: `htk_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: HumanTaskCompletionRequest.

Field	Type	Required	Description
`fields`	map of any	no	The form's other fields, each checked against its declared type. Content.
`outcome`	string	yes	A value of the form's `outcome` enum.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	HumanTask
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`process_not_active`, `human_task_conflict`, `idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is HumanTask.

Field	Type	Required	Description
`assignee`	HumanTaskAssignee	yes
`claimed_at`	Timestamp or null	yes
`claimed_by`	MemberId or null	yes
`completion`	HumanTaskCompletion or null	yes
`created_at`	Timestamp	yes
`due_at`	Timestamp or null	yes	When the node takes `timeout` and the task expires; null when unbounded.
`environment`	Environment	yes
`escalate_at`	Timestamp or null	yes	When `human_task.overdue` is written if the task is still open or claimed.
`form`	map of WorkflowField	yes	Typed fields, with an `outcome` enum.
`id`	HumanTaskId	yes
`node_id`	WorkflowNodeId	yes
`object`	`"human_task"`	yes
`organization_id`	OrganizationId	yes
`process_id`	ProcessInstanceId	yes
`status`	HumanTaskStatus	yes
`step_id`	ProcessStepId	yes
`title`	string or null	yes	Rendered from the node's template. Content; null unless the read names `include=content`.
`updated_at`	Timestamp	yes
`workflow_id`	WorkflowId	yes
`workflow_version`	integer	yes