> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

Tesouro allows [organizations](/finops/support/glossary#organization) to customize and automate the set of roles and approval conditions to change the payable status according to the business needs of the organization with **approval policies**.

Some examples of approval policies:

> If the payable:
>
> * was received from a specific [counterpart](/finops/support/glossary#counterpart) (vendor or supplier),
> * was uploaded by a specific [organization user](/finops/support/glossary#organization-user),
> * was uploaded by any user with a specific role,
> * is in a specific [currency](/finops/support/currencies) (such as USD),
> * has a specific amount to be paid (for example, ≥ $5,000 or $100–\$500),
> * has specific [tags](/finops/guides/common/tags) assigned to it,
> * or any combination of these conditions,
>
> then it should be approved by:
>
> * a specific organization user (such as the Finance Manager),
> * any user with a specific role,
> * any N users from the given list,
> * several organization users in a specific order (for example, first by the Team Lead, then by the Finance Manager).

Organizations can create multiple approval policies with different [trigger](/finops/guides/accounts-payable/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, Tesouro 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, Tesouro sends email notifications to the organization 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.
</Warning>

## Approval policy structure

Approval policies are defined using the [TesouroScript](/finops/guides/advanced/tesouroscript) and consist of two parts:

* `trigger`: The conditions that define which documents this approval policy applies to. [See examples](/finops/guides/accounts-payable/approvals/policies/trigger-examples).
* `script`: Specifies the logical statement to be executed. [See examples](/finops/guides/accounts-payable/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 expandable lines theme={null}
{
  "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](/finops/guides/accounts-payable/approvals/policies/processes).
</Info>

## Create an approval policy

To create a customized approval policy, follow these steps:

### 1. Create an approval policy

To create an approval policy, call `POST /approval-policies` passing the [approval policy script](/finops/guides/advanced/tesouroscript):

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/approval-policies' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_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",
        "priority": 1,
        "trigger": "{invoice.amount >= 50000}",
        "script": [ ... ]
     }'
```

### 2. Upload the payable

[Submit the payable.](/finops/guides/accounts-payable/payables/collect) If the collected payable matches the approval policy trigger conditions, it will automatically be inserted into this approval policy.

### 3. Get notified about the required actions

If the approval policy started for a payable requires the approval of specific organization 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](/finops/support/glossary#partner) settings by calling `PATCH /settings`:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payable": {
         "approve_page_url": "https://tesouro.pay/cs_test_a1Olodw1w6YKbShWJHKcBPEATjtYF9I5aNbPOwTm"
       }
     }
```

Once all the required approvers have approved the payable, the organization 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, Tesouro 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 organization.

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 lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/approval-policies?order=asc&limit=100&sort=created_at&object_type=payable' \
     -H 'X-Finops-Version: 2025-06-23'\
     -H 'x-organization-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4'
```

The successful response contains information about all approval policies:

```json expandable lines theme={null}
{
  "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",
      "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](/finops/api/concepts/pagination-sorting-filtering) parameters.
</Info>

## Retrieve an approval policy

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

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/approval-policies/{approval_policy_id}' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'accept: application/json' \
     -H 'x-organization-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4'
```

The successful response contains information about the informed approval policy:

```json expandable lines theme={null}
{
  "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).
</Info>