Update A Task Or Subtask

PATCH 
/projects/tasks/:taskId

Updates a task or subtask by id (title, TipTap body, status, dates, assignees, priority, parentTaskId, custom fields, etc.). Response is { "task": { … } } without embedded subtasks.

Request

Version stringrequired

API Version

Available optionsv3

taskId stringrequired

Task id

locationId string

Location id. Required for channel: APP. Ignored for OAuth/PIT — those use the location on the auth token. Do not send in path, body, or headers.

application/json

application/json

Body

Bodyrequired

titlestring

Task title

dueDatestring

Due date in ISO 8601 format or Unix timestamp

bodystring

Task body as TipTap HTML or TipTap JSON string (same field as comment body). See TipTap documentation. Sanitised server-side to a published HTML allowlist (basic formatting + links). Max 32,000 characters.

Possible values: <= 32000 characters

startDatestring

Start date

statusstring

Status key from the list effective workflow. Do not send statusGroup.

prioritynumber

Priority level. Allowed: 1 (highest), 2, 3, 4 (lowest).

Available options1234

Possible values: >= 1 and <= 4

parentTaskIdstring

Parent task id when this task should become a subtask. Do not send this task’s own id.

assigneesstring[]

Assignee user IDs. Only one assignee is supported today — send a single-element array (extra ids are rejected with 422).

Possible values: <= 1

contactIdstring

Linked contact id

businessIdstring

Linked business id

customFieldsobject

Location-defined custom field values keyed by the task field key (without the task. prefix). Discover keys via the Custom Fields API (objectKey: "task"). Example: definition task.project_phase → { "project_phase": "discovery" }.

Example (auto)

{
  "title": "Updated title",
  "dueDate": "2026-09-20T12:00:00.000Z",
  "body": "<p>Updated notes</p>",
  "startDate": "2026-09-20T10:00:00.000Z",
  "status": "to_do",
  "priority": 2,
  "parentTaskId": "6a102435124ecfb348bd5520",
  "assignees": [
    "user_1"
  ],
  "contactId": "sx6wyHhbFdRXh302Lunr",
  "businessId": "8fK3mN2pQ7rT1vW9xY4z",
  "customFields": {
    "connections": 42,
    "project_phase": "discovery"
  }
}

application/json

Successful response

application/json

Schema

Schema

taskobjectrequired

Task

Example (auto)

{
  "task": {
    "id": "6a102435124ecfb348bd5509",
    "locationId": "ve9EPM428h8b87FE9C12Kg",
    "objectKey": "task",
    "assignees": [
      "user_1"
    ],
    "properties": {
      "title": "Follow up with client",
      "status": "to_do",
      "dueDate": "2026-09-20T17:00:00.000Z",
      "priority": 2,
      "primaryListId": "6a102435124ecfb348bd5507"
    }
  }
}