# Send leads to ClickUp

> Turn every lead into a task in the list your team already works from.

Source: https://welcomeai.dev/docs/clickup
Category: Destinations
Updated: 2026-09-08

---
## What you need

A personal **API token**: ClickUp → your avatar → Settings → Apps → API Token. It starts with `pk_`.

ClickUp personal tokens have no permission settings of their own: the token can reach exactly what
the person who made it can reach. If a list is missing from the picker, that is what to check.

## Connect and route

1. In **Destinations**, connect ClickUp with the token.
2. Create a route and pick the list. We show every list the token can see, grouped by workspace and
   space, the same way ClickUp's sidebar does.
3. Map the fields. The left column is what your form asks; the right is what the list holds. The task
   name is required; the description and any custom fields on that list are optional.

A good default is the person's name or email as the task name, and the conversation summary as the
description.

### Large workspaces

Reading a big workspace takes a few seconds -- one real account has 4,959 lists across 22 spaces --
so we keep the answer and reuse it. Under the list picker you can see how many lists we found, when
we last read them, and a **Refresh** button. Press it after creating a list in ClickUp; otherwise the
stored answer is used and the dialog opens immediately.

## One route per widget, and so one per form

A route's scope is a widget. Leave it on all widgets and the route takes every lead; pin it to one
and it takes only that widget's.

That is also how two forms reach two places, because a widget runs one form: its lead capture names
the form it asks, so choosing the widget chooses the form. A contact form on one widget and a demo
request on another are two routes, each to its own destination. Two forms on the same widget is not a
thing you can set up -- swap the widget's form and you have changed which form it asks.

Choosing a widget does one more thing: the mapper's left column shows the questions **that** form
asks, instead of every question every form in the workspace asks. So a route built for the demo
request is not mapped against the contact form's fields, and the questions on screen are the ones a
visitor will actually be asked. Leave the route on all widgets and you get all of them, which is
right -- the route takes leads from all of them.

One consequence worth knowing: a lead captured by the assistant in conversation carries the widget it
came from, so a widget-scoped route takes it like any other. A lead pushed through the API with no
widget is taken only by a route with no widget.

## Custom fields

Custom fields on the list appear in the mapper, and **New field** creates one without leaving the
dialog -- text, long text, number, date, checkbox or a dropdown with the choices you type.

Two limits are ClickUp's, not ours:

- **A created field cannot be deleted through the API.** Once it exists, it can only be removed inside
  ClickUp. The dialog says so before it creates anything.
- **A choice cannot be added to a dropdown that already exists.** Create the dropdown with all its
  choices, or add the missing one in ClickUp.

### Dropdowns and other typed fields

ClickUp stores a dropdown as a list of options, and a task can only reference an option that exists.
A lead answering something that is not one of the choices has **that one field left out**, and the
task is still created -- the dispatch log names what was left out. This is deliberate: ClickUp
rejects the whole task for one bad value, and a lead that lands with eleven of twelve fields is worth
more than a lead that does not land.

Numbers, currencies, dates and checkboxes are converted for you. `$1,200` becomes 1200, `yes` and
`si` become a tick, and a date becomes ClickUp's own timestamp.

Fields ClickUp works out for itself -- formulas, rollups, progress, people and relationships -- are
not offered in the mapper, because no answer a visitor types could ever be a valid value for one.

## Check it before a visitor does

- **Check connection** on the account asks ClickUp whether the token still works and records the
  answer with today's date.
- **Send sample lead** creates one invented lead in the list this route points at, so you can see
  exactly what arrives. It uses the same mapping a real lead uses. It is not stored as a lead and
  does not count against your plan; the dispatch log marks it as a sample.

## When it fails

The dispatch log shows the request, the response, and which route sent it. The usual causes are a
token that lost access to the space, and a required custom field on the list that the lead had
nothing for.