> This page is for version v2024-05-25 (default).
> For other versions, use one of these documentation indexes:
> - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt
> - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt
> - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# Tags

## Overview

Some objects in Monite 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](../accounts-payable/index) documents: payables, credit notes (in any status)
* [Accounts receivable](../accounts-receivable/index) documents: invoices, quotes, credit notes (in any status)
* [Counterparts](./counterparts/index)
* [Projects](./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 \[#permissions]

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

If a [partner-level token](../../get-started/credentials#generate-partner-token) is used, no special permissions are needed.

## Create a tag \[#create]

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

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/tags' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_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}
{
  "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 \[#assign]

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

Some examples:

#### Payable

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/b9503...20b' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "tag_ids": [
         "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
         "a6041f76-8f4a-4494-8c59-2f32fe0d971c"
       ]
     }'
```

#### Receivables: create invoice

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/receivables' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_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"
       ]
     }'
```

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

```sh {7}
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/d4e2d...bd1' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_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"
         ]
       }
     }'
```

#### Counterpart

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/counterparts/c04d69...b12' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "tag_ids": [
         "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
         "a6041f76-8f4a-4494-8c59-2f32fe0d971c"
       ]
     }'
```

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

## Tag auto-assignment for payables \[#auto-assignment]

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

Additionally, you must specify a set of keywords that Monite will use to search within the created payables. Monite 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
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/{entity_id}/settings' \
  -H 'X-Monite-Version: 2024-05-25' \
  -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.

## Find and filter objects by tags \[#find-filter]

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`](/api/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`](/api/receivables/get-receivables#request.query.tag_ids) (AND) and [`tag_ids__in`](/api/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 \[#list-all]

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

```sh
curl GET 'https://api.sandbox.monite.com/v1/tags' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

You will get a list of tag names and IDs:

```json
{
  "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 \[#update]

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

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/tags/ea837...1f5' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"name": "Website"}'
```

## Delete a tag \[#delete]

Call [`DELETE /tags/{tag_id}`](/api/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
curl -X DELETE 'https://api.sandbox.monite.com/v1/tags/ea837...1f5' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```