Actions3
- Lookup on Task Actions
- Custom Task Type Actions
Overview
This node, named "ClickupLookup," is designed to map and lookup custom fields within ClickUp tasks. It enables users to retrieve specific field options or values from tasks based on various criteria, such as team, space, folder, list, and custom field lookups. This functionality is particularly useful when automating workflows that require dynamic retrieval of task metadata or custom field data from ClickUp.
Common scenarios include:
- Fetching available options for a dropdown or label-type custom field in a task.
- Looking up specific custom field values by matching against color, ID, label, or other attributes.
- Retrieving all options for a custom field when no specific lookup value is provided.
- Integrating with ClickUp to dynamically populate UI elements or decision branches based on task custom fields.
Practical example:
- An automation workflow that assigns tasks based on the priority selected in a custom dropdown field. The node can lookup the dropdown options and their IDs to match and route tasks accordingly.
Properties
| Name | Meaning |
|---|---|
| Authentication | Method of authentication to use: either "Access Token" or "OAuth2". |
| Team Name or ID | Select or specify the ClickUp team by name or ID. Required for operations involving teams. |
| Space Name or ID | Select or specify the ClickUp space by name or ID. Depends on the selected team. Required for task lookup operations. |
| Folderless List | Boolean flag indicating whether to use folderless lists (true) or lists inside folders (false). |
| Folder Name or ID | Select or specify the folder by name or ID. Required if Folderless List is false. Depends on the selected space. |
| List Name or ID | Select or specify the list by name or ID. Depends on whether folderless is true or false; loads folderless lists or folder-contained lists accordingly. Required. |
| Custom Field Lookups | Collection of custom field lookup entries. Each entry includes: |
| - Field Name or ID | The ID of the custom field to lookup against. Loaded dynamically based on the selected list. |
| - Type | Internal hidden field indicating the type of the custom field (e.g., drop_down, labels). |
| - Field Options Reference | Reference display of the field's dropdown or label options (informational only, does not affect output). |
| - Lookup Value | The value to lookup in the custom field. If empty or "*", all options are returned. |
| - Match To | Attribute of the field option to match against. For dropdowns: Color, ID, Index, or Name. For labels: Color, ID, or Label. |
| - Output | Attribute of the matched field option to output. For dropdowns: Color, ID, Index, Name, or Object. For labels: Color, ID, Label, or Object. |
Output
The node outputs JSON data representing the results of the custom field lookups. For each custom field lookup entry, it returns an object containing:
lookupValue: The value used for lookup.matchTo: The attribute matched against (e.g., id, color).matchAgainst: A string combining the field name and ID for reference.outputType: The attribute requested for output (e.g., id, name).result: The matched value(s) or object(s) depending on the lookup and output settings. If no specific lookup value is provided, it returns all options for that field attribute.
The output is structured as an array of these lookup result objects, allowing downstream nodes to process or route based on the retrieved custom field data.
The node does not output binary data.
Dependencies
- Requires access to the ClickUp API.
- Needs an API key credential or OAuth2 authentication configured in n8n.
- Relies on several ClickUp API endpoints to fetch teams, spaces, folders, lists, custom fields, and their options.
- Dynamic loading of options depends on prior selections (e.g., lists depend on folder or space).
Troubleshooting
Common issues:
- Incorrect or missing authentication credentials will cause API request failures.
- Selecting invalid or non-existent team, space, folder, or list IDs will result in empty or error responses.
- Providing a lookup value that does not match any field option will return "no match found".
- Misconfiguration of the
folderlessboolean may lead to incorrect list loading.
Error messages:
- API errors from ClickUp (e.g., 401 Unauthorized) indicate authentication problems; verify API keys or OAuth tokens.
- Validation errors when required parameters are missing; ensure all required fields are filled.
- Network or timeout errors suggest connectivity issues; check network and API availability.
Resolution tips:
- Double-check all IDs and names used in properties.
- Use the dynamic load options to select valid entities rather than manual input.
- Enable "Continue On Fail" in the node settings to handle partial failures gracefully.