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 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 entity user token, this entity 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 Monite. To create a tag, call POST /tags:

1
curl -X POST 'https://api.sandbox.monite.com/v1/tags' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d {
7
       "category": "department",
8
       "name": "Marketing",
9
       "description": "Tag for the Marketing Department"
10
     }

The response contains the ID assigned to this tag name:

1
{
2
  "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
3
  "created_at": "2022-09-07T16:35:18.484507+00:00",
4
  "updated_at": "2022-09-07T16:35:18.484507+00:00",
5
  "category": "department",
6
  "created_by_entity_user_id": "2735282a-bc63-4848-b8c2-5a0577a130fd",
7
  "description": "Tag for the Marketing Department",
8
  "name": "Marketing"
9
}

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.

Some examples:

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

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 entity setting 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:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/{entity_id}/settings' \
2
  -H 'X-Monite-Version: 2024-05-25' \
3
  -H 'Authorization: Bearer ACCESS_TOKEN' \
4
  -H 'Content-Type: application/json' \
5
  -d '{
6
    "payables_ocr_auto_tagging": [
7
      {
8
        "tag_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
9
        "keywords": [
10
          "Marketing",
11
          "Website"
12
        ],
13
        "enabled": true
14
      },
15
      {
16
        "tag_id": "1ef5d605-2847-4a8a-9ef9-09576c68805b",
17
        "keywords": [
18
          "FR"
19
        ],
20
        "enabled": false
21
      }
22
    ]
23
  }'

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:

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

You will get a list of tag names and IDs:

1
{
2
  "data": [
3
    {
4
      "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
5
      "created_at": "2022-09-07T16:35:18.484507+00:00",
6
      "updated_at": "2022-09-07T16:35:18.484507+00:00",
7
      "category": "department",
8
      "created_by_entity_user_id": "2735282a-bc63-4848-b8c2-5a0577a130fd",
9
      "description": "Tag for the Marketing Department",
10
      "name": "Marketing"
11
    }
12
  ],
13
  "next_pagination_token": "eyJvcmRlciI6ImFzYyIs",
14
  "prev_pagination_token": null
15
}

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:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/tags/ea837...1f5' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -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.

1
curl -X DELETE 'https://api.sandbox.monite.com/v1/tags/ea837...1f5' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'