×

Create Tasks with ClickUp API

/ ClickUp / By

How to Create Tasks with the ClickUp API

The ClickUp API lets you create tasks programmatically so your apps and workflows can send work directly into ClickUp spaces, folders, and lists. This guide explains each field in the Create Task endpoint and shows you how to build valid requests that work reliably in production.

Overview of the ClickUp Create Task Endpoint

The Create Task endpoint allows you to add a new task to a specific list in your workspace. You send an HTTP POST request with a JSON body that contains task details such as name, description, assignees, and due dates.

The endpoint URL format is:

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

In this URL, {list_id} is the ID of the list where you want the task to be created.

Authentication Requirements for ClickUp

Before you can call the Create Task endpoint, you must authenticate with the platform.

  • Use a valid API token in the Authorization header.
  • The token must have access to the workspace and list you are targeting.
  • All requests must be sent over HTTPS.

Example header:

Authorization: <your_clickup_api_token>

Required Fields When Creating a ClickUp Task

Most properties in the Create Task body are optional, but one field is critical for every request.

  • name (string, required) – The title of the task you want to create.

Without the name field, the request will fail. Always provide a clear and concise task title so it is easy to find and manage inside your workspace.

Optional Task Fields in the ClickUp API

The ClickUp Create Task endpoint supports many optional fields so you can shape tasks to match your process. Below are the main options you can include in the JSON body.

Basic Content and Status Fields

  • description (string) – A detailed description of the task.
  • markdown_description (string) – Description in Markdown format if you prefer structured content.
  • status (string) – Status name to apply to the new task (must exist on the list).
  • priority (integer) – Priority level, where valid values correspond to your workspace configuration.
  • archived (boolean) – Set to true to create the task in an archived state.

Parent, Relationships, and Templates in ClickUp

  • parent (string) – ID of the parent task if you are creating a subtask.
  • links_to (string) – Task ID that this new task should link to.
  • template_id (string) – ID of a task template to apply during creation.
  • custom_task_ids (boolean) – Set to true if your workspace uses custom task IDs.
  • team_id (integer) – Workspace (team) ID, required when custom_task_ids is true.

Assignees and Collaboration in ClickUp

  • assignees (array of integers) – User IDs to assign to the task.
  • watchers (array of integers) – User IDs who will watch the task.
  • check_required_custom_fields (boolean) – When true, the task cannot be created if any required custom fields are missing.

Time Tracking and Dates

  • time_estimate (integer) – Estimated time in milliseconds.
  • start_date (string) – Unix time in milliseconds for the task start date.
  • start_date_time (boolean) – Set to true if the start date includes a time of day.
  • due_date (string) – Unix time in milliseconds for the due date.
  • due_date_time (boolean) – Set to true if the due date includes a time of day.
  • time_original_estimate (integer) – Original time estimate in milliseconds, used when tracking changes.

ClickUp Custom Fields and Tags

  • custom_fields (array of objects) – Custom field values to apply to the task, each object including field IDs and values that match your configuration.
  • tags (array of strings) – Tags to label and group the task.

Additional Configuration Options

  • notify_all (boolean) – If true, sends notifications to all watchers of the task.
  • list_assigner (boolean) – When supported, indicates list-based assignment behavior.
  • list_creator (boolean) – When supported, indicates list-based creation behavior.

Step-by-Step: Create a Task with the ClickUp API

Follow these steps to send a valid Create Task request.

1. Find the List ID in ClickUp

  1. Open the workspace where you want to create the task.
  2. Locate the target list in your hierarchy.
  3. Use the web app or another API call to obtain the list ID.

2. Build the Request Body

Create a JSON object with at least the required name field and any optional fields you want to use.

{
  "name": "New API Task",
  "description": "Task created via the ClickUp API.",
  "status": "to do",
  "assignees": [123456],
  "tags": ["api", "example"],
  "priority": 3,
  "due_date": 1735689600000,
  "due_date_time": true,
  "time_estimate": 3600000
}

3. Send the HTTP Request

  1. Set the method to POST.
  2. Use the endpoint URL with your list ID: /list/{list_id}/task.
  3. Add the Authorization header with your token.
  4. Set Content-Type: application/json.
  5. Include your JSON body in the request payload.

4. Handle the Response from ClickUp

If the request succeeds, the response body will contain the created task object with its ID and all stored properties.

Typical actions after a success response include:

  • Store the returned task ID in your app database.
  • Log the creation event for auditing.
  • Display confirmation to the user.

If the request fails, review the error message and confirm that:

  • Your token is valid and has sufficient permissions.
  • The list ID exists and belongs to the workspace for that token.
  • All required fields, including custom fields marked as required, are provided.

Best Practices for Using the ClickUp Create Task API

To keep your integration stable and maintainable, consider the following recommendations.

  • Validate all user input before sending it to the API.
  • Use check_required_custom_fields when your processes depend on full data.
  • Convert human-readable dates into Unix time in milliseconds consistently.
  • Limit the number of fields you send to only what is needed to keep payloads compact.
  • Monitor API responses and log errors for debugging and analysis.

Where to Learn More About ClickUp API Details

For the full reference, including every field, type, and example, review the official Create Task documentation at the ClickUp API reference. It is updated by the platform team and should be your primary technical source.

If you need strategic help designing workflows, automations, or integrations around this API, you can also visit Consultevo for professional consulting and implementation support.

By following the structure, fields, and practices described in this guide, you can reliably create tasks via the ClickUp API and integrate work creation directly into your applications, forms, and automation pipelines.

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