Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/clickup-pack/skills/clickup-migration-deep-dive/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill clickup-migration-deep-dive. Copyright stays with the author (MIT).

ClickUp Migration Deep Dive

Overview

Migrate project data to ClickUp from external tools or between ClickUp workspaces using API v2. Covers data mapping, batch creation, custom field migration, and validation.

Prerequisites

• Approved source and destination owners, scopes, and change window
• Exported source inventory plus a field/status/assignee mapping decision
• Scoped API credentials and separate staging or reversible pilot destination
• Verified backup, idempotency keys, reconciliation query, and rollback owner

Instructions

Map and validate a small representative sample before any bulk creation, then create in bounded batches with durable source IDs and rate limits. Reconcile counts, statuses, custom fields, relationships, and permissions after every batch; do not retire the source system or cancel its access until the agreed validation window confirms the migration is complete.

Migration Types

ClickUp Hierarchy Mapping

External Concept        ClickUp API v2 Target
─────────────────       ──────────────────────
Project/Board       →   Space   (POST /team/{team_id}/space)
Epic/Section        →   Folder  (POST /space/{space_id}/folder)
Sprint/Column       →   List    (POST /folder/{folder_id}/list)
Issue/Card/Task     →   Task    (POST /list/{list_id}/task)
Subtask             →   Task with parent  (parent field)
Label/Tag           →   Tag     (POST /task/{task_id}/tag/{tag_name})
Custom Field        →   Custom Field (POST /task/{task_id}/field/{field_id})
Comment             →   Comment (POST /task/{task_id}/comment)
Attachment          →   Attachment (POST /task/{task_id}/attachment)

Migration Script

// src/migrate-to-clickup.ts
interface MigrationItem {
  externalId: string;
  name: string;
  description: string;
  status: string;
  priority?: 'urgent' | 'high' | 'normal' | 'low';
  assigneeEmail?: string;
  dueDate?: string;
  labels?: string[];
  subtasks?: MigrationItem[];
}

const PRIORITY_MAP: Record<string, number> = {
  urgent: 1, high: 2, normal: 3, low: 4,
};

const STATUS_MAP: Record<string, string> = {
  'To Do': 'to do',
  'In Progress': 'in progress',
  'Done': 'complete',
  'Backlog': 'to do',
  // Add your status mappings here
};

async function migrateItems(
  items: MigrationItem[],
  listId: string,
  memberEmails: Map<string, number>, // email -> ClickUp user ID
): Promise<{ migrated: number; errors: Array<{ item: string; error: string }> }> {
  let migrated = 0;
  const errors: Array<{ item: string; error: string }> = [];

  for (const item of items) {
    try {
      const assignees = item.assigneeEmail && memberEmails.has(item.assigneeEmail)
        ? [memberEmails.get(item.assigneeEmail)!]
        : [];

      const task = await clickupRequest(`/list/${listId}/task`, {
        method: 'POST',
        body: JSON.stringify({
          name: item.name,
          markdown_description: item.description,
          status: STATUS_MAP[item.status] ?? 'to do',
          priority: item.priority ? PRIORITY_MAP[item.priority] : null,
          assignees,
          due_date: item.dueDate ? new Date(item.dueDate).getTime() : undefined,
          due_date_time: !!item.dueDate,
          tags: item.labels ?? [],
        }),
      });

      // Migrate subtasks
      if (item.subtasks?.length) {
        for (const subtask of item.subtasks) {
          await clickupRequest(`/list/${listId}/task`, {
            method: 'POST',
            body: JSON.stringify({
              name: subtask.name,
              markdown_description: subtask.description,
              parent: task.id,
              status: STATUS_MAP[subtask.status] ?? 'to do',
            }),
          });
        }
      }

      migrated++;
      console.log(`Migrated: ${item.name} -> ${task.id}`);

      // Rate limit: stay under 100 req/min
      await new Promise(r => setTimeout(r, 700));
    } catch (error) {
      errors.push({ item: item.name, error: String(error) });
    }
  }

  return { migrated, errors };
}

Build Member Lookup

// Map external emails to ClickUp user IDs
async function buildMemberLookup(teamId: string): Promise<Map<string, number>> {
  const data = await clickupRequest(`/team/${teamId}`);
  const lookup = new Map<string, number>();

  for (const member of data.team.members) {
    lookup.set(member.user.email, member.user.id);
  }

  return lookup;
}

Workspace-to-Workspace Migration

async function cloneListBetweenWorkspaces(
  sourceToken: string,
  sourceListId: string,
  destToken: string,
  destListId: string,
) {
  // Fetch all tasks from source
  const sourceTasks = [];
  let page = 0;
  let hasMore = true;

  while (hasMore) {
    const data = await fetch(
      `https://api.clickup.com/api/v2/list/${sourceListId}/task?page=${page}&subtasks=true&include_closed=true`,
      { headers: { 'Authorization': sourceToken } }
    ).then(r => r.json());

    sourceTasks.push(...data.tasks);
    hasMore = data.tasks.length === 100;
    page++;
  }

  console.log(`Fetched ${sourceTasks.length} tasks from source`);

  // Create tasks in destination
  for (const task of sourceTasks) {
    if (task.parent) continue; // Handle subtasks separately

    const created = await fetch(
      `https://api.clickup.com/api/v2/list/${destListId}/task`,
      {
        method: 'POST',
        headers: { 'Authorization': destToken, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          name: task.name,
          markdown_description: task.description,
          priority: task.priority?.id ? parseInt(task.priority.id) : null,
          tags: task.tags.map((t: any) => t.name),
        }),
      }
    ).then(r => r.json());

    console.log(`Cloned: ${task.name} -> ${created.id}`);
    await new Promise(r => setTimeout(r, 700)); // Rate limit
  }
}

Validation

async function validateMigration(
  sourceItems: MigrationItem[],
  listId: string,
): Promise<{ match: number; missing: string[] }> {
  const tasks = await clickupRequest(`/list/${listId}/task?include_closed=true`);
  const taskNames = new Set(tasks.tasks.map((t: any) => t.name));

  const missing = sourceItems
    .filter(item => !taskNames.has(item.name))
    .map(item => item.name);

  return {
    match: sourceItems.length - missing.length,
    missing,
  };
}

Error Handling

Output

Produce a migration receipt with source/destination scope, mappings, batch and task counts, skipped/failed items, custom-field and assignee decisions, reconciliation result, approvals, and rollback status. Preserve redacted audit data rather than user tokens, raw private task content, or unnecessary member details.

Examples

Migrate one staging list with ten representative tasks, map its status and one custom field, then compare source IDs and target tasks before proceeding. If the reconciliation finds missing records or a field mapping is ambiguous, stop the next batch and repair the map instead of recreating tasks blindly.

Resources

• ClickUp Create Task
• ClickUp Get Tasks
• ClickUp Import Guide

Next Steps

For advanced troubleshooting during migration, see clickup-debug-bundle.