Skip to main content
Skip to Content

Tags API

Tags help you categorize and filter companies, projects, tickets, and other resources. Create custom tags for industries, service types, priorities, or any classification that fits your workflow.

The Tag Object

{
  "id": "tag_cuid123456",
  "name": "Enterprise",
  "slug": "enterprise",
  "color": "#8B5CF6",
  "description": "Enterprise-tier companies",
  "usage_count": 24,
  "created_at": "2025-06-15T10:00:00Z"
}

Tag Fields

FieldTypeDescription
idstringUnique identifier (prefix: tag_)
namestringRequired. Tag display name
slugstringURL-safe identifier (auto-generated)
colorstringHex color code
descriptionstringTag description
usage_countintegerNumber of resources using this tag
created_atdatetimeWhen created

List Tags

GET/v1/tagsList all tags

Query Parameters

ParameterTypeDescription
searchstringSearch by name
sortstringname, usage_count, created_at

Request

curl "https://api.govantage.co/v1/tags" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": [
    {
      "id": "tag_enterprise",
      "name": "Enterprise",
      "slug": "enterprise",
      "color": "#8B5CF6",
      "usage_count": 24
    },
    {
      "id": "tag_healthcare",
      "name": "Healthcare",
      "slug": "healthcare",
      "color": "#10B981",
      "usage_count": 12
    },
    {
      "id": "tag_urgent",
      "name": "Urgent",
      "slug": "urgent",
      "color": "#EF4444",
      "usage_count": 8
    }
  ]
}

Create a Tag

POST/v1/tagsCreate a new tag

Request Body

FieldTypeRequiredDescription
namestringYesTag name
colorstringNoHex color (default: auto-assigned)
descriptionstringNoTag description

Request

curl -X POST "https://api.govantage.co/v1/tags" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP",
    "color": "#F59E0B",
    "description": "High-priority companies requiring white-glove service"
  }'

Update a Tag

PUT/v1/tags/:idUpdate a tag
curl -X PUT "https://api.govantage.co/v1/tags/tag_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP",
    "color": "#EAB308"
  }'

Delete a Tag

DELETE/v1/tags/:idDelete a tag

Deleting a tag removes it from all resources. This cannot be undone.

curl -X DELETE "https://api.govantage.co/v1/tags/tag_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Tag Resources

Add Tags to a Resource

POST/v1/clients/:id/tagsAdd tags to a company

Works for companies, projects, tickets, and contacts.

curl -X POST "https://api.govantage.co/v1/clients/cli_xxxxx/tags" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["enterprise", "healthcare"]
  }'

Remove Tags from a Resource

DELETE/v1/clients/:id/tagsRemove tags from a company
curl -X DELETE "https://api.govantage.co/v1/clients/cli_xxxxx/tags" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["healthcare"]
  }'

Set Tags (Replace All)

PUT/v1/clients/:id/tagsReplace all tags on a company
curl -X PUT "https://api.govantage.co/v1/clients/cli_xxxxx/tags" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["enterprise", "vip"]
  }'

Filter by Tags

Use tags in list queries:

# Companies with "enterprise" tag
curl "https://api.govantage.co/v1/clients?tags=enterprise" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"
 
# Tickets with "urgent" OR "bug" tags
curl "https://api.govantage.co/v1/tickets?tags=urgent,bug" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"
 
# Projects with "enterprise" AND "healthcare" tags
curl "https://api.govantage.co/v1/projects?tags=enterprise&tags=healthcare" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Bulk Tag Operations

Bulk Add Tags

POST/v1/tags/bulk-addAdd tags to multiple resources
curl -X POST "https://api.govantage.co/v1/tags/bulk-add" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "clients",
    "resource_ids": ["cli_xxxxx", "cli_yyyyy", "cli_zzzzz"],
    "tags": ["enterprise"]
  }'

Suggested Tags

GET/v1/tags/suggestionsGet tag suggestions for a resource

AI-powered tag suggestions based on resource content.

curl "https://api.govantage.co/v1/tags/suggestions?resource_type=ticket&resource_id=tkt_xxxxx" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": [
    { "tag": "bug", "confidence": 0.92 },
    { "tag": "urgent", "confidence": 0.78 },
    { "tag": "frontend", "confidence": 0.65 }
  ]
}

Next Steps