Description

n8n-nodes-clickuplookup

An n8n community node for lookup and mapping in ClickUp workflows — match incoming values to dropdown/label options, list statuses, priorities, and custom task types without hard-coding field metadata.

ClickUp custom fields are dynamic. The built-in ClickUp node handles CRUD well, but comparing expression output to field option IDs is painful. This node focuses on that gap.

n8n is a fair-code licensed workflow automation platform.

Installation

Follow the community nodes installation guide.

Docker / self-hosted — persist custom nodes between updates:

mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install n8n-nodes-clickuplookup
or for local development:
npm install file:/absolute/path/to/n8n-nodes-clickup-lookup

Restart n8n after install or upgrade. If you bind-mount ~/.n8n, the nodes folder survives container recreates.

Operations

Field → Resolve Option

Match values against option-backed metadata on a list.

List selection (pick one):

| Mode | When to use |
|——|————-|
| Browse | Team → Space → one list dropdown (Folder / List) |
| Hierarchy | Classic folder vs folderless path (default; matches 1.0 layout) |
| List ID | Paste or express a list ID directly |

Per mapping row:

| Control | Purpose |
|———|———|
| Target | Custom field, status, or priority |
| Field | Dropdown or labels field (custom field only) |
| List All Options | Return every option as objects (discovery) |
| Value | Pick from loaded ClickUp options, or use an expression |
| Mapping | Preset such as Name → ID |
| Advanced Mapping | Separate Find By and Return fields |

Output shape (one item per mapping row):

| Field | Meaning |
|——-|———|
| lookupTarget | customField, status, or priority |
| lookupValue | Value searched (or * for list-all) |
| matchTo | Field used to match (e.g. name, id) |
| matchAgainst | Human-readable target (field name or "list statuses") |
| outputType | What was returned (e.g. id, object) |
| result | Matched value, array of options, or "no match found" |

Task Type → List / Update

• List — all custom task types for a workspace (GET /team/{id}/custom_item)
• Update — set customitemid on a task; optional Use Custom Task ID + workspace team_id

Task → List / Find / Get

| Operation | Purpose |
|———–|———|
| List | Paginated tasks in a list → { id, name, custom_id, status, url } |
| Find | Exact match by task name or custom task ID in a list |
| Get | Fetch one task by internal or custom ID (default operation — same as 1.0) |

Task List/Find share List Selection with Field. Optional filters: closed tasks, subtasks, status (List), limit (List, default 50).

Credentials

Two credential types (same tokens as the built-in ClickUp node):

• ClickUp Lookup API — personal access token (pk_…)
• ClickUp Lookup OAuth2 API — OAuth2

Docs: ClickUp authentication

Compatibility

| Item | Value |
|——|——-|
| Package | 1.2.0 |
| Node type version | 2 (workflows saved at typeVersion 2 keep working) |
| n8n | 1.x / 2.x with n8n-workflow ^2.2 |
| ClickUp API | v2 |

Backward compatibility: Saved parameter names from 1.0 (matchTo, output, team, space, list, etc.) are still read at runtime. UI labels changed in 1.1; you do not need to re-save workflows for them to execute.

Usage examples

Discover dropdown options — enable List All Options, or pick All options (*) as the value.

Map “Email” to option ID — Target Custom Field, pick the field, Value Email, Mapping Name → ID.

Find a task by name — Task → Find, pick your list, enter the task name, use the returned id downstream.

List open tasks — Task → List with optional status filter.

See workflows/clickup-lookup-smoke.json for a starter workflow.

Migration guide

From 1.0.0 → 1.2.0 (Field — no change required)

Existing nodes keep working. The operation value is still lookupOptions internally; the UI label is now Resolve Option.

1.0 saved parameters (still valid):

{
  "resource": "field",
  "operation": "lookupOptions",
  "team": "36081325",
  "space": "54201574",
  "folderless": false,
  "folder": "108197607",
  "list": "901325237142",
  "customFieldsUi": {
    "customFieldsValues": [
      {
        "lookupTarget": "customField",
        "fieldKey": "293abad7-42ae-4089-9108-6911fadf4ea9|drop_down",
        "value": "Email",
        "matchTo": "name",
        "output": "id"
      }
    ]
  }
}

Equivalent 1.2 UI (optional refresh):

{
  "listSelectionMode": "hierarchy",
  "customFieldsUi": {
    "customFieldsValues": [
      {
        "lookupTarget": "customField",
        "fieldKey": "293abad7-42ae-4089-9108-6911fadf4ea9|drop_down",
        "value": "Email",
        "mappingPreset": "nameToId"
      }
    ]
  }
}

List all options — any of these still work:

• "value": "*" (legacy)
• "listAllMode": true (1.1+ toggle)
• Value All options (*) in the dropdown

Removed in 1.1: fieldOptionsReference — ignored if still present in JSON; use Value dropdown instead.

| 1.0.0 UI | 1.2.0 UI |
|———-|———-|
| Field Options Reference | Value dropdown |
| Lookup Options | Resolve Option |
| Lookups | Mappings |
| Match To / Output | Find By / Return (advanced) or Mapping preset |

From 1.0.0 → 1.2.0 (Task)

Task → Get is unchanged. Ensure saved workflows include "operation": "get" when fetching by task ID:

{
  "resource": "task",
  "operation": "get",
  "taskId": "86agvpxeg"
}

New in 1.2 — list or find tasks in a list (does not replace Get):

{
  "resource": "task",
  "operation": "find",
  "listSelectionMode": "hierarchy",
  "team": "36081325",
  "space": "54201574",
  "folder": "108197607",
  "list": "901325237142",
  "searchValue": "Kate Tokarski",
  "caseInsensitive": true
}

From 0.1.x → 1.0.0+

| 0.1.x | 1.0.0+ |
|——-|——–|
| Lookup on Task → Field Options Lookup | Field → Resolve Option |
| Lookup on Task → Custom Task Type Lookup | Task Type → List |
| Custom Task Type → Update… | Task Type → Update |

Re-select Resource and Operation once when upgrading from 0.1.x.

Resources

• Community nodes documentation
• Repository
• CHANGELOG

Version history

See CHANGELOG.md.