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

# Tags

> Learn how to add tags to your objects and have more control over your workflows.

## Overview

Some objects in Tesouro can have custom tags assigned to them, such as "Travel expenses" or "Events". Tags are useful for improving organization, reporting, and workflows by enabling detailed categorization and tracking.

You can assign tags to:

* [Accounts payable](/finops/guides/accounts-payable/index) documents: payables, credit notes (in any status)
* [Accounts receivable](/finops/guides/accounts-receivable/index) documents: invoices, quotes, credit notes (in any status)
* [Counterparts](/finops/guides/common/counterparts/index)
* [Projects](/finops/guides/common/projects)

Tag names are case-sensitive, so `Marketing` and `marketing` are two different tags.

Tags can optionally have a category and description. The available categories are `document_type`, `department`, `project`, `cost_center`, `vendor_type`, `payment_method`, and `approval_status`.

## Roles and permissions

To create and manage tags using an [organization user token](/finops/guides/organizations/users#get-organization-user-token), this organization user must have a role with the `tag` [permission](/finops/api/concepts/permissions).

If a [partner-level token](/finops/guides/authentication/client-credentials) is used, no special permissions are needed.

## Create a tag

Before you can add tags to an object, you need to create these tags in Tesouro. To create a tag, call [`POST /tags`](/finops/reference/openapi/tags/post-tags):

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/tags' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d {
       "category": "department",
       "name": "Marketing",
       "description": "Tag for the Marketing Department"
     }
```

The response contains the ID assigned to this tag name:

```json {2} lines theme={null}
{
  "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
  "created_at": "2022-09-07T16:35:18.484507+00:00",
  "updated_at": "2022-09-07T16:35:18.484507+00:00",
  "category": "department",
  "created_by_entity_user_id": "2735282a-bc63-4848-b8c2-5a0577a130fd",
  "description": "Tag for the Marketing Department",
  "name": "Marketing"
}
```

## Assign tags to an object

You can assign tags to objects both when creating new objects and updating existing objects.
Provide the tag IDs in the `tag_ids` list in the request body of the create or update request.

<Tip>Tags can be assigned to payables and receivables in any status (not just draft).</Tip>

Some examples:

<Tabs>
  <Tab title="Payable">
    ```sh lines theme={null}
    curl -X PATCH 'https://api.sandbox.tesouro.com/v1/payables/b9503...20b' \
         -H 'X-Finops-Version: 2025-06-23' \
         -H 'X-Organization-Id: ORGANIZATION_ID' \
         -H 'Authorization: Bearer ACCESS_TOKEN' \
         -H 'Content-Type: application/json' \
         -d '{
           "tag_ids": [
             "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
             "a6041f76-8f4a-4494-8c59-2f32fe0d971c"
           ]
         }'
    ```
  </Tab>

  <Tab title="Receivables: create invoice">
    ```sh lines theme={null}
    curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables' \
         -H 'X-Finops-Version: 2025-06-23' \
         -H 'X-Organization-Id: ORGANIZATION_ID' \
         -H 'Authorization: Bearer ACCESS_TOKEN' \
         -H 'Content-Type: application/json' \
         -d '{
           "type": "invoice",
           ...
           "tag_ids": [
             "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
             "a6041f76-8f4a-4494-8c59-2f32fe0d971c"
           ]
         }'
    ```
  </Tab>

  <Tab title="Receivables: update invoice">
    <Note>
      Unlike POST requests, the PATCH receivable payload uses a wrapper key that depends on the document
      type: `invoice` for draft invoices, `issued_invoice` for non-draft invoices, `quote` for quotes,
      and `credit_note` for credit notes.
    </Note>

    ```sh {7} lines theme={null}
    curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/d4e2d...bd1' \
         -H 'X-Finops-Version: 2025-06-23' \
         -H 'X-Organization-Id: ORGANIZATION_ID' \
         -H 'Authorization: Bearer ACCESS_TOKEN' \
         -H 'Content-Type: application/json' \
         -d '{
           "invoice": {
             "tag_ids": [
               "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
               "a6041f76-8f4a-4494-8c59-2f32fe0d971c"
             ]
           }
         }'
    ```
  </Tab>

  <Tab title="Counterpart">
    ```sh lines theme={null}
    curl -X PATCH 'https://api.sandbox.tesouro.com/v1/counterparts/c04d69...b12' \
         -H 'X-Finops-Version: 2025-06-23' \
         -H 'X-Organization-Id: ORGANIZATION_ID' \
         -H 'Authorization: Bearer ACCESS_TOKEN' \
         -H 'Content-Type: application/json' \
         -d '{
           "tag_ids": [
             "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
             "a6041f76-8f4a-4494-8c59-2f32fe0d971c"
           ]
         }'
    ```
  </Tab>
</Tabs>

<Warning>
  When updating existing objects, the provided `tag_ids` list **replaces** the old tags rather than appends tags. In other words:

  * To add new tags, include both the old and new tags in the `tag_ids` list.
  * To remove tags, provide the `tag_ids` list containing the tags you want to keep - or an empty array `[]` if you want to remove all tags.
</Warning>

## Tag auto-assignment for payables

You can define sets of specific tags to be automatically assigned to new payables created via OCR. This feature must be enabled via the organization setting [`payables_ocr_auto_tagging`](/finops/reference/openapi/identity/patch-organizations-id-settings#request.body.payables_ocr_auto_tagging).

Additionally, you must specify a set of keywords that Tesouro will use to search within the created payables. Tesouro searches by substring and is case-insensitive. When one of these keywords is detected during the OCR process, the corresponding tag will be automatically assigned to the payable:

```sh expandable lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/{organization_id}/settings' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payables_ocr_auto_tagging": [
      {
        "tag_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "keywords": [
          "Marketing",
          "Website"
        ],
        "enabled": true
      },
      {
        "tag_id": "1ef5d605-2847-4a8a-9ef9-09576c68805b",
        "keywords": [
          "FR"
        ],
        "enabled": false
      }
    ]
  }'
```

<Info>
  Tag auto-assignment only applies to payables successfully scanned by the OCR. When manually
  creating or editing a payable, the tags are not added automatically.
</Info>

## Find and filter objects by tags

When querying taggable objects, you can provide a list of tags to use as a filter.

* `/payables` and `/payable-credit-notes` endpoints support the [`tag_ids`](/finops/reference/openapi/payables/get-payables#request.query.tag_ids) filter that works as OR.
  * `GET /payables?tag_ids=TAG_1&tag_ids=TAG_2` returns payables that contain at least one of TAG\_1 or TAG\_2.

* `/receivables` endpoints support the [`tag_ids`](/finops/reference/openapi/receivables/get-receivables#request.query.tag_ids) (AND) and [`tag_ids__in`](/finops/reference/openapi/receivables/get-receivables#request.query.tag_ids__in) (OR) filters.
  * `GET /receivables?tag_ids=TAG_1&tag_ids=TAG_2` returns receivables that contain both TAG\_1 and TAG\_2.
  * `GET /receivables?tag_ids__in=TAG_1&tag_ids__in=TAG_2` returns receivables that contain at least one of TAG\_1 or TAG\_2.

* `GET /counterparts` supports the `tag_ids__in` filter that works as OR.

## List all tags

To list all existing tags, call [`GET /tags`](/finops/reference/openapi/tags/get-tags):

```sh lines theme={null}
curl GET 'https://api.sandbox.tesouro.com/v1/tags' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

You will get a list of tag names and IDs:

```json lines theme={null}
{
  "data": [
    {
      "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
      "created_at": "2022-09-07T16:35:18.484507+00:00",
      "updated_at": "2022-09-07T16:35:18.484507+00:00",
      "category": "department",
      "created_by_entity_user_id": "2735282a-bc63-4848-b8c2-5a0577a130fd",
      "description": "Tag for the Marketing Department",
      "name": "Marketing"
    }
  ],
  "next_pagination_token": "eyJvcmRlciI6ImFzYyIs",
  "prev_pagination_token": null
}
```

## Update a tag

You can rename existing tags as well as change their category and description.
To update a tag, call [`PATCH /tags/{tag_id}`](/finops/reference/openapi/tags/patch-tags-id) and provide the new values in the request body:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/tags/ea837...1f5' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"name": "Website"}'
```

## Delete a tag

Call [`DELETE /tags/{tag_id}`](/finops/reference/openapi/tags/delete-tags-id) to delete an existing tag by its ID. This tag will be automatically deleted from all objects where it is used.

```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/tags/ea837...1f5' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```