---
title: "Tags API · COUNT Partner API"
description: "Tags are workspace labels used to classify transactions, journal entries, invoices, bills, and other records. Tag groups organize related tags — each tag may…"
canonical: "https://developers.getcount.com/reference/tags"
source: "https://developers.getcount.com/reference/tags"
---
API Reference

# Tags

Tags are workspace labels used to classify transactions, journal entries, invoices, bills, and other records. Tag groups organize related tags — each tag may belong to at most one group.

Last updated 2026-06-21

## Overview

The Tags API covers both individual tags and tag groups. Tags are simple name labels; tag groups bundle tags under a named, optionally colored container for structured reporting.

Partner responses expose UUIDs as `id`. When creating or updating tag groups, pass `tagUuids` (from list tags) — the server resolves UUIDs to internal ids. A tag can belong to at most one group at a time.

## Key concepts

### Tags vs tag groups

Tags are flat labels. Tag groups collect tags for UI grouping and reporting. Manage tags at `/partners/tags` and groups at `/partners/tags/groups`.

### One group per tag

Each tag may belong to at most one group. Assigning a tag that is already in another group returns 400.

### Group membership replacement

On tag group update, sending `tagUuids` replaces the entire membership set — tags omitted are removed from the group. Pass `[]` to clear all tags.

### Idempotent tag create

Creating a tag with a name that already exists returns the existing tag rather than duplicating it.

## The tag object

Fields returned on a tag. Tag groups embedding the tag may appear under `tagGroups`.

#### Attributes

`id` uuid

Tag identifier (UUID).

`name` string

Tag label. Required and unique per workspace on create.

`tagGroups` array

Tag groups this tag belongs to (at most one in practice).

`id` uuid

Tag group UUID.

`name` string

Group name.

`color` string

Group color.

`createdAt` datetime

ISO 8601 creation timestamp.

`updatedAt` datetime

ISO 8601 last update timestamp.

Example

```json
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "name": "Office",
  "tagGroups": [
    {
      "id": "f6a7b8c9-d0e1-2345-fabc-456789012346",
      "name": "Department",
      "color": "#4A90D9"
    }
  ],
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-28T14:22:30.000Z"
}
```

List tag groups includes ungrouped tags

GET /partners/tags/groups returns both `tagGroups` and `unGroupedTags` — tags not assigned to any group.

Deleting a tag removes associations

Deleting a tag clears its links to transactions, journal entries, invoices, bills, and other tagged records.

## Related

- [Transactions API](https://developers.getcount.com/reference/transactions)
- [Journal Entries API](https://developers.getcount.com/reference/journal-entries)

## Recent changes

2026-09-07

Accounting Playbooks and Ledger Semantics published as documentation

The workflows and behaviour rules the MCP server serves to agents through COUNT_playbooks and COUNT_knowledge are now readable documentation. Accounting Playbooks (/guides/playbooks) covers nine ordered workflows across 54 steps — invoicing, credit memos, recurring templates, vendor bill payment, chart-of-accounts setup, migration imports, budget planning and round-trip, and month-end review — each naming the exact tool per step. Ledger Semantics & Lifecycles (/guides/ledger-semantics) documents 33 confirmed behaviours across twelve resources: the state each operation is valid in, the fields accepted and then ignored, and the calls that cannot be undone, with every irreversible behaviour collected in one table at the top of the page. Both pages carry the COUNT_playbooks and COUNT_knowledge ids they were ported from so the agent-facing and human-facing copies stay in step. Playbooks, lifecycle sections, and individual behaviour rules are indexed into site search.

2026-06-21

Complete Partner API reference

Documented all remaining API reference groups: Chart of Accounts, Vendors, Products & Services, Recurring Invoice Templates, Credit Memos, Bills, Journal Entries, Tags, People, Projects, Tasks, Time Entries, Expense Receipts, Reports, and Workspace Stats. Added missing invoice endpoints (audit log, attachments, credit application, remove transaction) and group overviews for Invoices and Transactions.

## Endpoints

[GET List tags `/partners/tags` Returns all tags in the workspace.](https://developers.getcount.com/reference/tags/list-tags) [GET Get tag `/partners/tags/{uuid}` Retrieves a single tag by UUID.](https://developers.getcount.com/reference/tags/get-tag) [POST Create tag `/partners/tags` Creates a tag in the workspace.](https://developers.getcount.com/reference/tags/create-tag) [PATCH Update tag `/partners/tags/{uuid}` Updates a tag name by UUID.](https://developers.getcount.com/reference/tags/update-tag) [DELETE Delete tag `/partners/tags/{uuid}` Deletes a tag and removes all of its associations.](https://developers.getcount.com/reference/tags/delete-tag) [GET List tag groups `/partners/tags/groups` Returns all tag groups and tags not assigned to any group.](https://developers.getcount.com/reference/tags/list-tag-groups) [GET Get tag group `/partners/tags/groups/{uuid}` Retrieves a single tag group by UUID with its member tags.](https://developers.getcount.com/reference/tags/get-tag-group) [POST Create tag group `/partners/tags/groups` Creates a tag group and optionally assigns tags.](https://developers.getcount.com/reference/tags/create-tag-group) [PATCH Update tag group `/partners/tags/groups/{uuid}` Updates a tag group name, color, and/or membership.](https://developers.getcount.com/reference/tags/update-tag-group) [DELETE Delete tag group `/partners/tags/groups/{uuid}` Deletes a tag group. Member tags are not deleted.](https://developers.getcount.com/reference/tags/delete-tag-group)