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

List your tags

Returns your tags, newest first. Without limit you get all of them.

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",
      "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

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", "color": "#E11D48", "text_color": "#FFFFFF" }'

The response is 201 with the new tag.

{
  "data": {
    "tag_id": "fbd9fdcb-59ac-42ba-991e-3b469b9df791",
    "label": "Hot lead",
    "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 or recolor a tag

Changes the label, colors or both. Always send label, even when you only change a color. Contacts that have the tag show the change.

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.

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.

For everything else, see Responses, errors and limits.