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.
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 |
|---|---|
| Bill approval policy name |
| Bill approval policy rules. In the |
| List of approvers. In the
|
We will add support for creating approval groups with the BILL v3 APICurrently, 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
approversin 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 --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": [
{
"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"
}
]
}
}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.
[
{
"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.
{
"id": "{bill_id}",
"archived": false,
"vendorId": "{vendor_id}",
"amount": 1500.00,
"dueDate": "2025-12-31",
"invoice": {
"invoiceNumber": "202501",
"invoiceDate": "2025-12-31"
},
"billLineItems": [
{
"id": "{billLineItem_id01}",
"amount": 1500.00
}
],
"paymentStatus": "UNPAID",
"approvalStatus": "ASSIGNED",
"createdTime": "2025-12-30T23:15:23.127+00:00",
"updatedTime": "2025-12-30T23:15:23.127+00:00",
"approvers": [
{
"userId": "{user_id01}",
"status": "WAITING",
"approverOrder": 0,
"statusChangedTime": "2025-12-30T23:15:23.127+00:00"
},
{
"userId": "{user_id02}",
"status": "WAITING",
"approverOrder": 1,
"statusChangedTime": "2025-12-30T23:15:23.127+00:00"
}
]
}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 --request POST \
–-url 'https://gateway.stage.bill.com/connect/v3/actions' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
"billId": "{bill_id}",
"action": "APPROVE"
}Response
When the request is successful, you receive an HTTP 200 response.
Get list of bills pending approvals
Sample response
When you make the GET /v3/bill-approvals/pending-user-approvals request, you get a list of bills that are pending approval by the currently signed-in user.
{
"bills": [
{
"billId": "{bill_id01}",
"vendorId": "{vendor_id01}",
"amount": 1500.00,
"dueDate": "2025-12-31"
},
{
"billId": "{bill_id02}",
"vendorId": "{bill_id02}",
"amount": 1199.00,
"dueDate": "2025-12-31"
}
]
}Updated about 5 hours ago