Schedule a pilot

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.