> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add or Remove Lead Tags

> Add and remove tags on a Tuco lead in one call, found by HubSpot Record ID, email or phone. Built for HubSpot workflow webhooks on segment changes.

> [!NOTE]
>
> **One call, no lookups.** [`PATCH /api/leads/{id}`](https://docs.tuco.ai/api-reference/endpoint/update-lead) replaces
> the whole tag list and needs Tuco's lead id. This endpoint finds the lead for you and only touches
> the tags you name, so a single HubSpot webhook can drive it.

Filter the Leads page by the tag (**Filter → Tag**, or open `https://app.tuco.ai/leads?tag=<tag>`)
and your team can work that list and call straight from it.

## Authentication

Pass your workspace API key as a Bearer token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Request body

Identify the lead with **at least one** of these. They are tried in this order and the first one
that finds a lead wins, so `email` and `phone` act as fallbacks for a contact Tuco has not linked
to HubSpot yet.

**leadId** `string`

Tuco lead id.

**hubspotRecordId** `string`

The HubSpot Record ID (HubSpot property `hs_object_id`). Leads synced from HubSpot already carry
it. A number is accepted too. `hs_object_id` works as the key name as well.

**email** `string`

Lead email. Case-insensitive.

**phone** `string`

Lead phone in any common format, e.g. `(650) 249-9992` or `+16502499992`. US numbers without a
country code are assumed.

Then say what to change. Send `add`, `remove`, or both.

**add** `string | string[]`

Tags to add. A string can hold several tags separated by **semicolons**
(`"vip;call-accepted-not-paid"`), because HubSpot webhook bodies can only carry text.
Commas are part of the tag (`"Dallas, TX"` is one tag). In an array, each item is one tag as written.
A tag the lead already has, in any letter case, is left as it is.

**remove** `string | string[]`

Tags to remove, same format. Matching ignores letter case: removing `vip` also removes `VIP`.
Removing a tag the lead does not have is not an error.

Tags are trimmed, blanks are dropped, and each tag can be up to 100 characters.

***

## Behaviour

* **Idempotent.** Sending the same add or remove twice leaves the lead the same as sending it once,
  so retries are safe.
* **Safe under load.** Two webhooks for the same lead arriving together both apply; neither overwrites the other.
* **Any language.** Letter case is ignored for every alphabet (`École` and `école` are one tag).
* **Every match is tagged.** If a HubSpot contact was imported into Tuco twice, both leads get the change (up to 25).
* **50-tag cap.** A change that would take a lead past 50 tags returns `400`. Removing tags always works.
* **Bots see it.** A bot that wakes on a tag (`includeTags`) picks the lead up on its next message.
  Bot tags match exactly, including letter case, so send the tag spelled the way the bot uses it.

***

## Response

```json theme={null}
{
  "success": true,
  "matchedBy": "hubspotRecordId",
  "matchedCount": 1,
  "leads": [
    { "_id": "6730f0c2a1b2c3d4e5f60718", "tags": ["vip", "call-accepted-not-paid"] }
  ]
}
```

`matchedBy` says which identifier found the lead. `leads[].tags` is each lead's full tag list after the change.

## Errors

| Status | When |
| - | - |
| `400` | No identifier, nothing to add or remove, the same tag in both `add` and `remove`, a tag that is not text or is over 100 characters, or the change would take a lead past 50 tags |
| `401` | Missing or invalid API key |
| `404` | No lead in your workspace matched any identifier you sent. The body lists what was tried: `{ "error": "Lead not found", "code": "lead_not_found", "tried": ["hubspotRecordId", "email"] }` |
| `429` | More than 300 requests a minute. Wait for the `Retry-After` seconds, then retry |
| `503` | The lead was being changed by another request at the same moment. Retry after `Retry-After` seconds; HubSpot does this for you |

***

## Example

```bash theme={null}
curl -X POST https://app.tuco.ai/api/leads/tags \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "hubspotRecordId": "51234567",
    "email": "ann@acme.com",
    "add": "call-accepted-not-paid"
  }'
```

***

## Set it up in HubSpot

Use two contact-based workflows: one for contacts joining your segment, one for contacts leaving it.
Each ends in a **Send a webhook** action. Check that your HubSpot subscription includes the webhook action.

**1. Create the 'joined' workflow**

Enrol contacts when they become members of the segment, e.g. *Call accepted, not paid*.

**2. Add a Send a webhook action**

* **Method:** `POST`
* **Webhook URL:** `https://app.tuco.ai/api/leads/tags`

**3. Authenticate with your Tuco API key**

* **Authentication type:** API key
* **API key name:** `Authorization`
* **API key location:** Request header
* **Secret value:** `Bearer tuco_xxxxxxxxxxxxx` (create one under **Integrations → API Keys** in Tuco)

**4. Customize the request body**

| Key | Value |
| - | - |
| `hubspotRecordId` | Property: **Record ID** |
| `email` | Property: **Email** |
| `phone` | Property: **Phone number** |
| `add` | Static value: `call-accepted-not-paid` |

Use **Customize request body**, not "include all properties": only these keys are read.

**5. Create the 'left' workflow**

Same webhook action, enrolled when contacts leave the segment, with the static key `remove`
instead of `add`.

> [!TIP]
>
> HubSpot retries a webhook that gets a `429` or a `5xx` for up to three days, and does not retry a
> `4xx`. A `404` means the contact is not a lead in Tuco yet. Once it is, the next join or leave tags it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.