ClickUp

Sync data to ClickUp lists as tasks. Use Zeotap to push leads, action items, support tickets, or any structured data into ClickUp for project management, collaboration, and operational workflows.

Prerequisites

A ClickUp account (Free Forever, Unlimited, Business, Business Plus, or Enterprise plan)
A personal API token or OAuth 2.0 access token
A ClickUp list to write tasks to

Permissions

Your API token inherits the permissions of the ClickUp user who generated it. The user must have:

Write access to the target list (member or higher role in the containing Space)
Task creation permissions in the Workspace

Authentication

ClickUp uses a Personal API Token for authentication.

Log in to your ClickUp account
Click your avatar in the lower-left corner and select Settings
Navigate to Apps in the left sidebar
Under API Token, click Generate (or Regenerate if you already have one)
Copy the token (it starts with pk_)
In Zeotap, paste the token into the Personal API Token field

Personal API tokens never expire and have the same permissions as your ClickUp user account.

Configuration

ClickUp does not require additional configuration fields beyond authentication.

Target Settings

Field	Type	Required	Description
List ID	Text	Yes	The ID of the ClickUp list where tasks will be created or updated. You can find this in the list URL (the numeric ID after `/li/`) or by using the ClickUp API to list your workspace hierarchy.

Supported Operations

Sync Modes

Mode	Supported	Description
Insert	Yes	Creates new tasks in the list
Update	Yes	Updates existing tasks matched by task ID
Upsert	Yes	Creates new tasks or updates existing ones matched by task ID
Mirror	—	Not supported — ClickUp does not provide a bulk delete API suitable for full-list replacement

Audience Sync Modes

ClickUp does not have a native audience or list membership concept, so audience sync modes are not supported.

Features

Field Mapping: Yes — map source columns to ClickUp task fields
Schema Introspection: No — ClickUp task fields are predefined; custom fields require manual configuration

Required Mapping Fields

Field	Description
`name`	The name / title of the task. Required for creating new tasks.

Default Destination Fields

Field	Type	Description
`name`	string	Task title (required for new tasks)
`description`	string	Plain-text task description
`markdown_description`	string	Markdown-formatted task description. Takes precedence over `description`.
`status`	string	Task status name (e.g. `open`, `in progress`, `closed`)
`priority`	string	Priority level: `1` (urgent), `2` (high), `3` (normal), `4` (low)
`due_date`	string	Due date as Unix timestamp in milliseconds
`start_date`	string	Start date as Unix timestamp in milliseconds
`assignees`	string	Comma-separated list of ClickUp user IDs to assign
`tags`	string	Comma-separated list of tag names
`time_estimate`	string	Estimated time in milliseconds
`points`	string	Sprint point value for the task

How It Works

Zeotap writes data to the specified ClickUp list via the ClickUp REST API v2:

Insert mode: Tasks are created using POST /api/v2/list/{list_id}/task with one task per request
Upsert mode: Rows containing a task_id field are updated via PUT /api/v2/task/{task_id}. Rows without a task_id are created as new tasks
Update mode: All rows are updated using PUT /api/v2/task/{task_id}. Each row must include a valid task_id

Batching

ClickUp does not have a bulk create or update endpoint. Zeotap sends individual API requests for each task. Each request creates or updates a single task.

Error Handling

Each task is sent as an individual request. If a task fails, it is recorded as a row error without affecting other tasks.
The writer retries on transient errors (HTTP 429 rate limits and 5xx server errors) with exponential backoff.
When rate-limited, Zeotap respects the X-RateLimit-Reset header to determine when to retry.

Rate Limits

ClickUp enforces per-token rate limits that vary by Workspace plan:

Plan	Requests per Minute
Free Forever / Unlimited / Business	100
Business Plus	1,000
Enterprise	10,000

When the rate limit is exceeded, ClickUp returns HTTP 429. Zeotap automatically retries with backoff based on the X-RateLimit-Reset response header.

For large syncs on Free/Unlimited/Business plans (~100 tasks/minute), expect longer sync times.

Best Practices

Include task IDs for updates: When using upsert or update mode, include the ClickUp task_id in your source data. Without it, upsert mode creates new tasks instead of updating existing ones.
Use meaningful status names: Task status names must match the statuses configured in your ClickUp Space exactly (case-insensitive). Invalid status names cause task creation to fail.
Format dates as millisecond timestamps: ClickUp expects due dates and start dates as Unix timestamps in milliseconds, not formatted date strings.
Monitor rate limits on lower plans: Free and Business plans allow only 100 requests per minute. For syncs with thousands of tasks, consider upgrading or scheduling syncs during off-peak hours.
Use custom fields for structured data: For data beyond the built-in task fields, configure ClickUp custom fields and pass a JSON array in the custom_fields mapping. The format is [{"id": "field_id", "value": "..."}].

Troubleshooting

Authentication failed: invalid API token

Verify that your personal API token is correct and has not been regenerated. Tokens start with pk_. Generate a new token at Settings > Apps > API Token in your ClickUp account if needed.

List not found (HTTP 404)

Double-check the List ID in your target settings. The List ID is a numeric value found in the list URL. Ensure the list has not been deleted or moved to a different Space.

Access denied (HTTP 403)

Your API token user does not have write access to the target list. Verify that the user is a member of the Space containing the list and has task creation permissions.

Rate limited (HTTP 429)

ClickUp enforces 100 requests per minute on Free/Unlimited/Business plans. Zeotap retries automatically with backoff. For large syncs, consider upgrading to Business Plus (1,000 req/min) or Enterprise (10,000 req/min).

Invalid status name

ClickUp rejects tasks with status names that do not match the configured statuses in the Space. Check the available statuses in your ClickUp Space settings and use the exact status name in your source data.

Task update fails: task_id not found

When using update or upsert mode, ensure the task_id value corresponds to an existing task in your ClickUp workspace. Task IDs are alphanumeric strings (e.g., abc123). Deleted tasks cannot be updated.

Assignee IDs not recognized

ClickUp assignees must be specified as numeric user IDs, not email addresses or usernames. Use the ClickUp API (GET /api/v2/team) to retrieve your workspace member IDs.