> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Approval policies ## 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](../../../references/glossary#entity) 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](../../../references/glossary#counterpart) (vendor or supplier), > * was uploaded by a specific [entity user](../../../references/glossary#entity-user), > * was uploaded by any user with a specific role, > * is in a specific [currency](../../../references/currencies) (such as EUR or USD), > * has a specific amount to be paid (for example, ≥ 5000 EUR or 100-500 USD), > * has specific [tags](../../../common/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](../../approvals/policies/trigger-examples) 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. > **Warning** > > **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](../../../references/monitescript) and consist of two parts: * `trigger`: The conditions that define which documents this approval policy applies to. [See examples](../../approvals/policies/trigger-examples). * `script`: Specifies the logical statement to be executed. [See examples](../../approvals/policies/script-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. The optional `priority` field defines the order in which approval policies are evaluated. When multiple policies match, the one with the highest priority is applied. This prevents invoices from getting stuck when no policy matches or when several overlap. Higher numbers mean higher priority. The default is 1, with a valid range from -32,768 to 32,767. null is allowed and treated as unset. Below is a sample approval policy that requires approval from two users of a list for any payables over 500 worth submitted for approval: ```json { "starts_at": "2024-10-21T16:47:04.550Z", "ends_at": "2024-10-21T16:47:04.550Z", "name": "Sample approval policy", "description": "Approval of two users required for any payables over 500 worth", "priority": 1, "trigger": { "all": [ "{event_name == 'submitted_for_approval'}", "{invoice.amount >= 50000}" ] }, "script": [ { "call": "ApprovalRequests.request_approval_by_users", "params": { "user_ids": [ "91bff192-1a13-4a13-a4da-a2945ed0537d", "ae6e88a8-c088-428c-ace2-d657bf407805", "c2daca46-c0cb-45a3-a3a2-bfb1e768104c" ], "required_approval_count": 2 } } ] } ``` > **Info** > > This instance of an approval policy applied to a payable is called a [Process](../../approvals/policies/processes). ## 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](../../../references/glossary#role) assigned that allows them to `create`, `read`, `update`, and `delete` the approval policies. This role is created by calling `POST /roles`: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/roles' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "name": "all-access-example", "permissions": { "objects": [ { "object_type": "approval_policy", "actions": [ { "action_name": "read", "permission": "allowed" }, { "action_name": "create", "permission": "allowed" }, { "action_name": "update", "permission": "allowed" }, { "action_name": "delete", "permission": "allowed" } ] } ] } } ``` The successful response contains the ID assigned to this role: ```json { "id": "8cd8c515-9862-4cbb-8f1e-511d081e5b73", "name": "all-access-example", "permissions": {...}, "status": "active", "created_at": "2022-04-22T13:15:20.415Z", "updated_at": "2022-04-22T13:15:20.415Z" } ``` ### 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}`: ```sh curl -X PATCH 'https://api.sandbox.monite.com/v1/entity_users/{entity_user_id}/{role_id}' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` ### 3. Create an approval policy To create an approval policy, call `POST /approval_policies` passing the [approval policy script](../../../references/monitescript): ```sh curl -X POST 'https://api.sandbox.monite.com/v1/approval_policies' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "starts_at": "2024-10-21T16:47:04.550Z", "ends_at": "2024-10-21T16:47:04.550Z", "name": "Sample approval policy", "description": "Manager approval is required for any payables over 500 EUR", "priority": 1, "trigger": "{invoice.amount >= 50000}", "script": [ ... ] }' ``` ### 4. Upload the payable [Submit the payable.](../../payables/collect) 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](../../../references/glossary#partner) settings by calling `PATCH /settings`: ```sh curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "payable": { "approve_page_url": "https://monite.pay/cs_test_a1Olodw1w6YKbShWJHKcBPEATjtYF9I5aNbPOwTm" } } ``` 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. ## Manual approval policy enforcement In addition to automatic approval policy selection based on triggers and priority, Monite also supports manual enforcement of approval policies. This allows you to explicitly specify which approval policy should be applied to a payable, bypassing the normal trigger-based selection process. Set `enforce_approval_policy_id` to a valid approval policy ID when creating payables via `POST /payables` or updating them via `PATCH /payables/{payable_id}`. Clear manual enforcement by setting the field to `null`. The field accepts any valid approval policy ID that exists, is active, and belongs to the same entity. When `enforce_approval_policy_id` is set and the payable transits to `submit_for_approval` status: * Trigger conditions are completely ignored - policy executes regardless. * Priority is ignored - only the enforced policy is applied. * If enforced policy is unavailable (deleted or inactive) - **no** policy is applied, even if other policies would match. ## List all approval policies To get a list of all existing approval policies, call `GET /approval_policies`: ```sh curl -X GET 'https://api.sandbox.monite.com/v1/approval_policies?order=asc&limit=100&sort=created_at&object_type=payable' \ -H 'X-Monite-Version: 2024-05-25'\ -H 'x-monite-entity-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4' ``` The successful response contains information about all approval policies: ```json { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "active", "starts_at": "2024-10-21T16:47:04.550Z", "ends_at": "2024-10-21T16:47:04.550Z", "name": "Sample approval policy", "description": "Manager approval is required for any payables over 500 EUR", "priority": 1, "trigger": { "all": [ "{event_name == 'submitted_for_approval'}", "{invoice.amount >= 50000}" ] }, "script": [ { "call": "ApprovalRequests.request_approval_by_users", "params": { "user_ids": [ "d133263a-605b-4e4a-abea-92aa79b04adf", "e013e750-e629-4404-8df5-82dd741c6325" ], "object_id": "{invoice.id}", "required_approval_count": 2 } } ], "created_at": "2023-03-30T14:19:33.400Z", "updated_at": "2023-03-30T14:19:33.400Z", "created_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "updated_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "prev_pagination_token": null, "next_pagination_token": null } ``` 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. > **Info** > > See also the standard [pagination, sorting, and filtering](../../../api/concepts/pagination-sorting-filtering) parameters. ## Retrieve an approval policy To get information about a specific approval policy, call `GET /approval_policies/{approval_policy_id}`: ```sh curl -X GET 'https://api.sandbox.monite.com/v1/approval_policies/{approval_policy_id}' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'accept: application/json' \ -H 'x-monite-entity-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4' ``` The successful response contains information about the informed approval policy: ```json { "starts_at": "2024-10-21T16:47:04.550Z", "ends_at": "2024-10-21T16:47:04.550Z", "name": "Sample approval policy", "description": "Approval of two users required for any payables over 500 worth", "priority": 1, "trigger": { "all": [ "{event_name == 'submitted_for_approval'}", "{invoice.amount >= 50000}" ] }, "script": [ { "call": "ApprovalRequests.request_approval_by_users", "params": { "user_ids": [ "d133263a-605b-4e4a-abea-92aa79b04adf", "e013e750-e629-4404-8df5-82dd741c6325" ], "object_id": "{invoice.id}", "required_approval_count": 2 } } ], "id": "e7233158-a82d-4ab2-9581-5d3bcbb30c7f", "status": "active", "created_at": "2023-03-31T11:46:10.615890+00:00", "updated_at": "2023-03-31T11:46:10.615899+00:00", "created_by": "3f4c99b1-3551-4910-93dd-1fd07b0a4772", "updated_by": "3f4c99b1-3551-4910-93dd-1fd07b0a4772" } ``` ## 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}`. > **Info** > > 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).