# Tags

> Organize entities with tag groups and tags — departments, projects, locations.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/tags
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# Tags

Tags let you categorize and segment entities (transactions, invoices, bills, journal entries, customers, vendors, products, projects, contracts) by custom dimensions like department, project, or location.

## Concepts

- **Tag Group** — A category of tags (e.g., "Department", "Project", "Location")
- **Tag** — A specific value within a group (e.g., "Engineering", "Q1 Launch")
- **Entity Tag** — The link between a tag and a specific entity, identified by `model_type` + `model_id`

## Tag Groups

### Create a Tag Group

```bash
curl -X POST "https://api.ondayzero.com/api/v1/tag-groups" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "Department", "description": "Cost-center segmentation"}'
```

### List Tag Groups

```bash
curl "https://api.ondayzero.com/api/v1/tag-groups" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

`PUT` / `DELETE /api/v1/tag-groups/{tag_group_id}` rename or remove a group.

## Tags

### Create a Tag

```bash
curl -X POST "https://api.ondayzero.com/api/v1/tags" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "tag_group_id": "TAG_GROUP_UUID"
  }'
```

`tag_group_id` is optional — ungrouped tags work too, but grouped tags are what segmented reports use.

### List Tags

```bash
curl "https://api.ondayzero.com/api/v1/tags?tag_group_id=TAG_GROUP_UUID&search=eng" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

`POST /api/v1/tags/suggest` with `{"context": "SaaS startup, 12 people", "existing_tags": ["Engineering"]}` returns AI-suggested tag names.

## Tagging Entities

### Attach a Tag

```bash
curl -X POST "https://api.ondayzero.com/api/v1/entity-tags" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id": "TAG_UUID",
    "model_type": "transaction",
    "model_id": "ENTITY_UUID"
  }'
```

### Supported `model_type` values

`transaction`, `invoice`, `bill`, `journal_entry`, `line_entry`, `customer`, `vendor`, `product`, `project`, `contract`

### View Tags on an Entity

```bash
curl "https://api.ondayzero.com/api/v1/entity-tags/transaction/{model_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

For many entities at once, `POST /api/v1/entity-tags/batch` with `{"model_type": "transaction", "model_ids": ["UUID_1", "UUID_2"]}` returns the tags for each.

### Detach a Tag

```bash
curl -X DELETE "https://api.ondayzero.com/api/v1/entity-tags/{tag_id}/transaction/{model_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Bulk Operations

Attach several tags to one entity:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/entity-tags/bulk-attach" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model_type": "transaction",
    "model_id": "ENTITY_UUID",
    "tag_ids": ["TAG_UUID_1", "TAG_UUID_2"]
  }'
```

Attach tags to many entities in one call:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/entity-tags/bulk-attach-many" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model_type": "transaction",
    "model_ids": ["UUID_1", "UUID_2", "UUID_3"],
    "tag_ids": ["TAG_UUID"]
  }'
```

`POST /api/v1/entity-tags/bulk-detach` takes the same shape as `bulk-attach` and removes the tags instead.

### Find Entities by Tag

```bash
curl "https://api.ondayzero.com/api/v1/tags/{tag_id}/entities/transaction?limit=50" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

Returns the tagged entities of that `model_type`, cursor-paginated. Transaction lists also accept `tag_id` as a filter directly (`GET /api/v1/transactions?tag_id=…`).

## Tag-Based Reports

Tags power the **P&L by Department** report. Create a "Department" tag group, tag your transactions, and generate `pnl_by_department` with `tag_group_id` (one sheet per tag) or specific `tag_ids` via the [Reports API](/docs/guides/reports).