ClickupLookup

Overview

The node "ClickupLookup" provides functionality to map ClickUp custom fields to their corresponding values, specifically focusing on tasks and custom task types within ClickUp. It supports operations such as looking up custom field values on tasks and retrieving custom task types for a given team. This node is useful when you want to dynamically fetch or translate custom field data from ClickUp tasks or manage custom task types programmatically.

Common scenarios include:

• Automatically mapping user-friendly labels or dropdown options from ClickUp custom fields to their underlying IDs or objects.
• Retrieving all custom task types available in a specific team to use them in workflows.
• Updating tasks with a selected custom task type (though this operation is outside the provided resource-operation scope).

Practical example:

• You have a list of tasks with custom dropdown fields in ClickUp, and you want to convert the dropdown label selected by users into its corresponding ID or full object for further processing or integration with other systems.

Properties

Additional properties relevant to the "Lookup on Task" resource and "Custom Task Type Lookup" operation (inferred from code and bundled properties):

Output

The node outputs JSON data structured according to the operation:

• For Lookup on Task with operation "lookup":

  • An array of objects, each representing a custom field lookup result with these fields:
    • lookupValue: The value provided to look up.
    • matchTo: The property used to match the lookup value (e.g., an ID).
    • matchAgainst: A string combining the custom field's name and ID.
    • outputType: The requested output format (e.g., "object" or a specific property).
    • result: The resolved value or object matching the lookup criteria, or a default "no match found" if none matched.

• For Custom Task Type Lookup operation:

  • An array of custom task type objects retrieved from the specified team, including their IDs, names, and descriptions.

The node does not output binary data.

Dependencies

• Requires access to the ClickUp API.
• Needs an API authentication credential configured in n8n, either via an Access Token or OAuth2.
• Uses several ClickUp API endpoints such as /team, /list/{listId}/field, and /team/{teamId}/custom_item.
• The node relies on internal helper functions to make authenticated API requests and handle pagination or data transformation.

Troubleshooting

• Common issues:

  • Invalid or expired API credentials will cause authentication failures.
  • Providing incorrect or missing team, list, or task IDs will result in empty or error responses.
  • Mismatched custom field keys or unsupported field types may lead to "no match found" results.
  • Network or API rate limiting errors from ClickUp can interrupt execution.

• Error messages:

  • Errors thrown during API calls are caught and can be optionally continued on failure depending on node settings.
  • Typical error messages relate to HTTP status codes like 401 Unauthorized (invalid credentials), 404 Not Found (invalid resource IDs), or 429 Too Many Requests (rate limiting).

• Resolutions:

  • Verify that the API key or OAuth2 token is valid and has sufficient permissions.
  • Double-check that the team, list, and custom field IDs exist and are accessible.
  • Use the node’s load options to select valid teams and lists to avoid manual input errors.
  • Implement retry logic or increase wait times if hitting rate limits.

Links and References

• ClickUp API Documentation
• n8n Expressions Documentation
• ClickUp Custom Fields Guide
• n8n Node Development Docs