API reference / Contacts
Tags
A tag is a colored label you put on contacts, such as "Hot lead" or "Spanish speaker". Use tags to mark contacts for your team, filter them in the app, and start automations. Tags don't decide who a campaign reaches; lists do. This page manages the tags themselves. To tag a contact, see Add a tag to a contact.
Routes
| Method | Route | Scope | What it does |
|---|---|---|---|
GET |
/tag/public/tags |
contacts:read |
List your tags |
POST |
/tag/public/tags |
contacts:write |
Create a tag |
PUT |
/tag/public/tags/{tag_id} |
contacts:write |
Rename, recolor, or set a description on a tag |
DELETE |
/tag/public/tags/{tag_id} |
contacts:write |
Delete a tag |
POST |
/tag/public/tags/bulk-delete |
contacts:write |
Delete several tags at once |
List your tags
Returns your tags, newest first. Without limit you get all of them.
| Field | Type | Required | Description |
|---|---|---|---|
search_term |
string | No | Tags whose label contains this text, ignoring case. |
limit |
integer | No | Most tags to return. |
curl "https://api-v2.dropcowboy.com/tag/public/tags?search_term=lead" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": [
{
"tag_id": "fbd9fdcb-59ac-42ba-991e-3b469b9df791",
"label": "Hot lead",
"description": "Priority follow-up needed",
"color": "#E11D48",
"text_color": "#FFFFFF",
"created_at": 1790870333466,
"created_by": "d8ea4045-3e3c-45e6-b2ba-3917287c378c",
"updated_at": 1790870333466,
"updated_by": "d8ea4045-3e3c-45e6-b2ba-3917287c378c"
}
],
"meta": { "request_id": "35f86685-859f-4a8d-926a-45ec7fba7ddc" }
}
To find a tag by name before you create it, search for it first. Labels don't have to be unique, so creating the same label twice gives you two tags.
Create a tag
| Field | Type | Required | Description |
|---|---|---|---|
label |
string | Yes | The text on the tag. |
description |
string | No | Tooltip shown on hover wherever the tag chip appears. Max 500 characters. |
color |
string | No | Background color, such as #E11D48. |
text_color |
string | No | Text color, such as #FFFFFF. |
curl -X POST "https://api-v2.dropcowboy.com/tag/public/tags" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "label": "Hot lead", "description": "Priority follow-up needed", "color": "#E11D48", "text_color": "#FFFFFF" }'
The response is 201 with the new tag.
{
"data": {
"tag_id": "fbd9fdcb-59ac-42ba-991e-3b469b9df791",
"label": "Hot lead",
"description": "Priority follow-up needed",
"color": "#E11D48",
"text_color": "#FFFFFF",
"is_seed": false,
"created_at": 1790870333466,
"created_by": "d8ea4045-3e3c-45e6-b2ba-3917287c378c",
"updated_at": 1790870333466,
"updated_by": "d8ea4045-3e3c-45e6-b2ba-3917287c378c",
"deleted_at": null,
"deleted_by": null
},
"meta": { "request_id": "22b934c0-e7e6-4f07-8608-e2bc91f06e39" }
}
Rename, recolor, or describe a tag
Changes the fields you send. Omit label to leave the name unchanged. An empty description clears the tooltip. Contacts that have the tag show the change.
| Field | Type | Required | Description |
|---|---|---|---|
label |
string | No | The text on the tag. |
description |
string | No | Tooltip shown on hover. Max 500 characters. Empty string clears it. |
color |
string | No | New background color. |
text_color |
string | No | New text color. |
curl -X PUT "https://api-v2.dropcowboy.com/tag/public/tags/fbd9fdcb-59ac-42ba-991e-3b469b9df791" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "label": "Hot lead", "color": "#F59E0B" }'
{
"data": {
"id": "fbd9fdcb-59ac-42ba-991e-3b469b9df791",
"label": "Hot lead",
"color": "#F59E0B",
"text_color": "#FFFFFF",
"updated_at": "2026-10-01T16:38:53.466Z"
},
"meta": { "request_id": "5292b8c9-4b2d-44c5-84b7-5dd37627aeb8" }
}
This response names the tag's id id and gives updated_at as an ISO 8601 string.
Delete a tag
Deletes the tag. It stops appearing in your tag list, and you can't add it to contacts afterwards. Contacts that had it still carry its id in tags, so ignore tag ids that aren't in your tag list.
curl -X DELETE "https://api-v2.dropcowboy.com/tag/public/tags/fbd9fdcb-59ac-42ba-991e-3b469b9df791" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": { "id": "fbd9fdcb-59ac-42ba-991e-3b469b9df791", "deleted": true },
"meta": { "request_id": "3b2f0314-e849-4799-9969-af93349bef75" }
}
Delete several tags at once
Deletes every tag in tag_ids. Ids that don't exist, or are already deleted, are skipped.
| Field | Type | Required | Description |
|---|---|---|---|
tag_ids |
array | Yes | One or more tag ids. |
curl -X POST "https://api-v2.dropcowboy.com/tag/public/tags/bulk-delete" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "tag_ids": ["fbd9fdcb-59ac-42ba-991e-3b469b9df791", "23f5fb66-b9ff-4e52-9765-d961345b5463"] }'
matched_count is how many of your tags matched. modified_count is how many were deleted by this call.
{
"data": { "matched_count": 2, "modified_count": 2 },
"meta": { "request_id": "8e42bc36-efeb-42c1-b99b-41ae9c60aa66" }
}
Errors
On these routes, the type URL in an error doesn't tell errors apart. Branch on status.
| Status | When | What to do |
|---|---|---|
400 |
Renaming without label (Tag must have at least 1 character.). |
Send the tag's label, even if it hasn't changed. |
400 |
tag_ids is missing or empty. |
Send an array with at least one id. |
404 |
The tag doesn't exist or is in another account. | Check the id with List your tags. |
For everything else, see Responses, errors and limits.