> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getasset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tagging

### **Overview**

Tags let you label [Business](/getstarted/CoreConcepts#businesses-your-smb-customers) 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:

1. **Define tag fields** (the dimensions you want to tag by).
2. **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](/api-reference/tenant/list-global-tag-fields) — `GET /v0/tenant/tag-fields`
* [Create a global Tag Field](/api-reference/tenant/create-a-global-tag-field) — `POST /v0/tenant/tag-fields`
* [Update a global Tag Field](/api-reference/tenant/update-a-global-tag-field) — `PATCH /v0/tenant/tag-fields/{tag_field_id}`
* [Delete a global Tag Field](/api-reference/tenant/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](/api-reference/tag/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](/api-reference/schema/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](/api-reference/schema/tag-value)** for that business:

* [Create a Tag Value](/api-reference/tag/create-a-tag-value) — `POST /v0/business/{business_id}/tag-values`
* [List Tag Values for a Business](/api-reference/tag/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"`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "Job": null
}
```

**Examples of entities that support `tags`**

* [Transactions](/api-reference/transaction/create-transactions) (inline tags on transaction payloads)
* [Journal Entry](/api-reference/journal-entry/create-a-journal-entry) line entries (`tags` on lines)
* [Invoices](/api-reference/invoice/create-an-invoice) (`tags` on create/update)
* [Bills](/api-reference/bill/create-bills) (`tags` on create/update)

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

<Note>
  Questions? Reach out via our [Contact
  form](https://www.getasset.com/get-in-touch).
</Note>