Tags

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 documents: payables, credit notes (in any status)
Accounts receivable documents: invoices, quotes, credit notes (in any status)
Counterparts
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, this organization user must have a role with the tag permission. If a partner-level token 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:

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:

{
  "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.

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

Some examples:

Payable
Receivables: create invoice
Receivables: update invoice
Counterpart

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"
       ]
     }'

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"
       ]
     }'

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.

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"
         ]
       }
     }'

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"
       ]
     }'

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.

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. 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:

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
      }
    ]
  }'

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.

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 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 (AND) and 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:

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:

{
  "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} and provide the new values in the request body:

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} to delete an existing tag by its ID. This tag will be automatically deleted from all objects where it is used.

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'

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Overview

Roles and permissions

Create a tag

Assign tags to an object

Tag auto-assignment for payables

Find and filter objects by tags

List all tags

Update a tag

Delete a tag

​Overview

​Roles and permissions

​Create a tag

​Assign tags to an object

​Tag auto-assignment for payables

​Find and filter objects by tags

​List all tags

​Update a tag

​Delete a tag

Overview

Roles and permissions

Create a tag

Assign tags to an object

Tag auto-assignment for payables

Find and filter objects by tags

List all tags

Update a tag

Delete a tag