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

Create a tag

Before you can add tags to payables, you need to create those tags in Monite. To create a tag, call POST /tags with the request body containing the tag name:

curl -X POST 'https://api.sandbox.monite.com/v1/tags' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -d '{"name": "Travel expenses"}'

The response contains the ID assigned to this tag name:

{
  "name": "Travel expenses",
  "id": "b8636e1c-218e-400a-9711-f8fb94d7663a",
  "created_at": "2022-09-07T16:35:18.484507+00:00",
  "updated_at": "2022-09-07T16:35:18.484507+00:00",
  "created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
}

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: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -d '{
      "tags": [
        {
          "name": "Marketing",
          "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",
          "created_by_entity_user_id": "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).

List all tags

To list all existing tags, call GET /tags:

curl GET 'https://api.sandbox.monite.com/v1/tags' \
     -H 'X-Monite-Version: 2023-03-14' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

You will get a list of tag names and IDs:

{
  "data": [
    {
      "name": "Marketing",
      "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",
      "created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
    }
  ],
  "prev_pagination_token": "eyJvcmRlciI6ImFzYyIs",
  "next_pagination_token": "eyJvcmRlciI6ImFzYyIs"
}

Rename a tag

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

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

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