Sign in
Tasks

Create Task

Create a new task.

Custom Field values in the request body are only saved when the field is applicable to the task's custom_item_id. Use Get Custom Fields and each field's applied_objects to determine applicability before creating the task.

post/v2/list/{list_id}/task

Path parameters

list_idnumber required
Example:123

Request body

namestring required
descriptionstring
assigneesinteger[]
archivedboolean
group_assigneesstring[]

Assign multiple user groups to the task.

tagsstring[]
statusstring
priorityinteger nullable
due_dateinteger
due_date_timeboolean
time_estimateinteger
start_dateinteger
start_date_timeboolean
pointsnumber

Add Sprint Points to the task.

notify_allboolean

If notify_all is true, the creator of the task will also be notified. Other assignees and watchers are always notified regardless of this setting.

parentstring nullable

You can create a subtask by including an existing task ID.

The parent task ID you include can be a subtask, but must be in the same List specified in the path parameter.

markdown_contentstring

Markdown formatted description for the task. If both markdown_content and description are provided, markdown_content will be used instead of description.

links_tostring nullable

Include a task ID to create a linked dependency with your new task.

check_required_custom_fieldsboolean

When creating a task via API any required Custom Fields are ignored by default (false).

You can enforce required Custom Fields by including check_required_custom_fields: true.

custom_item_idnumber

The custom task type ID for this task. A value of 0 (default) creates a standard task type "Task".

This determines which Custom Fields from the custom_fields array are accepted.

To get a list of available custom task type IDs for your Workspace, use the Get Custom Task Types endpoint.

Example request

{
  "name": "New Task Name",
  "description": "New Task Description",
  "assignees": [
    183
  ],
  "archived": false,
  "group_assignees": [
    "dd01f92f-48ca-446d-88a1-0beb0e8f5f14"
  ],
  "tags": [
    "tag name 1"
  ],
  "status": "Open",
  "priority": 3,
  "due_date": 1508369194377,
  "due_date_time": false,
  "time_estimate": 8640000,
  "start_date": 1567780450202,
  "start_date_time": false,
  "points": 3,
  "notify_all": true,
  "parent": null,
  "links_to": null,
  "check_required_custom_fields": true,
  "custom_fields": [
    {
      "id": "0a52c486-5f05-403b-b4fd-c512ff05131c",
      "value": 23
    },
    {
      "id": "03efda77-c7a0-42d3-8afd-fd546353c2f5",
      "value": "Text field input"
    }
  ]
}

Response

idstring
custom_idstring nullable
custom_item_idnumber nullable

The custom task type ID for this task. A value of 0 (default) creates a standard task type "Task".

To get a list of available custom task type IDs for your Workspace, use the Get Custom Task Types endpoint.

namestring
text_contentstring
descriptionstring
markdown_descriptionstring
statusStatus — unresolved $ref
orderindexstring
date_createdstring
date_updatedstring
date_closedstring nullable
date_donestring nullable
archivedboolean
creatorCreator — unresolved $ref
assigneesstring[]
group_assigneesstring[]
watchersstring[]
checklistsstring[]
tagsstring[]
parentstring nullable
top_level_parentstring nullable
priorityPriority — unresolved $ref
due_datestring nullable
start_datestring nullable
pointsnumber nullable
time_estimatestring nullable
time_spentnumber
custom_fieldsItems[] — unresolved $ref
dependenciesstring[]
linked_tasksstring[]
locationsItems[] — unresolved $ref

Array of Lists where the task has been added.

team_idstring
urlstring
permission_levelstring
listList — unresolved $ref
projectFolder — unresolved $ref
folderFolder — unresolved $ref
spaceSpace — unresolved $ref

Example response

{
  "id": "9hx",
  "custom_id": null,
  "custom_item_id": 0,
  "name": "New Task Name",
  "text_content": "New Task Content",
  "description": "New Task Content",
  "markdown_description": "New Task Content",
  "status": {
    "id": "p7002367_HxJmgqni",
    "status": "to do",
    "color": "#f8ae00",
    "orderindex": 0,
    "type": "open"
  },
  "orderindex": "1.00000000000000000000000000000000",
  "date_created": "1567780450202",
  "date_updated": "1567780450202",
  "date_closed": null,
  "date_done": null,
  "archived": false,
  "creator": {
    "id": 183,
    "username": "Alex Johnson",
    "color": "#827718",
    "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
  },
  "assignees": [],
  "group_assignees": [],
  "watchers": [],
  "checklists": [],
  "tags": [],
  "parent": null,
  "top_level_parent": null,
  "priority": {
    "color": "#f8ae00",
    "id": "3",
    "orderindex": "3",
    "priority": "normal"
  },
  "due_date": "1508369194377",
  "start_date": null,
  "points": 3,
  "time_estimate": "8640000",
  "time_spent": 0,
  "custom_fields": [
    {
      "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b",
      "name": "Sprint Goal",
      "type": "short_text",
      "type_config": {},
      "date_created": "1621915186877",
      "hide_from_guests": false,
      "value": "Fix critical auth issues",
      "value_richtext": "",
      "required": false
    },
    {
      "id": "1f3cc395-3448-4264-bedd-590a3b3fa178",
      "name": "Story Points",
      "type": "number",
      "type_config": {},
      "date_created": "1627004071219",
      "hide_from_guests": false,
      "required": false
    },
    {
      "id": "f4d2a20d-6759-4420-b897-222dbe2587d4",
      "name": "Assigned Reviewer",
      "type": "users",
      "type_config": {
        "include_guests": false,
        "include_team_members": true,
        "single_user": false
      },
      "date_created": "1618440378816",
      "hide_from_guests": false,
      "required": false
    },
    {
      "id": "b2e4be70-c4d3-4726-985b-46ac25375b28",
      "name": "Marketing Requirements",
      "type": "drop_down",
      "type_config": {
        "sorting": "manual",
        "new_drop_down": true,
        "options": [
          {
            "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a",
            "name": "No Marketing Needed",
            "color": "#b5bcc2",
            "orderindex": 0
          },
          {
            "id": "97704092-e5aa-4005-a87f-677b764d2e4c",
            "name": "Internal Announcement",
            "color": "#02BCD4",
            "orderindex": 1
          },
          {
            "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7",
            "name": "Release Notes Only",
            "color": "#7b68ee",
            "orderindex": 2
          },
          {
            "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d",
            "name": "Social Media Post",
            "color": "#2ecd6f",
            "orderindex": 3
          },
          {
            "id": "87b3c808-a335-4284-a671-e2f9bce66713",
            "name": "Blog Post",
            "color": "#f9ae27",
            "orderindex": 4
          },
          {
            "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6",
            "name": "Dedicated Campaign with Press",
            "color": "#e50000",
            "orderindex": 5
          }
        ]
      },
      "date_created": "1762838079415",
      "hide_from_guests": false,
      "required": false
    }
  ],
  "dependencies": [],
  "linked_tasks": [],
  "locations": [],
  "team_id": "7002367",
  "url": "https://app.clickup.com/t/9hx",
  "sharing": {
    "public": false,
    "public_share_expires_on": null,
    "public_fields": [
      "assignees",
      "priority",
      "due_date",
      "content",
      "comments",
      "attachments",
      "customFields",
      "subtasks",
      "tags",
      "checklists",
      "coverimage"
    ],
    "token": null,
    "seo_optimized": false
  },
  "permission_level": "create",
  "list": {
    "id": "15505202",
    "name": "Sprint Backlog",
    "access": true
  },
  "project": {
    "id": "6992470",
    "name": "Mobile Squad",
    "hidden": false,
    "access": true
  },
  "folder": {
    "id": "6992470",
    "name": "Mobile Squad",
    "hidden": false,
    "access": true
  },
  "space": {
    "id": "7002367"
  }
}

Changes