Tags

Caution

Tag endpoints require the tags:read, tags:write, or tags:delete permissions respectively.

Overview

Tags are organization-scoped labels used to categorize contacts. Each tag has a unique name and a predefined color. Tags are identified by their name in the URL path (not a UUID), so renaming or deleting a tag is done via /api/tags/{name}.

Note

A tag's identity is its name. Path parameters must be URL-encoded (e.g. a tag named VIP customer becomes /api/tags/VIP%20customer).

Valid colors are: blue, red, green, yellow, purple, gray. An empty color defaults to gray.

List Tags

Get all tags in your organization.

GET /api/tags

Query Parameters

Parameter	Type	Description
search	string	Case-insensitive filter by tag name or color
page	integer	Page number (default 1)
limit	integer	Results per page

Response

{
  "status": "success",
  "data": {
    "tags": [
      {
        "name": "VIP",
        "color": "purple",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Create Tag

Create a new tag.

POST /api/tags

Request Body

{
  "name": "VIP",
  "color": "purple"
}

Field	Type	Required	Description
name	string	Yes	Unique tag name (max 50 characters)
color	string	No	One of blue, red, green, yellow, purple, gray (defaults to gray)

Response

{
  "status": "success",
  "data": {
    "name": "VIP",
    "color": "purple",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Caution

Creating a tag with a name that already exists returns 409 Conflict.

Update Tag

Update a tag's name and/or color. If the name changes, every contact using the old tag is updated to reference the new name.

PUT /api/tags/{name}

Request Body

{
  "name": "VIP Customer",
  "color": "blue"
}

Field	Type	Required	Description
name	string	No	New tag name (max 50 characters). Omit to keep the current name
color	string	No	New color. Omit to keep the current color

Response

{
  "status": "success",
  "data": {
    "name": "VIP Customer",
    "color": "blue",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-02T00:00:00Z"
  }
}

Delete Tag

Delete a tag. The tag is also removed from every contact that references it.

DELETE /api/tags/{name}

Response

{
  "status": "success",
  "data": {
    "message": "Tag deleted"
  }
}

See Also

• Contacts API - Assign tags to contacts via PUT /api/contacts/{id}/tags