Search documentation...

K
ChangelogBook a demoSign up

ClickUp

A productivity team app for storing all essentials such as tasks, documents, goals, chat, and more.

Supported syncing

TypeDescriptionSupported Sync ModesAPI Reference
TasksSync data from any source to ClickUp tasks and subtasksUpsert, Update, InsertTasks docs

For more information about sync modes, refer to the sync modes docs.

Connect to ClickUp

Go to the Destinations overview page and click the Add destination button. Select ClickUp and click Continue. You can then authenticate Hightouch to ClickUp using OAuth.

Select Log in to ClickUp and log into your ClickUp account. You then need to select the ClickUp workspace or workspaces you want to connect to.

ClickUp Workspace selection

Once done, you will be redirected back to Hightouch to enter a descriptive name for your destination and complete setup.

Sync configuration

Once you've set up your ClickUp destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the ClickUp destination you want to sync to.

Syncing tasks

In ClickUp, a task is a specific action or activity that needs to be completed to achieve a particular goal or objective. Hightouch supports syncing tasks and subtasks.

To get started, select the ClickUp workspace, space, folder, and list for your tasks. You can then choose to insert new tasks, update existing ones, or do both in upsert mode.

If you want to sync subtasks, you need to map the Parent field. Refer to the references section to learn more.

Hightouch doesn't update closed or archived ClickUp tasks. If your model contains data related to a closed or archived task, the sync creates a new task with the provided data.

Record matching

You can match rows from your model to tasks in ClickUp on identifer fields in ClickUp. The identifer fields you can use depend on your sync mode:

  • In Upsert mode, you can match on custom fields, which are displayed as id in the dropdown menu.
  • In Update mode, you can match on any of the following ClickUp fields:
  • In Insert mode, ClickUp automatically generates an identifier for every new record synced, so there is no need to match an existing record.

To avoid unexpected duplicates or other potential issues, make sure you select a ClickUp field with unique values. Refer to the record matching docs for more information.

Field mapping

When creating a new task, ClickUp requires a name for it. Therefore, in upsert and insert modes, you must map the Name field to complete your configuration.

You can also map data from any of your model columns to default fields in ClickUp. The following default fields have some special guidelines:

  • Status: The values you sync must be a valid statuses for your task. Status is case insensitive; for example, in progress is the same as IN PROGRESS. See ClickUp's custom status docs for customization information.
  • Priority: This is a number that corresponds to the priorities available in the ClickUp UI. 1 is the must urgent priority while 4 is the least urgent.
  • Time Estimate: This field must be in milliseconds.

Arrays

You can sync array fields to ClickUp by selecting model columns that contain either comma-delimited strings or arrays. If you sync a comma-delimited string, for example "tag1, tag2, tag3", Hightouch transforms it into the array (["tag1", "tag2", "tag3"]) ClickUp expects.

Hightouch overwrites array values rather than aggregating them. For example, suppose you sync the following array ["tag1", "tag2"] to the tags field of a particular task. Then, a later sync sends another array ["tag1", "tag3"] to the same task's tags. The tasks tags will be ["tag1", "tag3"], not ["tag1", "tag2", "tag3"] after the later sync runs.

References

You can relate tasks to other ClickUp objects while field mapping.

To do so, select a ClickUp reference field. Hightouch denotes these with a chainlink icon. Begin by selecting one of these fields, for example Links to. The Links To field lets you include a task ID to create a linked dependency for the task you're syncing.

Field mapping in the Hightouch UI

Then, select a field on the object you're referencing to match on, for example, a task's ID, and the corresponding column from your model.

Field mapping in the Hightouch UI

Hightouch uses this column to look up the related object's ID and create the relationship with the task you're syncing. Generally, it's best to match on ID fields, but Hightouch also supports matching on meaningful properties like email for users.

Field mapping in the Hightouch UI

A common reference field is Parent. Mapping to the Parent field lets you sync subtasks.

Field mapping in the Hightouch UI

The preceding screenshot shows associating a parent task to a subtask based on the parent's task ID. The parent cannot be a subtask itself and it must be part of the ClickUp list you selected in the sync configuration.

Hightouch syncs only one value to reference fields. This includes reference fields like assignees that allow multiple values.

Custom field mapping

Hightouch supports syncing data to these custom field types:

Custom field typeExpected data type or descriptionExample
CheckboxBoolean valuetrue or false
DateMillisecond Unix timestamp; See the date formatting tip.1682452269219
DropdownA series of options in a menu-
EmailValid email addresslana@clickup.com
LabelsA flexible list of options (invalid labels will be omitted)-
MoneyA numerical value9.99
PeoplePeople or teams, see (#references)Sam
PhoneA valid phone number with country and area code"+1 123 456 7890"
RatingA number value from 1 through 55
TasksTasks linked together without relationshipsTask A
TextSingle-line text"This is a single-line text"
Text AreaMulti-line text"This is a multi-line text..."
WebsiteA valid URLhttps://clickup.com

Delete behavior

The delete behavior you select dictates what to do when a row no longer appears in your model's query results. You have the following options for upsert mode:

BehaviorDescription
Do nothingKeep the task in ClickUp with all its synced fields
ClearClear all the mapped fields, but keep the task in ClickUp
DeleteDelete the synced tasks from ClickUp

Update mode has these options:

BehaviorDescription
Do nothingKeep the task in ClickUp with all its synced fields

Insert mode doesn't support any delete behavior.

Tips and troubleshooting

Formatting dates

ClickUp expects millisecond Unix timestamps for all date fields. A millisecond timestamp is numerical value with 13 digits, for example, 1620170285617, as compared to a traditional Unix timestamp which has ten.

A convenient way to convert your date values to Unix millisecond timestamps is to use the to_unix function in the template mapper.

Field mapping in the Hightouch UI

The to_unix function throws an error if the input row's value is null. To avoid this, you can enter this Liquid into the template mapper:

{%- if row['column_name'] == null -%} {{null}} {%- else -%} {{row['column_name'] | to_unix}} {%- endif -%}

Be sure to replace column_name with the name of your model column.

Common errors

To date, our customers haven't experienced any errors while using this destination. If you run into any issues, please don't hesitate to . We're here to help.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Jun 21, 2023

On this page

Supported syncingConnect to ClickUpSync configurationSyncing tasksTips and troubleshootingFormatting datesCommon errorsLive debuggerSync alerts

Was this page helpful?