A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The BILL API is how an app or AI agent works with a BILL organization: drafting a bill, adding a vendor, paying a bill, or sending an invoice to a customer. Access runs through a developer key plus a login that signs in as a BILL user, and every call is bounded by that user's role and permissions in the organization rather than a per-method scope. BILL can also push a signed notification to an app when something changes, like a bill being created or a payment moving status.
How an app or AI agent connects to BILL determines what it can reach. There is a route for making calls, signed in as a BILL user, and a route for receiving events, and each is governed by the signed-in user and the developer key behind it.
The v3 REST API takes JSON request bodies, returns JSON, and uses the standard verbs (GET, POST, PUT, PATCH, DELETE). The production base address is https://gateway.prod.bill.com/connect/v3 and the sandbox is https://gateway.stage.bill.com/connect/v3. A call signs in as a BILL user through the login method, then sends the returned sessionId and the devKey as headers on every request.
BILL posts a JSON notification to a registered URL when a subscribed event occurs, like a bill being created or a payment changing status. An app creates a subscription, picks events from the event catalog, and verifies each notification against an HMAC-SHA256 signature sent in the x-bill-sha-signature header. An organization can hold up to 10 subscriptions.
The standard flow. An app signs in with the login method, passing the devKey, a BILL username and password, and an organizationId, and receives a sessionId. The sessionId and devKey are then sent as headers on every call. The session acts as that user, so its reach equals the user's role and permissions, and it expires after a period of inactivity.
Some actions, in particular creating or releasing a payment, require the session to be stepped up through BILL's multi-factor flow first. The app sets up multi-factor on the user, then challenges and validates a code to mark the session trusted. A money-moving call on an untrusted session is rejected with BDC_1361.
A partner login signs in at the partner level rather than a single organization, granting additional permissions for managing organizations and users across an accounting-firm or platform relationship. It is used by integrators who administer many BILL organizations.
The BILL API is split into areas an agent can act on, like bills, vendors, payments, invoices, and customers. Each area has its own methods, and a write that creates or sends a payment moves real money out of a connected bank account.
Methods for creating and managing the bills an organization owes.
Methods for working with vendors and their bank accounts.
Methods for paying bills and managing payments.
Methods for billing customers through accounts receivable.
Methods for working with customers and charging them.
Methods for bill approval policies and actions.
Methods for the organization's own funding bank accounts.
Methods for bill documents and record attachments.
Methods for signing in, reading session details, and signing out.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Bills (AP)Methods for creating and managing the bills an organization owes.7 | ||||||
| POST | /v3/bills | Create a bill, with line items, for a vendor. | write | — | Current | |
No per-endpoint scope; allowed if the signed-in user's role can create bills. Acts onbill Permission (capability)None required VersionAvailable since the API’s base version Webhook event bill.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/bills/bulk | Create multiple bills in a single request. | write | — | Current | |
Bulk variant of bill creation; same role requirement. Acts onbill Permission (capability)None required VersionAvailable since the API’s base version Webhook event bill.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/bills | List bills in the organization, with filtering and pagination. | read | — | Current | |
Read-only; returns bills the signed-in user may see. Acts onbill Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/bills/{billId} | Get a single bill by its ID. | read | — | Current | |
Read-only. Acts onbill Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/bills/{billId} | Update fields on an existing bill. | write | — | Current | |
Partial update; allowed by the signed-in user's role. Acts onbill Permission (capability)None required VersionAvailable since the API’s base version Webhook event bill.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/bills/{billId} | Replace a bill with a new full representation. | write | — | Current | |
Full replacement rather than a partial patch. Acts onbill Permission (capability)None required VersionAvailable since the API’s base version Webhook event bill.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/bills/{billId}/archive | Archive a bill, the soft-delete used in place of a hard delete. | write | — | Current | |
Reversible with the restore method. Acts onbill Permission (capability)None required VersionAvailable since the API’s base version Webhook event bill.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Vendors (AP)Methods for working with vendors and their bank accounts.5 | ||||||
| POST | /v3/vendors | Create a vendor (US or international) to pay. | write | — | Current | |
Allowed if the signed-in user's role can manage vendors. Acts onvendor Permission (capability)None required VersionAvailable since the API’s base version Webhook event vendor.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/vendors | List vendors in the organization. | read | — | Current | |
Read-only. Acts onvendor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/vendors/{vendorId} | Get a single vendor by its ID. | read | — | Current | |
Read-only. Acts onvendor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/vendors/{vendorId} | Update fields on an existing vendor. | write | — | Current | |
Partial update of vendor details. Acts onvendor Permission (capability)None required VersionAvailable since the API’s base version Webhook event vendor.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/vendors/{vendorId}/bank-account | Add the bank account a vendor is paid into. | write | — | Current | |
Sets where money is sent; an MFA-trusted session may be required. Acts onvendor-bank-account Permission (capability)None required VersionAvailable since the API’s base version Webhook event vendor.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payments (AP)Methods for paying bills and managing payments.5 | ||||||
| POST | /v3/payments | Pay one or more vendor bills, moving real money. | write | — | Current | |
Requires an MFA-trusted session and a role that can make payments. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook event payment.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/payments/bulk | Pay multiple bills in a single request. | write | — | Current | |
Bulk variant; needs an MFA-trusted session. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook event payment.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/payments | List payments in the organization. | read | — | Current | |
Read-only. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/payments/{paymentId} | Get a single payment by its ID. | read | — | Current | |
Read-only. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/payments/{paymentId}/cancel | Cancel a payment that has not yet cleared. | write | — | Current | |
Reverses a pending payment; needs a payment-capable role. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Invoices (AR)Methods for billing customers through accounts receivable.3 | ||||||
| POST | /v3/invoices | Create an accounts-receivable invoice for a customer. | write | — | Current | |
Allowed if the signed-in user's role can manage invoices. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook event invoice.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/invoices | List invoices in the organization. | read | — | Current | |
Read-only. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/invoices/{invoiceId}/send | Send an invoice to its customer by email. | write | — | Current | |
Delivers a real invoice to the customer. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Customers (AR)Methods for working with customers and charging them.3 | ||||||
| POST | /v3/customers | Create a customer to invoice and charge. | write | — | Current | |
Allowed if the signed-in user's role can manage customers. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/customers | List customers in the organization. | read | — | Current | |
Read-only. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/customers/{customerId}/charge | Charge a customer who has authorized payment. | write | — | Current | |
Moves money in from the customer; needs a charge authorization on file. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ApprovalsMethods for bill approval policies and actions.3 | ||||||
| POST | /v3/bill-approvals/actions | Approve or deny bills as an approval action. | write | — | Current | |
Acts on bills pending the signed-in user's approval. Acts onbill-approval Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/bill-approvals/pending | List bills awaiting approval by the signed-in user. | read | — | Current | |
Read-only. Acts onbill-approval Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/bill-approvals/policies | Create a bill approval policy that routes bills for sign-off. | write | — | Current | |
Changes how bills are routed for approval across the organization. Acts onapproval-policy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Bank accountsMethods for the organization's own funding bank accounts.3 | ||||||
| POST | /v3/funding-accounts/banks | Add a bank account the organization pays bills from. | write | — | Current | |
Sets up a funding source; verification and MFA apply. Acts onbank-account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/funding-accounts/banks | List the organization's funding bank accounts. | read | — | Current | |
Read-only. Acts onbank-account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/funding-accounts/banks/{bankAccountId}/verify | Verify a funding bank account so it can be used to pay. | write | — | Current | |
Completes setup of a money-moving funding source. Acts onbank-account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DocumentsMethods for bill documents and record attachments.2 | ||||||
| POST | /v3/documents/bills/{billId} | Attach a document, like a supporting PDF, to a bill. | write | — | Current | |
Adds a document to a financial record. Acts ondocument Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/documents/bills/{billId} | List the documents attached to a bill. | read | — | Current | |
Read-only. Acts ondocument Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Login & sessionMethods for signing in, reading session details, and signing out.3 | ||||||
| POST | /v3/login | Sign in to create an API session, returning a sessionId. | write | — | Current | |
Takes devKey, username, password, and organizationId; limited to 200 calls per devKey per hour. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit200 per developer key per hour SourceOfficial documentation ↗ | ||||||
| GET | /v3/login/session | Read the current session: organization, user, and MFA status. | read | — | Current | |
Read-only; confirms who the session acts as and whether MFA is set. Acts onsession Permission (capability)None required VersionIntroduced 2024-08-02 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/logout | Sign out and invalidate the current session. | write | — | Current | |
Ends the session so the sessionId can no longer be used. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BILL can notify an app when something happens in an organization, like a bill being created or a payment changing status. An app subscribes to named events and BILL posts a signed notification, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
bill.created | A new bill was created in the organization. An integration can sync it or kick off an approval workflow. | /v3/bills |
bill.updated | A bill changed, like its amount, due date, or status being updated. | /v3/bills/{billId}/v3/bills/{billId}/v3/bills/{billId}/archive |
vendor.created | A new vendor was added. An integration can enrich or sync the vendor record. | /v3/vendors |
vendor.updated | A vendor's details changed, for example its bank account or contact information. | /v3/vendors/{vendorId} |
payment.created | A payment was created against one or more bills. This is the signal that money is moving. | /v3/payments |
invoice.created | A new accounts-receivable invoice was created for a customer. | /v3/invoices |
BILL limits how many requests an app can make per hour against a developer key, and caps how many run at once for one organization.
BILL meters requests per developer key per hour rather than per second. The ceiling is 20,000 requests per developer key per hour across standard endpoints; going over returns error code BDC_1144. The login method is limited far lower, to 200 requests per developer key per hour, and SMS-sending methods used for multi-factor checks allow 5 messages per minute. Separately, only 3 requests may run at once for one developer key against one organization, and exceeding that returns BDC_1322, so an integration should run calls in sequence with backoff rather than in parallel.
List methods page with a max parameter for page size and a nextPage cursor token carried forward from the previous response to fetch the following page. Results are returned in pages rather than all at once, and an app follows the cursor until no further page token is returned.
A webhook subscription is capped at 10 per organization, and event notifications are retained for resend for a fixed window (raised to 180 days). A session becomes invalid after a period of inactivity and must be recreated by signing in again.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | BDC_xxxx (REQUEST) | A bad request: a field is missing or invalid. The response body carries a BILL code, a severity, a category of REQUEST, and a plain message describing what is wrong. | Read the message, fix the request body or parameters, and resend. The call is not retryable as-is. |
| 401 | BDC_1109 | The session is invalid or has expired (Session is invalid. Please log in.). It also covers an invalid developer key, BDC_1102. | Sign in again with the login method to get a fresh sessionId, and confirm the devKey is correct for the environment. |
| 403 | BDC_1361 | The session is untrusted: a multi-factor check is needed for this action, typically creating or releasing a payment. | Step the session up through BILL's multi-factor flow (setup, challenge, validate), then retry the call. |
| 404 | BDC_1121 | API not supported: the endpoint path is wrong, often a spelling or capitalization mistake. | Check the method and path against the reference, including case, and resend. |
| 429 | BDC_1144 | The hourly request limit for the developer key was reached (Max number of allowed requests per hour reached: 20000). | Back off and retry after the hour window, and smooth the request rate. |
| 429 | BDC_1322 | Too many requests are running at once: the cap is 3 concurrent requests per developer key per organization. | Run calls in sequence rather than in parallel, and retry with exponential backoff once an in-flight call completes. |
| 500 | BDC_1001 | A system error on BILL's side. The category in the body is SERVER or DOWNSTREAM. | Retry with backoff, and contact BILL support if it persists. |
BILL keeps two API generations side by side. The v3 API is the current line and gets ongoing feature updates, while the older v2 API stays supported on its own base address.
The v3 API is BILL's current generation and the recommended target for new integrations, covering accounts payable, accounts receivable, and spend and expense. It receives ongoing feature updates shipped through dated release notes, while the older v2 API stays supported on its own base address.
Webhook retention was raised from 90 days to 180 days, and event notifications can be filtered by an entity ID so an app can scope a subscription to a specific record.
Vendor credit endpoints were added to the v3 API, extending accounts payable coverage.
A new method to read the current session was added, returning the current organization, current user, and the organization's multi-factor status.
Webhook endpoints were introduced, letting an app subscribe to real-time event notifications for vendor, bill, and payment activity instead of polling.
Build new work on v3; v2 remains supported for existing integrations.
BILL API release notes ↗Bollard AI sits between a team's AI agents and BILL. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.