Tags

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

Overview

Payables, receivables, and counterparts 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.

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

Optionally, you can set the tag to a category and description. The available categories are document_type, department, project, cost_center, vendor_type, payment_method, and approval_status.

Create a tag

Before you can add tags to an object, you have to create those tags in Monite. To create a tag, call POST /tags:

1curl -X POST 'https://api.sandbox.monite.com/v1/tags' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5     -d {
6       "category": "department",
7       "description": "Tag for the Marketing Department",
8       "name": "Marketing"
9     }

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": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
7  "description": "Tag for the Marketing Department",
8  "name": "Marketing"
9}

Add tags to an object

Once you have a tag ID, add it to the list of tags of the object’s tag_ids list by sending a PATCH request to the:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/{payable_id}' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5     -d '{
6     "tag_ids": [
7       "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
8       ],
9     }'

If the object in question already has some tags, the tag_ids list in the request body must specify both the existing and new tags (since the PATCH request replaces the tag_ids list rather than appends to it).

Tags 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 in the entity settings via the payables_ocr_auto_tagging field.

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:

1curl -X PATCH "https://api.sandbox.monite.com/v1/entities/{entity_id}/settings" \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
4  -H "X-Monite-Version: 2023-09-01" \
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  }'
The tags auto-assignment only applies to payables successfully scanned by the OCR. When manually creating/editing a payable, the tags are not added automatically.

List all tags

To list all existing tags, call GET /tags:

1curl GET 'https://api.sandbox.monite.com/v1/tags' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_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": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
9      "description": "Tag for the Marketing Department",
10      "name": "Marketing"
11    }
12  ],
13  "prev_pagination_token": "eyJvcmRlciI6ImFzYyIs",
14  "next_pagination_token": "eyJvcmRlciI6ImFzYyIs"
15}

Update a tag

To update a tag, call PATCH /tags/{tag_id} and provide the new value in the request body:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/tags/{tag_id}' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5     -d '{"name": "Website"}'

The description and category fields can also be updated.

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:

1curl -X DELETE 'https://api.sandbox.monite.com/v1/tags/{tag_id}' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'