---
title: "Create Task"
method: POST
path: "/v2/list/{list_id}/task"
tags: ["Tasks"]
---

# Create Task

`POST /v2/list/{list_id}/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](https://developer.clickup.com/reference/getaccessiblecustomfields) and each field's `applied_objects` to determine applicability before creating the task.

## Path parameters

- `list_id` number, required

## Request body

- object
  - `name` string, required
  - `description` string
  - `assignees` integer[]
  - `archived` boolean
  - `group_assignees` string[] — Assign multiple user groups to the task.
  - `tags` string[]
  - `status` string
  - `priority` integer, nullable
  - `due_date` integer
  - `due_date_time` boolean
  - `time_estimate` integer
  - `start_date` integer
  - `start_date_time` boolean
  - `points` number — Add Sprint Points to the task.
  - `notify_all` boolean — 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.
  - `parent` string, 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_content` string — Markdown formatted description for the task. If both `markdown_content` and `description` are provided, `markdown_content` will be used instead of `description`.
  - `links_to` string, nullable — Include a task ID to create a linked dependency with your new task.
  - `check_required_custom_fields` boolean — 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_fields` union[] — You can include one or more Custom Fields to set them when creating a new task.\ \ Custom Fields that use object and array type values are nullable by sending `"value": null`.\ \ Only Custom Fields applicable to the task's `custom_item_id` are saved. Values for fields scoped to other custom task types are ignored. Use a [Get Custom Fields](https://developer.clickup.com/reference/getaccessiblecustomfields) endpoint and check each field's `applied_objects` to see which fields apply to which task types before creating the task.
    - union
      - object — The `value` must be a string with a valid URL.
        - `id` string, required
        - `value` string, nullable, required
      - object — Enter the universal unique identifier (UUID) of the dropdown menu option you want to set. You can find the UUIDs available for each Dropdown Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields) New Dropdown Custom Field options cannot be created from this request.
        - `id` string, required
        - `value` string, nullable, required
      - object — The `value` must be a string with a valid email address.
        - `id` string, required
        - `value` string, nullable, required
      - object — The `value` must be a string with a valid country code.
        - `id` string, required
        - `value` string, nullable, required
      - object — The `value` must be Unix time in milliseconds. To display the time in a Date Custom Field in ClickUp, you must include `time: true` in the `value_options` property.
        - `id` string, required
        - `value` integer, nullable, required
        - `value_options` object
          - `time` boolean
      - object — Enter a string of text.
        - `id` string, required
        - `value` string, nullable, required
      - object — Enter a number.
        - `id` string, required
        - `value` number, nullable, required
      - object — You can set an amount, but not the currency of a Money Custom Field via the API. You can check the currency of a Money Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields)
        - `id` string, required
        - `value` number, nullable, required
      - object — Enter an array of task ids in the `add` property to add them to a Task Relationship Custom Field. Enter them into the `rem` property to remove tasks from the Relationship. Task Relationship Custom Fields are nullable: `"value": null`.
        - `id` string, required
        - `value` object, required
          - `add` string[]
          - `rem` string[]
      - object — Enter an array of user ids or a Team id in the `add` property to add them to a People Custom Field. Enter them into the `rem` property to remove users from a People Custom Field. You can get a list of people in the Workspace using [Get Authorized Teams (Workspaces).](https://developer.clickup.com/reference/getauthorizedteams) People Custom Fields are nullable: `"value": null`.
        - `id` string, required
        - `value` object, required
          - `add` number[]
          - `rem` number[]
      - object — Enter an integer that is greater than or equal to zero and where the `count` property is greater than or equal to the `value`. You can find the `count` property for each Emoji (Rating) Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields)
        - `id` string, required
        - `value` integer, nullable, required
      - object — Enter a number between the `start` and `end` values of each Manual Progress Custom Field. For example, for a field with `start: 10` and `end: 30`, sending `current: 20` will be displayed as 50% complete in ClickUp. You can find the `start` and `end` values for each Manual Progress Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields) Manual Progress Custom Fields are nullable: `"value": null`.
        - `id` string, required
        - `value` object, required
          - `current` number, required
      - object — Enter an array of the universal unique identifiers (UUIDs) of the labels you want to apply. You can find the UUIDs available for each Label Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields) Label Custom Fields are nullable: `"value": null`.
        - `id` string, required
        - `value` string[], required
      - object — Include the latitude, longitude, and formatted address as defined in the [Google Maps Geocoding API.](https://developers.google.com/maps/documentation/geocoding/overview)
        - `id` string, required
        - `value` object, required
          - `location` object
            - `lat` number
            - `lng` number
          - `formatted_address` string
      - object — Set a button Custom Field to `true` to "click" it. This will trigger the button's action as if it was clicked in the UI.
        - `id` string, required
        - `value` boolean, nullable, required
  - `custom_item_id` number — 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](https://developer.clickup.com/reference/getcustomitems).

## Response `200`

- object
  - `id` string
  - `custom_id` string, nullable
  - `custom_item_id` number, 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](https://developer.clickup.com/reference/getcustomitems).
  - `name` string
  - `text_content` string
  - `description` string
  - `markdown_description` string
  - `status` Status — unresolved $ref
  - `orderindex` string
  - `date_created` string
  - `date_updated` string
  - `date_closed` string, nullable
  - `date_done` string, nullable
  - `archived` boolean
  - `creator` Creator — unresolved $ref
  - `assignees` string[]
  - `group_assignees` string[]
  - `watchers` string[]
  - `checklists` string[]
  - `tags` string[]
  - `parent` string, nullable
  - `top_level_parent` string, nullable
  - `priority` Priority — unresolved $ref
  - `due_date` string, nullable
  - `start_date` string, nullable
  - `points` number, nullable
  - `time_estimate` string, nullable
  - `time_spent` number
  - `custom_fields` Items[] — unresolved $ref
  - `dependencies` string[]
  - `linked_tasks` string[]
  - `locations` Items[] — Array of Lists where the task has been added. — unresolved $ref
  - `team_id` string
  - `url` string
  - `sharing` object
    - `public` boolean
    - `public_share_expires_on` string, nullable
    - `public_fields` string[]
    - `token` string, nullable
    - `seo_optimized` boolean
  - `permission_level` string
  - `list` List — unresolved $ref
  - `project` Folder — unresolved $ref
  - `folder` Folder — unresolved $ref
  - `space` Space — unresolved $ref

---

[API](https://skmtc.dev/clickup/apis/clickup-api-v2-reference.md) · [All operations](https://skmtc.dev/clickup/apis/clickup-api-v2-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/clickup/clickup-api-v2-reference/revisions/72216f55b952/schema)