Add or Remove Lead Tags
curl --request POST \
--url https://app.tuco.ai/api/leads/tags \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"leadId": "<string>",
"hubspotRecordId": "<string>",
"email": "<string>",
"phone": "<string>",
"add": [
"<string>"
],
"remove": [
"<string>"
]
}
'import requests
url = "https://app.tuco.ai/api/leads/tags"
payload = {
"leadId": "<string>",
"hubspotRecordId": "<string>",
"email": "<string>",
"phone": "<string>",
"add": ["<string>"],
"remove": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
leadId: '<string>',
hubspotRecordId: '<string>',
email: '<string>',
phone: '<string>',
add: ['<string>'],
remove: ['<string>']
})
};
fetch('https://app.tuco.ai/api/leads/tags', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/leads/tags",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'leadId' => '<string>',
'hubspotRecordId' => '<string>',
'email' => '<string>',
'phone' => '<string>',
'add' => [
'<string>'
],
'remove' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/leads/tags"
payload := strings.NewReader("{\n \"leadId\": \"<string>\",\n \"hubspotRecordId\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"add\": [\n \"<string>\"\n ],\n \"remove\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/leads/tags")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": \"<string>\",\n \"hubspotRecordId\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"add\": [\n \"<string>\"\n ],\n \"remove\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/leads/tags")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"leadId\": \"<string>\",\n \"hubspotRecordId\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"add\": [\n \"<string>\"\n ],\n \"remove\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_bodyLines & Leads
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.
POST
/
api
/
leads
/
tags
Add or Remove Lead Tags
curl --request POST \
--url https://app.tuco.ai/api/leads/tags \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"leadId": "<string>",
"hubspotRecordId": "<string>",
"email": "<string>",
"phone": "<string>",
"add": [
"<string>"
],
"remove": [
"<string>"
]
}
'import requests
url = "https://app.tuco.ai/api/leads/tags"
payload = {
"leadId": "<string>",
"hubspotRecordId": "<string>",
"email": "<string>",
"phone": "<string>",
"add": ["<string>"],
"remove": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
leadId: '<string>',
hubspotRecordId: '<string>',
email: '<string>',
phone: '<string>',
add: ['<string>'],
remove: ['<string>']
})
};
fetch('https://app.tuco.ai/api/leads/tags', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/leads/tags",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'leadId' => '<string>',
'hubspotRecordId' => '<string>',
'email' => '<string>',
'phone' => '<string>',
'add' => [
'<string>'
],
'remove' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/leads/tags"
payload := strings.NewReader("{\n \"leadId\": \"<string>\",\n \"hubspotRecordId\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"add\": [\n \"<string>\"\n ],\n \"remove\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.tuco.ai/api/leads/tags")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"leadId\": \"<string>\",\n \"hubspotRecordId\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"add\": [\n \"<string>\"\n ],\n \"remove\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/leads/tags")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"leadId\": \"<string>\",\n \"hubspotRecordId\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"add\": [\n \"<string>\"\n ],\n \"remove\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_bodyOne 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.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.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, soemail and phone act as fallbacks for a contact Tuco has not linked
to HubSpot yet.
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.Lead phone in any common format, e.g.
(650) 249-9992 or +16502499992. US numbers without a
country code are assumed.add, remove, or both.
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.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.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 (
Écoleandécoleare 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
{
"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
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 |
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.