---
updatedAt: 2026-06-12T23:03:17.000Z
---
Fetch the complete documentation index at: https://developer.bill.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Bill approvals
A bill approval policy is a set of rules that enables you to control which bills require approval, by whom, and when.
In a bill approval policy, you can set rules and approvers. For example, if you set up an approval policy for all bills greater than or equal to $1000 and you assign two approvers in the policy, a bill of $1500 requires the assigned approvers to approve the bill before you can pay the bill.
## Tutorial: Bill approvals with the BILL v3 API
## Bill approval information in v3 bills
When you create or update a bill with the v3 API, set `billApprovals` as `true` for BILL to add approvals information in the v3 bills response.
When you have approval policies set up for bills and a bill matches a policy, you will see an additional `approvers` array of objects in the v3 bills response. The array shows the list of individual users and/or user groups assigned as bill approvers. In addition, the array provides information about the status of the bill in the current approval flow.
See the /v3/bill-approvals API for the complete list of available operations.
## Create a bill approval policy
In your `POST /v3/bill-approvals` request, set the required fields.
| Field | Description |
| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `policyName` | Bill approval policy name |
| `rules` | Bill approval policy rules. In the `rules` array, you can set multiple rules for a policy.
**Note**: Policy rules are applied in the specified order. |
| `approvers` | List of approvers. For each approver, set the BILL-generated ID of the user. The value begins with `006`. |
> 👍 We will add support for creating approval groups with the BILL v3 API
>
> Currently, you cannot create an approval group with the BILL v3 API. You can create an approval group with the BILL web app (**Settings > Approval policies > Approval groups**). In the future, we will add support for creating approval groups with the BILL v3 API.
>
> In the BILL web app, when you create an approval policy with an approver group and a bill matches the policy, you will see the approval group in the list of `approvers` in the v3 bills response.
### Sample request
In this cURL example, a bill approval policy is created for all v3 bills with `amount` greater than or equal to `1000.00` and less than `2000.00`. In addition, two individual `users` are added as approvers in the policy.
```curl
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/bill-approvals' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
"policyName": "Bills 1000 to 2000",
"rules": [
{
"key": "BILL_AMOUNT",
"op": "gte",
"values": [
"1000"
]
},
{
"key": "BILL_AMOUNT",
"op": "lt",
"values": [
"2000"
]
}
],
"approvers": [
"{user_id01}",
"{user_id02}"
]
}
```
### Response
In the response, a BILL-generated bill approval policy `id` as available. The value is in the `{organization_id}-{unique_id}` format. The `rules` and `approvers` are set.
```json
{
"id": "{bill_approval_policy_id}",
"policyName": "Bills 1000 to 2000",
"status": "ACTIVE",
"rules": [
{
"key": "BILL_AMOUNT",
"op": "gte",
"values": [
{
"value": "1000",
"displayName": "1000"
}
]
},
{
"key": "BILL_AMOUNT",
"op": "lt",
"values": [
{
"value": "2000",
"displayName": "2000"
}
]
}
],
"approvers": {
"users": [
{
"userId": "{user_id01}",
"fullName": "Clark Billenterson"
},
{
"userId": "{user_id02}",
"fullName": "Final boss"
}
],
"groups": []
}
}
```
## When a v3 bill matches the policy
When a bill created with the v3 API matches the bill approval policy, an additional `approvers` array of objects is available in the bill response.
In this sample response, `approvalStatus` is set as `ASSIGNED` since the bill is assigned to the list of approver users. In addition, the `approvers` array shows the current user assigned as an approver for the bill. Finally, `status` is set as `WAITING` to state that BILL is waiting for the user to perform an approval action on the bill.
> 👍 The bill cannot be paid until the approvers have approved the bill
>
> When BILL performs a policy match on a bill, the bill cannot be paid until all the required approvers have approved the bill for payment.
```json
{
"id": "{bill_id}",
"archived": false,
"vendorId": "{vendor_id}",
"amount": 1500.00,
"dueDate": "2026-12-31",
"invoice": {
"invoiceNumber": "202601",
"invoiceDate": "2026-12-31"
},
"billLineItems": [
{
"id": "{billLineItem_id01}",
"amount": 1500.00
}
],
"paymentStatus": "UNPAID",
"approvalStatus": "ASSIGNED",
"createdTime": "2026-12-30T23:15:23.127+00:00",
"updatedTime": "2026-12-30T23:15:23.127+00:00",
"approvers": [
{
"userId": "{user_id01}",
"status": "WAITING",
"approverOrder": 0,
"statusChangedTime": "2026-12-30T23:15:23.127+00:00"
},
{
"userId": "{user_id02}",
"status": "WAITING",
"approverOrder": 1,
"statusChangedTime": "2026-12-30T23:15:23.127+00:00"
}
]
}
```
## Get list of bills pending approvals
### Sample response
With `GET /v3/bill-approvals/pending-user-approvals`, you get a list of bills that are pending approval by the currently signed-in user.
> 👍 The user must have correct permissions for getting the list of bills pending approvals
>
> The signed-in user must have the necessary permissions for approving bills. Users with the **Administrator**, **Accountant**, and **Approver** user roles have permissions for bill approvals operations. See User roles and permissions in the BILL Help Center for more information.
```json
{
"bills": [
{
"billId": "{bill_id01}",
"vendorId": "{vendor_id01}",
"amount": 1500.00,
"dueDate": "2026-12-31"
},
{
"billId": "{bill_id02}",
"vendorId": "{bill_id02}",
"amount": 1199.00,
"dueDate": "2026-12-31"
}
]
}
```
## Approver or deny a bill
In your `POST /v3/bill-approvals/actions` request, set the required fields.
| Field | Description |
| :------- | :---------------------------------------------------------- |
| `billId` | BILL-generated ID of the bill. The value begins with `00n`. |
| `action` | Approve or deny the bill. Approved bills can be paid. |
### Sample request
In this cURL example, an approval action is completed for a bill. The bill is approved.
```curl
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/bill-approvals/actions' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '[{
"billId": "{bill_id}",
"action": "APPROVE",
"comment": "Approved for payment"
}]
```
### Response
When the request is successful, you receive an HTTP 200 response.