×

How to Add Tasks in ClickUp

/ ClickUp / By

How to Add Tasks to a List with the ClickUp API

This guide explains how to use the ClickUp REST API to add a task to a list. You will learn the required endpoint, headers, path parameters, and JSON body fields needed to successfully create tasks programmatically.

The instructions here are based strictly on the official reference documentation so you can implement a reliable integration without guesswork.

Overview of the ClickUp Add Task Endpoint

To create a new task on a specific list, the ClickUp API provides a dedicated endpoint under the /task resource. This endpoint is designed to accept a JSON payload describing the task and returns a JSON response containing the created task object.

The endpoint is available in versions:

  • Public API v2
  • Public API v3

If you do not explicitly specify an API version in your request, version 2 will be used by default.

ClickUp Endpoint and HTTP Method

The endpoint for adding a task to a list is:

POST /api/v2/list/{list_id}/task

This is an authenticated POST request. You send the task data in the request body as JSON and include your API token in the headers.

Base URL for ClickUp API

The base URL for all public endpoints is typically:

https://api.clickup.com

Putting it together, a full request URL will look like:

https://api.clickup.com/api/v2/list/{list_id}/task

Replace {list_id} with the numeric identifier of the list where the task should be created.

Authentication and Required Headers in ClickUp

Every request to this endpoint must include specific headers so that ClickUp can authenticate and correctly interpret your data.

Mandatory Headers

  • Authorization: Your personal token or app token as provided in your ClickUp account.
  • Content-Type: Must be application/json because the body uses JSON format.

An example of the minimum required headers:

Authorization: <your-clickup-api-token>
Content-Type: application/json

Path Parameters for the ClickUp Task Endpoint

The endpoint requires one path parameter that must be supplied in the URL.

  • list_id (required): The unique identifier of the list where the new task will be created. It should be placed directly in the URL path.

Example URL with a concrete list identifier:

https://api.clickup.com/api/v2/list/123456/task

Request Body: Task Fields in ClickUp

The request body is a JSON object that defines the properties of the new task. Several fields are available to control names, dates, assignees, and custom data.

Core Body Properties

  • name (string, required): The title of the task that will appear in the ClickUp interface.
  • description (string, optional): Detailed information about the task. Can include formatted text or links as supported by the platform.
  • assignees (array of integers, optional): A list of user IDs that should be assigned to the task.
  • tags (array of strings, optional): Labels or keywords to categorize the task.
  • status (string, optional): The workflow status, for example to do, in progress, or another status configured on the list.
  • priority (integer, optional): Numeric priority level, as defined in your workspace configuration.
  • due_date (integer, optional): The due date as a Unix timestamp in milliseconds.
  • start_date (integer, optional): The start date as a Unix timestamp in milliseconds.
  • time_estimate (integer, optional): Estimated time to complete the task, usually in milliseconds.
  • time_spent (integer, optional): Time already spent on the task, in milliseconds.
  • notify_all (boolean, optional): Whether to trigger notifications to all watchers when the task is created.
  • parent (string, optional): If provided, the ID of the parent task to create a subtask relationship.
  • custom_fields (array, optional): Used to set values for custom fields on the task. Each item represents a field-value pair.

Custom Fields in ClickUp Task Creation

Custom fields allow you to store additional structured data on tasks. In the JSON body, each custom field object typically includes:

  • id: The unique identifier of the custom field.
  • value: The value to assign. The data type depends on the field configuration (text, number, dropdown, etc.).

You must already know the id of each custom field you want to populate. These can be retrieved through other endpoints in the ClickUp API.

Step-by-Step: How to Call the ClickUp Add Task Endpoint

The process to add a task using the API can be broken down into clear steps.

1. Gather Required Information

  • Identify your ClickUp list_id.
  • Obtain a valid API token from your ClickUp account.
  • Determine the task name and any other fields you plan to include.

2. Build the Request URL

  1. Start with the base: https://api.clickup.com.
  2. Append the resource path: /api/v2/list/{list_id}/task.
  3. Replace {list_id} with the numeric identifier for your list.

3. Set the Headers

  1. Add Authorization with your API token.
  2. Set Content-Type to application/json.

4. Create the JSON Body

Include at least the required name field, then add optional fields as needed. A minimal example:

{
  "name": "New API task",
  "description": "Created via ClickUp public API.",
  "assignees": [123456],
  "status": "to do"
}

5. Send the Request

Use your preferred HTTP client or library, such as curl, Postman, or a language-specific SDK, to send the POST request to the ClickUp endpoint with the headers and body you defined.

6. Handle the Response

If the request is successful, the API returns a JSON object that represents the newly created task, including its unique id and all stored fields. Store this identifier if you plan to update or query the task later.

Example Request to the ClickUp Task API

Below is a conceptual example using curl. Adjust the values to match your environment, token, and list.

curl -X POST 
  "https://api.clickup.com/api/v2/list/123456/task" 
  -H "Authorization: <your-clickup-api-token>" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "API-created task",
    "description": "This task was created with the ClickUp REST API.",
    "assignees": [123456],
    "tags": ["api", "example"],
    "status": "to do",
    "priority": 3
  }'

This example shows how straightforward it is to integrate task creation into your own systems.

Troubleshooting Your ClickUp Task Requests

If your request fails, check the following areas:

  • Authorization header: Confirm your token is correct, active, and included.
  • Content-Type: Ensure it is set to application/json.
  • list_id: Verify that the list exists and your token has access.
  • JSON body: Validate the JSON structure and required fields, especially name.

Review the HTTP status code and error message in the response for more detailed diagnostics.

Official ClickUp Reference and Further Help

You can review every parameter and field directly in the official reference here: ClickUp add task to list API. That documentation is the authoritative source for up-to-date details, limits, and any new properties introduced to the endpoint.

For broader workflow automation, API strategy, and integration design around this platform and others, you can also explore expert resources at Consultevo.

By following the steps above, you can reliably create tasks via the ClickUp API and embed task management into your own applications, scripts, and services.

Need Help With ClickUp?

If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.

Get Help

“`

Verified by MonsterInsights