Send leads to ClickUp

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.