Practice Manager API
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-11-18
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 `/firm-partners/workspace/tags` and groups at `/firm-partners/workspace/tags/groups`.
Where tags go
Bills take tags per line in `lineItems[].tagUuids`, which code that line's expense and tax postings, and bill-level `tagUuids`, which apply to every posting. Manual journal entries take tags per line in `lines[].tagUuids`. Invoices, credit memos and recurring invoice templates take `tagUuids` for the whole document only.
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
iduuidTag identifier (UUID).
namestringTag label. Required and unique per workspace on create.
tagGroupsarrayTag groups this tag belongs to (at most one in practice).
iduuidTag group UUID.
namestringGroup name.
colorstringGroup color.
createdAtdatetimeISO 8601 creation timestamp.
updatedAtdatetimeISO 8601 last update timestamp.
{
"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 /firm-partners/workspace/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
Endpoints
/firm-partners/workspace/tagsReturns all tags in the workspace.
/firm-partners/workspace/tags/{uuid}Retrieves a single tag by UUID.
/firm-partners/workspace/tagsCreates a tag in the workspace.
/firm-partners/workspace/tags/{uuid}Updates a tag name by UUID.
/firm-partners/workspace/tags/{uuid}Deletes a tag and removes all of its associations.
/firm-partners/workspace/tags/groupsReturns all tag groups and tags not assigned to any group.
/firm-partners/workspace/tags/groups/{uuid}Retrieves a single tag group by UUID with its member tags.
/firm-partners/workspace/tags/groupsCreates a tag group and optionally assigns tags.
/firm-partners/workspace/tags/groups/{uuid}Updates a tag group name, color, and/or membership.
/firm-partners/workspace/tags/groups/{uuid}Deletes a tag group. Member tags are not deleted.
