--- updatedAt: 2025-10-02T22:24:43.000Z agentTools: projectIndex: https://developer.bill.com/v2/llms.txt --- # Create an approval policy Create a new approval policy. In your request, set `type` as the approval policy type. See the parameters for the complete list of types. In addition, you can set policies for a payment amount threshold (`amountThreshold`) and minimum number of approvers (`minNumApprovers`). ### What is an approval policy? You can create approval policies at the organization-level for approving bills or vendor credits. When you create a policy, you can set rules, such as payment amount threshold, mandatory approvers, and minimum number of approvers. For example, you can set the payment amount threshold (`amountThreshold`) as `$1000` and minimum number of approvers (`minNumApprovers`) as `2`. When you enter bills or vendor credits in the BILL web app, the Smart Data Entry (SDE) feature is used to auto-assign approvers that have been assigned to earlier bills or vendor credits. These approvers are also auto-assigned to new bills or vendor credits created with the API. When you apply an approval policy to a bill or vendor credit object, you can designate specific approvers (including the sequence of approvals) with `/v2/SetApprovers.json`. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "AP | Approvals", "version": "2.0", "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.", "contact": { "email": "developerprogram@hq.bill.com" } }, "servers": [ { "url": "https://api-stage.bill.com/api/v2", "description": "Sandbox base URL" } ], "x-readme": { "samples-languages": [ "curl", "java", "javascript", "python", "ruby" ], "explorer-enabled": true, "proxy-enabled": true }, "paths": { "/Crud/Create/ApprovalPolicy.json": { "post": { "summary": "Create an approval policy", "operationId": "ap-approvals-createapprovalpolicy", "description": "Create a new approval policy.\n\nIn your request, set `type` as the approval policy type. See the parameters for the complete list of types. In addition, you can set policies for a payment amount threshold (`amountThreshold`) and minimum number of approvers (`minNumApprovers`).\n\n### What is an approval policy?\nYou can create approval policies at the organization-level for approving bills or vendor credits. \n\nWhen you create a policy, you can set rules, such as payment amount threshold, mandatory approvers, and minimum number of approvers. For example, you can set the payment amount threshold (`amountThreshold`) as `$1000` and minimum number of approvers (`minNumApprovers`) as `2`.\n\nWhen you enter bills or vendor credits in the BILL web app, the Smart Data Entry (SDE) feature is used to auto-assign approvers that have been assigned to earlier bills or vendor credits. These approvers are also auto-assigned to new bills or vendor credits created with the API.\n\nWhen you apply an approval policy to a bill or vendor credit object, you can designate specific approvers (including the sequence of approvals) with `/v2/SetApprovers.json`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApprovalPolicyResponse" } } } } }, "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "devKey", "sessionId", "data" ], "properties": { "devKey": { "type": "string", "description": "Developer key generated with your BILL developer account" }, "sessionId": { "type": "string", "description": "API session ID generated with [`/v2/Login.json`](https://developer.bill.com/reference/auth-login)" }, "data": { "$ref": "#/components/schemas/CreateApprovalPolicyRequest" } } } } } }, "tags": [ "Approval policy" ] }, "parameters": [] } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "properties": { "error_code": { "type": "string", "description": "Error code (only when `response_status` is `1`)" }, "error_message": { "type": "string", "description": "Error message (only when `response_status` is `1`)" } } }, "CreateApprovalPolicyRequest": { "type": "object", "required": [ "obj" ], "properties": { "obj": { "type": "object", "required": [ "entity", "type", "amountThreshold", "minNumApprovers" ], "properties": { "entity": { "type": "string", "description": "Object type. Set as `ApprovalPolicy`.", "default": "ApprovalPolicy" }, "nickname": { "type": "string", "description": "Approval policy nickname" }, "type": { "type": "string", "description": "Approval policy type.\n* `0`: Bill\n* `1`: Vendor credit" }, "amountThreshold": { "type": "integer", "description": "Payment amount threshold for the policy" }, "minNumApprovers": { "type": "number", "description": "Minimum number of required approvers" }, "bankAccountId": { "type": "string", "description": "BILL-generated ID of the bank account. The value begins with `bac`. Set this value when you set `type` as `1`." }, "usersId": { "type": "string", "description": "BILL-generated user ID of a mandatory policy approver. The value begins with `006`." }, "approverNotSameAsPayer": { "type": "boolean", "description": "Set as `true` if the approver and payer cannot be the same user" }, "approverCondition": { "type": "string", "description": "Approving conditions. You can set this value for policy rules.\n* `0`: Priority AND\n* `1`: AND\n* `2`: OR" }, "isActive": { "type": "string", "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive" } } } } }, "CreateApprovalPolicyResponse": { "type": "object", "properties": { "response_status": { "type": "integer", "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`." }, "response_message": { "type": "string", "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`." }, "response_data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" } ], "properties": { "entity": { "type": "string", "description": "Object type. Set as `ApprovalPolicy`." }, "id": { "type": "string", "description": "BILL-generated ID of the approval policy. The value begins with `app`." }, "name": { "type": "string", "description": "Approval policy name automatically generated by BILL" }, "nickname": { "type": "string", "description": "Approval policy nickname" }, "type": { "type": "string", "description": "Approval policy type.\n* `0`: Bill\n* `1`: Vendor credit" }, "amountThreshold": { "type": "integer", "description": "Payment amount threshold for the policy" }, "minNumApprovers": { "type": "number", "description": "Minimum number of required approvers" }, "bankAccountId": { "type": "string", "description": "BILL-generated ID of the bank account. The value begins with `bac`. Set this value when you set `type` as `1`." }, "usersId": { "type": "string", "description": "BILL-generated user ID of a mandatory policy approver. The value begins with `006`." }, "approverNotSameAsPayer": { "type": "boolean", "description": "Set as `true` if the approver and payer cannot be the same user" }, "approverCondition": { "type": "string", "description": "Approving conditions. You can set this value for policy rules.\n* `0`: Priority AND\n* `1`: AND\n* `2`: OR" }, "isActive": { "type": "string", "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive" }, "createdTime": { "type": "string", "description": "Created date and time" }, "createdById": { "type": "string", "description": "BILL-generated user ID of the user that created the approval policy. The value begins with `006`." }, "updatedTime": { "type": "string", "description": "Updated data and time" } } } } } } } } ```