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.

Code samples

The requests from this page, ready to copy. Set DC_KEY and DC_SECRET to your API key pair first.

List your tags
curl "https://api-v2.dropcowboy.com/tag/public/tags?search_term=lead" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Create a tag
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" }'
Rename, recolor, or describe a tag
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" }'
Delete a tag
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"
Delete several tags at once
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"] }'