Approval policies

Learn how to create and customize the approval policies for payables.

Overview

Automating accounts payable workflows with rules-based decision-making and advanced approval policies reduces manual processes, saving time and minimizing the risk of errors.

Monite allows entities to customize and automate the set of roles and approval conditions to change the payable status according to the business needs of the entity with approval policies.

Some examples of approval policies:

If the payable:

  • was received from a specific counterpart (vendor or supplier),
  • was uploaded by a specific entity user,
  • was uploaded by any user with a specific role,
  • is in a specific currency (such as EUR or USD),
  • has a specific amount to be paid (for example, ≥ 5000 EUR or 100-500 USD),
  • has specific tags assigned to it,
  • or any combination of these conditions,

then it should be approved by:

  • a specific entity user (such as the Finance Manager),
  • any user with a specific role,
  • any N users from the given list,
  • several entity users in a specific order (for example, first by the Team Lead, then by the Finance Manager).

Entities can create multiple approval policies with different trigger conditions to cover the business needs.

With approval policies, the payable flow works as follows:

  1. Whenever a payable is created or its attributes or status are changed, Monite checks if there is an applicable approval policy. This also happens when a new approval policy is created.
  2. If such an approval policy is found, Monite sends email notifications to the entity users designated as approvers.
  3. The approvers can either approve or reject the payable.
  4. Approved payables can then be paid.

Approval policy conflicts

Avoid creating approval policies with overlapping conditions. If a payable matches the conditions of multiple approval policies, no policy will be applied to this payable.

Approval policy structure

Approval policies are defined using the MoniteScript and consist of two parts:

  • trigger: The conditions that define which documents this approval policy applies to. See examples.
  • script: Specifies the logical statement to be executed. See examples.

You can optionally define a start and end dates for the approval policies to accommodate seasonal changes, holidays, temporary changes in the organizational structure, etc. The default start date is today, while the default end date is null, which means the approval policy has no date to end.

Below is a sample approval policy that requires approval from two users of a list for any payables over 500 worth submitted for approval:

1{
2  "starts_at": "2024-10-21T16:47:04.550Z",
3  "ends_at": "2024-10-21T16:47:04.550Z",
4  "name": "Sample approval policy",
5  "description": "Approval of two users required for any payables over 500 worth",
6  "trigger": {
7    "all": [
8      "{event_name == 'submitted_for_approval'}",
9      "{invoice.amount >= 50000}"
10    ]
11  },
12  "script": [
13    {
14      "call": "ApprovalRequests.request_approval_by_users",
15      "params": {
16        "user_ids": [
17          "91bff192-1a13-4a13-a4da-a2945ed0537d",
18          "ae6e88a8-c088-428c-ace2-d657bf407805",
19          "c2daca46-c0cb-45a3-a3a2-bfb1e768104c"
20        ],
21        "required_approval_count": 2
22      }
23    }
24  ]
25}

This instance of an approval policy applied to a payable is called a Process.

Create an approval policy

To create a customized approval policy, follow these steps:

1. Create a role

To manage the approval policies, the entity users must have a specific role assigned that allows them to create, read, update, and delete the approval policies.

This role is created by calling POST /roles:

1curl -X POST 'https://api.sandbox.monite.com/v1/roles' \
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    	"name": "all-access-example",
8      "permissions": {
9        "objects": [
10          {
11            "object_type": "approval_policy",
12            "actions": [
13              {
14                "action_name": "read",
15                "permission": "allowed"
16              },
17              {
18                "action_name": "create",
19                "permission": "allowed"
20              },
21              {
22                "action_name": "update",
23                "permission": "allowed"
24              },
25              {
26                "action_name": "delete",
27                "permission": "allowed"
28              }
29            ]
30          }
31        ]
32 	    }
33    }

The successful response contains the ID assigned to this role:

1{
2  "id": "8cd8c515-9862-4cbb-8f1e-511d081e5b73",
3  "name": "all-access-example",
4  "permissions": {...},
5  "status": "active",
6  "created_at": "2022-04-22T13:15:20.415Z",
7  "updated_at": "2022-04-22T13:15:20.415Z"
8}

2. Assign the created role to the entity user

The previously created role ID must be assigned to the entity user that will create the workflow. The entity-level token is still necessary for this action. Call PATCH /roles/{role_id}:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/entity_users/{entity_user_id}/{role_id}' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

3. Create an approval policy

To create an approval policy, call POST /approval_policies passing the approval policy script:

1curl -X POST 'https://api.sandbox.monite.com/v1/approval_policies' \
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        "starts_at": "2024-10-21T16:47:04.550Z",
8        "ends_at": "2024-10-21T16:47:04.550Z",
9        "name": "Sample approval policy",
10        "description": "Manager approval is required for any payables over 500 EUR",
11        "trigger": "{invoice.amount >= 50000}",
12        "script": [ ... ]
13     }'

4. Upload the payable

Submit the payable. If the collected payable matches the approval policy trigger conditions, it will automatically be inserted into this approval policy.

5. Get notified about the required actions

If the approval policy started for a payable requires the approval of specific entity users, reminder notifications are sent by email indicating when the payable needs to be approved or paid.

The notification email contains information about the payable and the link to perform the required action.

The link for approval can be defined in the partner settings by calling PATCH /settings:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4     -H 'Content-Type: application/json' \
5     -d '{
6       "payable": {
7         "approve_page_url": "https://monite.pay/cs_test_a1Olodw1w6YKbShWJHKcBPEATjtYF9I5aNbPOwTm"
8       }
9     }

Once all the required approvers have approved the payable, the entity user who uploaded the invoice is notified by an email with information about the invoice to be paid and a link to the payment provider.

List all approval policies

To get a list of all existing approval policies, call GET /approval_policies:

1curl -X GET 'https://api.sandbox.monite.com/v1/approval_policies?order=asc&limit=100&sort=created_at&object_type=payable' \
2     -H 'X-Monite-Version: 2024-05-25'\
3     -H 'x-monite-entity-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4'

The successful response contains information about all approval policies:

1{
2  "data": [
3    {
4      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5      "status": "active",
6      "starts_at": "2024-10-21T16:47:04.550Z",
7      "ends_at": "2024-10-21T16:47:04.550Z",
8      "name": "Sample approval policy",
9      "description": "Manager approval is required for any payables over 500 EUR",
10      "trigger": {
11        "all": [
12          "{event_name == 'submitted_for_approval'}",
13          "{invoice.amount >= 50000}"
14        ]
15      },
16      "script": [
17        {
18          "call": "ApprovalRequests.request_approval_by_users",
19          "params": {
20            "user_ids": [
21              "d133263a-605b-4e4a-abea-92aa79b04adf",
22              "e013e750-e629-4404-8df5-82dd741c6325"
23            ],
24            "object_id": "{invoice.id}",
25            "required_approval_count": 2
26          }
27        }
28      ],
29      "created_at": "2023-03-30T14:19:33.400Z",
30      "updated_at": "2023-03-30T14:19:33.400Z",
31      "created_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
32      "updated_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
33    }
34  ],
35  "prev_pagination_token": null,
36  "next_pagination_token": null
37}

The results can be:

  • Sorted by:

    • name
    • created_at
    • updated_at

  • Filtered by:

    • object_type: exact match
    • ID: exact match
    • name: exact match, contains, icontains
    • created_by: exact match
    • created_at: gt, gte, lt, lte
    • updated_at: exact match, gt, gte, lt, lte

Some examples:

  • GET /approval_policies?id__in=9d2b4c8f-2087-4738-ba91-7359683c49a4&id__in=20354d7a-e4fe-47af-8ff6-187bca92f3f9 - get approval policies based on their IDs.
  • GET /approval_policies?created_at__gte=2022-01-01T00%3A00%3A00 - get all approval policies created on or after January 1, 2022.

See also the standard pagination, sorting, and filtering parameters.

Retrieve an approval policy

To get information about a specific approval policy, call GET /approval_policies/{approval_policy_id}:

1curl -X GET 'https://api.sandbox.monite.com/v1/approval_policies/{approval_policy_id}' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'accept: application/json' \
4     -H 'x-monite-entity-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4'

The successful response contains information about the informed approval policy:

1{
2  "starts_at": "2024-10-21T16:47:04.550Z",
3  "ends_at": "2024-10-21T16:47:04.550Z",
4  "name": "Sample approval policy",
5  "description": "Approval of two users required for any payables over 500 worth",
6  "trigger": {
7    "all": [
8      "{event_name == 'submitted_for_approval'}",
9      "{invoice.amount >= 50000}"
10    ]
11  },
12  "script": [
13    {
14      "call": "ApprovalRequests.request_approval_by_users",
15      "params": {
16        "user_ids": [
17          "d133263a-605b-4e4a-abea-92aa79b04adf",
18          "e013e750-e629-4404-8df5-82dd741c6325"
19        ],
20        "object_id": "{invoice.id}",
21        "required_approval_count": 2
22      }
23    }
24  ],
25  "id": "e7233158-a82d-4ab2-9581-5d3bcbb30c7f",
26  "status": "active",
27  "created_at": "2023-03-31T11:46:10.615890+00:00",
28  "updated_at": "2023-03-31T11:46:10.615899+00:00",
29  "created_by": "3f4c99b1-3551-4910-93dd-1fd07b0a4772",
30  "updated_by": "3f4c99b1-3551-4910-93dd-1fd07b0a4772"
31}

Update an approval policy

To update an existing approval policy, call PATCH /approval_policies/{approval policy_id}.

Delete an approval policy

To delete an existing approval policy, call DELETE /approval_policies/{approval policy_id}.

It is not possible to delete or modify a approval policies currently active (e.g. there are business logic objects currently being processed by the approval policy).