How to Merge Tasks with the ClickUp API

The ClickUp task merge endpoint lets you combine duplicate or related tasks into a single, clean record while preserving important data. This guide explains how to use the merge endpoint step-by-step, based strictly on the official API reference.

What the ClickUp Merge Tasks Endpoint Does

The merge endpoint allows you to select a primary task and merge one or more secondary tasks into it. After the operation:

• The primary task remains and receives merged data.
• The secondary task is removed or archived according to the API design.
• Supported fields such as comments, attachments, and custom fields can be consolidated.

This is especially useful when your ClickUp workspace accumulates duplicates from imports, integrations, or manual user error.

ClickUp Merge Tasks Endpoint Overview

The merge operation is exposed as an HTTP endpoint documented at the official developer site. You can view the full reference here: ClickUp Merge Tasks API reference.

From the reference, you will find:

• HTTP method used by the endpoint.
• Endpoint path, including any path parameters such as task IDs.
• Required and optional request body fields.
• Authentication and header requirements.
• Example request and response payloads.

Prerequisites for Using the ClickUp Merge Tasks API

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

• A valid ClickUp API token with appropriate workspace and task permissions.
• The ID of the primary task that will remain after the merge.
• The ID of the task that will be merged into the primary task.
• Network access to the ClickUp API endpoint from your environment.

It is good practice to test in a non-production space first, because merging tasks is typically not reversible.

Understanding the ClickUp Merge Request Structure

The reference page defines the JSON structure required in the request body. While field names and options come directly from the documentation, the general pattern looks like this:

• Field to identify the destination or primary task.
• Field or list to identify one or more source tasks.
• Optional configuration flags controlling how fields are merged.

Pay close attention to which fields are mandatory. The merge operation will fail with an error if any required value is missing or malformed.

Key Parameters for the ClickUp Merge Operation

Typical parameter types included in the body of the merge endpoint are:

• Primary task identifier: A required ID for the task that will survive after the merge.
• Secondary task identifier(s): One or more task IDs that will be merged into the primary task.
• Conflict handling options: Rules for how to behave when both tasks have values for the same field (for example, comments, attachments, or custom fields).

Refer to the linked ClickUp documentation for the exact field names, types, and allowed values.

Step-by-Step: How to Merge Tasks with ClickUp

Follow these steps to perform a merge operation safely.

1. Collect Required Task IDs from ClickUp

1. Use any task listing method (API, app UI, or integration) to identify the primary task.
2. Record the primary task ID.
3. Identify one or more tasks that will be merged into the primary task.
4. Record the IDs of these secondary tasks.

Always double-check task IDs. A wrong ID can lead to unintended data changes in your ClickUp workspace.

2. Build the ClickUp Merge Request Body

Construct a JSON body that matches the schema defined in the merge endpoint reference. At a high level, you will:

• Set the primary task field to your chosen destination task ID.
• List all secondary task IDs that should be merged.
• Configure optional flags such as merge strategies, if provided by the endpoint.

Make sure your JSON is valid and that you only use supported properties listed in the ClickUp API documentation.

3. Configure Headers and Authentication

When sending the HTTP request, include the necessary headers:

• Authorization: Your ClickUp API token.
• Content-Type: Typically application/json for JSON payloads.
• Any additional headers specified in the official reference.

Without the correct headers, the server will reject the request and no merge will occur.

4. Send the ClickUp Merge Request

1. Use your preferred HTTP client (such as curl, Postman, or a language SDK) to call the endpoint path shown in the documentation.
2. Attach the JSON body and headers you prepared.
3. Send the request to the ClickUp API.

The server will respond with a status code and, when successful, a response body describing the resulting task state.

5. Verify the Result in ClickUp

After a successful response:

• Retrieve the primary task again using a task detail endpoint.
• Confirm that expected comments, attachments, and other supported data from the secondary task are now present.
• Check that the secondary task is no longer listed as a separate active task, consistent with the behavior described in the API reference.

This verification step prevents unnoticed data issues in your ClickUp workflows.

Handling Errors in the ClickUp Merge API

The API documentation outlines possible error responses. Common causes include:

• Invalid or missing authentication token.
• Insufficient permissions for the tasks involved.
• Task IDs that do not exist in the current workspace.
• Malformed JSON or missing required fields in the request body.

Always log the full HTTP status code and the error message so you can map them against the official ClickUp reference and adjust your integration.

Best Practices for Safe ClickUp Task Merging

To keep your workspace organized and avoid accidental data loss, consider the following practices:

• Test in a sandbox: Use a test space or demo workspace before running merges on production data.
• Back up critical tasks: Export or duplicate high-value tasks before merging them.
• Automate cautiously: If you build automated deduplication, add safeguards such as dry-run modes or manual approvals.
• Document your rules: Define when and how your team should merge tasks so ClickUp data stays consistent.

Advanced ClickUp Merge Workflows

Once you are comfortable with single merges, you can design more advanced flows:

• Bulk deduplication: Scan for duplicates based on custom fields or titles, then use the merge endpoint programmatically.
• Cross-tool consolidation: If you import tasks from external systems, merge overlapping records into a single ClickUp task.
• Reporting cleanliness: Periodically merge obsolete duplicates so dashboards and reports stay accurate.

These workflows keep large ClickUp workspaces clean and focused on the single source of truth per work item.

Where to Learn More About ClickUp Integrations

For additional examples of workspace automation, integration patterns, and API usage strategies beyond simple task merging, you can explore consulting resources such as Consultevo. Combine these best practices with the official ClickUp Merge Tasks API documentation to design robust, maintainable automations.

By following the steps and guidelines above, you can confidently use the merge tasks endpoint to keep your ClickUp environment tidy, reduce duplicates, and maintain accurate task histories across your projects and teams.

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

“`