Tags

Tags label prospects. Every workspace shares five built-in tags (Hot, Warm, Cold, Follow up, Do not contact) that cannot be changed, and can add up to 200 of its own.

Endpoint	Description
`GET /v1/tags`	List built-in and workspace tags with usage counts (`include_inactive=true` shows archived ones)
`POST /v1/tags`	Create a workspace tag
`GET /v1/tags/{id}`	Get one tag
`PATCH /v1/tags/{id}`	Rename, describe, recolor, reorder, or archive
`DELETE /v1/tags/{id}`	Delete (`?force=true` removes it from prospects first)
`POST /v1/tags/reorder`	Set display order

To put tags on a prospect, see Tags on a Prospect.

body namestringrequired

Up to 100 characters, unique in the workspace.

body descriptionstring

Up to 255 characters.

body badge_variantstringdefault: secondary

default, secondary, info, warning, or destructive.

body sort_orderinteger

Lower sorts first.

body is_activeboolean

PATCH only: false archives the tag without removing it from prospects.

Request example

1234curl -X POST "https://api.v2.dealmachine.com/v1/tags" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Probate", "badge_variant": "info" }'

Response example

1234567891011121314{
  "data": {
    "id": "tag_212",
    "name": "Probate",
    "description": null,
    "badge_variant": "info",
    "is_system": false,
    "is_active": true,
    "sort_order": 1000,
    "usage_count": 0,
    "created_at": "2026-08-26T16:40:00.000Z",
    "updated_at": "2026-08-26T16:40:00.000Z"
  }
}