Tagging - Asset API Documentation

Overview

Tags let you label Business data with structured dimensions (for example Job, Location, or Department) so you can filter, report, and automate workflows consistently across entities. Tagging is a two-step process:

Define tag fields (the dimensions you want to tag by).
Set tag values on entities that support tagging (assign or remove values using each entity’s tags field in the API).

Step 1: Create tag fields

A tag field is the name of a dimension (for example "Job"). Tag fields fall into two scopes:

Scope	What it means
Global tag fields	Created at the tenant level. Every business under the tenant can use these fields.
Business tag fields	Created for one specific business. Only that business uses them (for example a field that does not apply tenant-wide).

API (global tag fields)

List global Tag Fields — GET /v0/tenant/tag-fields
Create a global Tag Field — POST /v0/tenant/tag-fields
Update a global Tag Field — PATCH /v0/tenant/tag-fields/{tag_field_id}
Delete a global Tag Field — DELETE /v0/tenant/tag-fields/{tag_field_id}

API (see fields available to a business)

List Tag Fields for a Business — GET /v0/business/{business_id}/tag-fields
Use this to discover which tag fields apply to a given business (including global fields and business-specific fields).

The Tag Field object describes the shape returned by the API. Optional: predefined tag values If you want a controlled list of allowed values for a field (instead of only free-form values created when tagging), create Tag Values for that business:

Create a Tag Value — POST /v0/business/{business_id}/tag-values
List Tag Values for a Business — GET /v0/business/{business_id}/tag-values

Step 2: Tag entities

After the tag field exists, set tags on any entity that supports tagging by sending a tags object on create or update requests. Simple Tagging Shape

Keys are tag field names (strings), for example "Job" or "Location".
Values are tag value names (strings), for example "job-123" or "NYC".

{
  "Job": "job-123",
  "Location": "NYC"
}

The tag field must already exist for that business. If the value string does not exist yet, the API can create the tag value automatically when you save the entity (see entity-specific API docs for details). Advanced Tagging There are times in which you want to split an entitiy across multiple tags. For example, let’s say that you pay for a software license that costs $500 for two business locations (NYC and LA), and you want to split the expense across the two. You can achieve that by specifying a tag object that contains the tag value and amount. Example:

{
  "Location": [
    {"value": "NYC", "amount": "300.00"},
    {"value": "LA", "amount": "300.00"}
  ]
}

Removing a tag On update payloads that support merge semantics for tags, set the field’s value to null to clear that tag on the entity. Keys you omit are typically left unchanged.

{
  "Job": null
}

Examples of entities that support tags

Transactions (inline tags on transaction payloads)
Journal Entry line entries (tags on lines)
Invoices (tags on create/update)
Bills (tags on create/update)

Check the request schema for each endpoint: if it includes a tags property, you can use the pattern above.

Questions? Reach out via our Contact form.

​Overview

​Step 1: Create tag fields

​Step 2: Tag entities

Overview

Step 1: Create tag fields

Step 2: Tag entities