Tags

Overview

Payables can have custom tags assigned to them, such as "Travel expenses" or "Events". Tags are useful when using approval policies, as an approval policy can be configured to apply only to payables with a specific set of tags.

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 payables, you have to create those tags in Monite. To create a tag, call POST /tags:

curl -X POST 'https://api.sandbox.monite.com/v1/tags' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -d {
       "category": "department",
       "description": "Tag for the Marketing Department",
       "name": "Marketing"
     }

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

Add tags to a payable

Once you have a tag ID, add it to the payable's tag_ids list by calling PATCH /payables/{payable_id}:

curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/{payable_id}' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -d '{
     "tag_ids": [
       "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
       ],
     }'

⚠️
If the payable 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

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:

curl -X PATCH "https://api.sandbox.monite.com/v1/entities/{entity_id}/settings" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "x-monite-version: 2024-01-31" \
-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
    }
  ]
}'

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

curl GET 'https://api.sandbox.monite.com/v1/tags' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_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": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
      "description": "Tag for the Marketing Department",
      "name": "Marketing"
    }
  ],
  "prev_pagination_token": "eyJvcmRlciI6ImFzYyIs",
  "next_pagination_token": "eyJvcmRlciI6ImFzYyIs"
}

Update a tag

Call PATCH /tags/{tag_id} and provide the new value in the request body:

curl -X PATCH 'https://api.sandbox.monite.com/v1/tags/{tag_id}' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -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 payables where it is used.

curl -X DELETE 'https://api.sandbox.monite.com/v1/tags/{tag_id}' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'