How to Create a List with the ClickUp API

This guide explains step by step how to create a list in ClickUp using the public REST API, based exclusively on the official developer reference. You will learn the required URL, headers, request body, and how to interpret the response when the list is created inside a folder.

Overview of the ClickUp Create List Endpoint

The create list endpoint lets you create a new list in a specific folder within a workspace. You call the ClickUp API with a POST request and provide the folder ID, list details, and your API token.

The reference endpoint documented is:

• Method: POST
• Path: /api/v2/folder/{folder_id}/list

This creates a list that belongs to the folder identified by folder_id. The folder and list must be in a space that belongs to your ClickUp workspace.

Prerequisites for Using the ClickUp API

Before you call the endpoint, make sure you have the following:

• A valid ClickUp API token.
• The folder_id where the list will be created.
• Access to send HTTPS POST requests (for example with curl or a REST client).

You can manage your API tokens in your ClickUp account settings. The token must have permission to access the workspace and folder where you want to create the list.

ClickUp Create List Endpoint URL Structure

The URL template for creating a list in a folder is:

https://api.clickup.com/api/v2/folder/{folder_id}/list

Replace {folder_id} with the numeric identifier of the folder. For example:

https://api.clickup.com/api/v2/folder/123/list

This URL tells ClickUp that the new list should be created inside folder 123.

Required Headers for the ClickUp Request

Your POST request must include authorization and content type headers so ClickUp can authenticate and parse the body.

• Authorization: your API token as a string.
• Content-Type: application/json.

In curl, the basic structure looks like this:

curl --request POST \
  --url https://api.clickup.com/api/v2/folder/<folder_id>/list \
  --header 'Authorization: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

Defining the Request Body for ClickUp

The request body is a JSON object that contains the properties of the list you want to create. According to the official reference, several fields are supported, but only name is required.

Required Fields in the ClickUp List Body

• name (string, required): The name of the list you are creating.

Without a name value, ClickUp will not create the list and the request will fail with a validation error.

Optional Fields for the ClickUp List

You can provide optional properties to customize the list:

• content (string): Description or details for the list.
• due_date (integer): Due date for the list in milliseconds.
• due_date_time (boolean): Whether time is included with the due date.
• priority (integer): Priority level, using the numeric priority values supported by ClickUp.
• assignee (integer): User ID of the assignee for the list.
• status (string): Status value for the list, based on statuses defined in the space.

You do not have to include all optional properties. Any field you omit will be handled using system defaults or remain unset.

Step-by-Step: Create a List in ClickUp

Use the following step-by-step process when calling the endpoint.

Step 1: Gather ClickUp Workspace Details

1. Log in to your ClickUp workspace.
2. Identify the folder where you want to create the list and obtain its folder_id.
3. Confirm that your API token has access to this folder and space.

Step 2: Build the ClickUp API Request

1. Start with the POST URL:
   https://api.clickup.com/api/v2/folder/{folder_id}/list
2. Set the Authorization header to your API token.
3. Set Content-Type: application/json.
4. Create a JSON body with at least a name.

Example body:

{
  "name": "Product Roadmap",
  "content": "Q3 product initiatives",
  "due_date": 1719964800000,
  "due_date_time": true,
  "priority": 2,
  "assignee": 123456,
  "status": "to do"
}

Step 3: Send the ClickUp Request

Use your preferred tool to send the POST request.

curl --request POST \
  --url https://api.clickup.com/api/v2/folder/123/list \
  --header 'Authorization: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Product Roadmap",
    "content": "Q3 product initiatives",
    "due_date": 1719964800000,
    "due_date_time": true,
    "priority": 2,
    "assignee": 123456,
    "status": "to do"
  }'

Step 4: Review the ClickUp API Response

On success, the API returns a JSON object describing the new list. It includes fields such as:

• id: Unique identifier of the list.
• name: The list name you provided.
• orderindex: The position of the list within the folder.
• content: Description you set for the list.
• status: Status object with label and color.
• priority: Priority details if provided.
• assignee: User assigned to the list, if set.
• due_date and due_date_time: Due date information.
• folder: Information about the parent folder.

Use the returned id to reference this list in future ClickUp API operations, such as creating tasks, updating the list, or retrieving list metadata.

Error Handling in the ClickUp Create List Call

If the create request fails, the ClickUp API responds with an error status code and message. Common issues include:

• Missing or invalid API token in the Authorization header.
• Invalid or missing folder_id in the URL.
• Request body missing the required name field.
• Permissions issues for the workspace or folder.

Always check the HTTP status code and parse the error message returned by ClickUp to understand why the request did not succeed.

Official ClickUp Documentation and Further Help

You can view the full reference for the create list endpoint directly in the official developer docs at ClickUp Create List API. The reference includes the latest request and response formats, field types, and additional examples.

For broader workflow design, API strategy, and implementation help around ClickUp and other platforms, you can also explore consulting resources such as Consultevo.

Summary: Automating List Creation with the ClickUp API

By calling the create list endpoint in the ClickUp API, you can programmatically organize work within folders and spaces. Use the proper URL with a valid folder_id, send authorized POST requests with JSON bodies, and include at least the required name field. Handle responses and errors carefully so your automation remains reliable as your workspace grows.

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

“`