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. To find properties by tag, use the Tags filter with these tag IDs, and add the tags export field to list them in an export.

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