Skip to main content
POST
Add or Remove Lead Tags
One call, no lookups. PATCH /api/leads/{id} 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.

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.
string
Tuco lead id.
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.
string
Lead email. Case-insensitive.
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.
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.
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

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

Errors


Example


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

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.
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.