Create Task

POST 
/projects/lists/:listId/tasks

Creates a task in this list as its home list. title and dueDate are required. dueDate accepts ISO 8601 or a Unix timestamp string; responses return ISO 8601. Optional TipTap body — see TipTap documentation. To create a subtask, set parentTaskId. Response is { "task": { … } } without embedded subtasks.

Request

Version stringrequired

API Version

Available optionsv3

listId stringrequired

List 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

titlestringrequired

Task title

dueDatestringrequired

Due date. Required. Accepted input: ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) or a Unix timestamp string. Responses always return ISO 8601.

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 in ISO 8601 format or Unix timestamp

statusstring

Status key from the list effective workflow. Do not send statusGroup — the server derives it from status.

prioritynumber

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

Available options1234

Possible values: >= 1 and <= 4

parentTaskIdstring

Parent task id when creating a subtask. Must not be the task being created.

assigneesstring[]

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

Possible values: <= 1

contactIdstring

Contact to associate with the task

businessIdstring

Business to associate with the task

customFieldsobject

Location-defined custom field values keyed by the task field key (without the task. prefix). Values are validated against the location task schema — use the Custom Fields API (objectKey: "task") to discover available keys and types. Example: definition task.project_phase → { "project_phase": "discovery" }.

Example (auto)

{
  "title": "API test task",
  "dueDate": "2026-09-17T12:00:00.000Z",
  "body": "<p>Call the client about renewal</p>",
  "startDate": "2026-09-17T09:00:00.000Z",
  "status": "to_do",
  "priority": 2,
  "parentTaskId": "6a102435124ecfb348bd5520",
  "assignees": [
    "hxHGVRb1YJUscrCB8eXK"
  ],
  "contactId": "sx6wyHhbFdRXh302Lunr",
  "businessId": "8fK3mN2pQ7rT1vW9xY4z",
  "customFields": {
    "connections": 42,
    "project_phase": "discovery"
  }
}

application/json

Successful response

application/json

Schema

Schema

taskobjectrequired

Created task

Example (auto)

{
  "task": {
    "id": "6a102435124ecfb348bd5509",
    "locationId": "ve9EPM428h8b87FE9C12Kg",
    "objectKey": "task",
    "assignees": [],
    "properties": {
      "title": "API test task",
      "dueDate": "2026-09-17T12:00:00.000Z",
      "status": "to_do",
      "primaryListId": "6a102435124ecfb348bd5507"
    }
  }
}