canonical: https://jentic.com/apis/bill.com/bill-approvals

# BILL Approvals API

Jentic publishes the only available OpenAPI specification for BILL Approvals API, keeping it validated and agent-ready. The Approvals API on BILL's accounts payable platform models approval policies and approver assignments for bills and vendor credits, exposing single and bulk CRUD plus dedicated approve, deny, set-approvers, and clear-approvers actions. Endpoints are POST-style /Crud and /List operations consistent with the v2 BILL API. Use it to codify multi-stage approval routing for accounts payable workflows.

## For AI agents

Define BILL approval policies, set or clear approvers on bills and vendor credits, and approve or deny pending items via the BILL v2 Approvals API.

## Scope

Does not handle bill creation, payment execution, or AR invoicing - use for BILL approval policy and approver workflow operations only.

## Capabilities

- Create and update approval policies via /Crud/Create/ApprovalPolicy.json
- Bulk-create or bulk-update approval policies in one call
- Assign approvers to a policy through /Crud/Create/ApprovalPolicyApprover.json
- Set or clear the approver list on bills and vendor credits with /SetApprovers.json and /ClearApprovers.json
- Approve or deny a pending bill or vendor credit via /Approve.json and /Deny.json
- List a user's pending approvals through /ListUserApprovals.json
- Read all bill-approver policies via /GetAllBillApproverPolicy.json

## Use cases

### Multi-Stage Bill Approval Routing

Finance teams enforce approval thresholds - junior approver under $5k, manager up to $25k, controller above. The Approvals API lets the integration codify this through ApprovalPolicy and ApprovalPolicyApprover records, then attach the right policy to each bill via /SetApprovers.json. Approvers act on items with /Approve.json or /Deny.json, and /ListUserApprovals.json powers an inbox view.

Example prompt: Call POST /SetApprovers.json with the bill objectId and ordered approver IDs, then notify each approver and surface /ListUserApprovals.json in their inbox

### Approval Policy Bulk Maintenance

When the AP team reorganizes - new departments, role changes, or quarterly delegation updates - the integration syncs the new approver matrix without manual rework. /Bulk/Crud/Update/ApprovalPolicy.json and /Bulk/Crud/Update/ApprovalPolicyApprover.json apply the changes in single calls, while the Undelete endpoints recover policies that were retired prematurely.

Example prompt: Call POST /Bulk/Crud/Update/ApprovalPolicyApprover.json with the new approver list per policy after the org update

### Approver Inbox Automation

Approvers want a one-screen view of everything waiting on their decision. /ListUserApprovals.json returns the pending items for the current session user, and /Approve.json or /Deny.json acts on each. Combined with /Crud/Read/BillApprover.json the integration can show full bill context including the policy that routed it before the user clicks approve.

Example prompt: Call /ListUserApprovals.json, render the items, and call /Approve.json with the chosen objectId on user click

### Agent-Driven Approval Actions via Jentic

An AI controller-assistant connected through Jentic answers 'approve invoice INV-2207 for Acme' by searching for the approve action, loading the BILL /Approve.json operation, and executing it with the bill's objectId. Through Jentic the BILL session credentials sit in the vault, and the agent never sees the raw devKey or session ID. The same flow extends to deny and set-approver actions.

Example prompt: Search Jentic for 'approve a bill in BILL', load /Approve.json, execute with objectId for INV-2207

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /Crud/Create/ApprovalPolicy.json | Create an approval policy |
| POST | /Crud/Create/ApprovalPolicyApprover.json | Add an approver to a policy |
| POST | /SetApprovers.json | Set approver list on a bill or vendor credit |
| POST | /ClearApprovers.json | Clear approver list on a bill or vendor credit |
| POST | /Approve.json | Approve a pending item |
| POST | /Deny.json | Deny a pending item |
| POST | /ListUserApprovals.json | List approvals waiting on a user |
| POST | /GetAllBillApproverPolicy.json | List all bill approver policies |

## Key resources

- **Approval Policies** — Create, update, list, and delete approval policy definitions
- **Approval Policy Approvers** — Manage which users sit on which policy and in what order
- **Approver Actions** — Approve, deny, set, and clear approvers on bills and vendor credits
- **User Approvals** — List items awaiting the current user's decision

## Why Jentic

- **Setup:** Wiring the BILL Approvals API by hand means logging in for a session id, pairing it with your developer key on every RPC-style POST, and shaping each approval-policy body yourself. Through Jentic you install once, import BILL Approvals from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** BILL Approvals identifies bills and policies in the request body of RPC-style operations rather than the URL path, so limit the agent to the operations it needs, such as listing user approvals or setting approvers. You choose that set, so Approve or Deny are not reachable unless you include them.
- **Credential handling:** Your BILL developer key and session id are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'set approvers on a bill' or 'list a user's approvals', and Jentic returns the matching BILL Approvals operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **BILL Authentication API** — Required to obtain a session ID before calling any BILL v2 endpoint
- **BILL Customer Management API** — Manage AR customer records that flow alongside AP approval workflows
- **BILL Connect Events API** — Subscribe to BILL events including approval state changes

## FAQ

### Why is there no official OpenAPI spec for BILL Approvals API?

BILL documents its v2 API in narrative form on developer.bill.com but does not publish the underlying OpenAPI document. Jentic generates and maintains a structured OpenAPI specification so AI agents and developers can call BILL Approvals API via tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the BILL Approvals API use?

BILL's v2 API uses a session-based scheme: callers authenticate against the BILL Authentication API to obtain a session ID, which is then passed alongside a developer key on each subsequent call. Through Jentic, the developer key and session lifecycle are managed inside the vault and auto-attached to outbound calls.

### Can I approve or deny a bill through this API?

Yes. POST /Approve.json with the bill or vendor credit objectId moves it forward in the workflow, and POST /Deny.json rejects it. Use /SetApprovers.json beforehand to make sure the right routing is attached, and /ClearApprovers.json to reset routing when a bill is being reissued.

### What are the rate limits for the BILL Approvals API?

BILL applies platform-wide rate limits at the v2 API gateway rather than per-endpoint, and the Approvals surface inherits those limits. For end-of-month pushes, prefer the bulk endpoints (/Bulk/Crud/Create/ApprovalPolicy.json, /Bulk/Crud/Update/ApprovalPolicyApprover.json) over single-item loops to stay well under the cap.

### How do I approve a bill through Jentic?

Run `pip install jentic`, then `await client.search('approve a bill in BILL')`, `await client.load(...)` for /Approve.json, and `await client.execute(...)` with the bill objectId. Jentic injects the BILL devKey and session credentials from the vault.

### How do I list everything waiting on the current user's approval?

POST /ListUserApprovals.json returns the items pending for the authenticated session user. Pair with /Crud/Read/BillApprover.json or /Crud/Read/VendorCreditApprover.json to enrich each item with the policy and approver chain that routed it.

### Can I limit what my agent is allowed to do with the BILL Approvals API?

Yes. Because Jentic One is self-hosted, you decide which BILL Approvals operations your agent may call and which credentials it uses, and your own rules are enforced at execution time. Since the API identifies bills and policies in the request body of its RPC-style POST calls rather than in the URL, you scope access at the operation level, allowing only what the agent needs such as /ListUserApprovals.json or /SetApprovers.json. Approve.json and Deny.json stay out of reach unless you explicitly include them in the allowed set.