{ "schema": "aaes/capability-pack/1", "provider": "billcom", "version": "1.0.0", "description": "BILL (Bill.com) v3 AP API: read vendors, bills and payments, create a bill, and approve or deny a bill.", "notes": "Use a BILL API session whose underlying sign-in credentials carry only the access these capabilities need; the pack does not create one. The BILL v3 API authenticates every call with TWO headers, sessionId and devKey: this pack's credential reference stores the sessionId material for injection into the sessionId header, and the deployment must present the devKey header alongside every call — review how the deployment's HTTP executor supplies that second header before enabling, because if it cannot, this pack is not enableable as wired.\n\nThe production host is gateway.prod.bill.com (path prefix /connect); gateway.stage.bill.com is the sandbox and is not registered. Bill creation is registered as pay at the minimum R3 tier, not create at R2: POST /v3/bills itself creates a bill object and schedules no payment — payment is the separate, MFA-gated POST /v3/payments endpoint this pack deliberately does not register — but BILL documents vendor auto-pay (when autoPay is enabled for a vendor, BILL automatically pays the vendor when a bill is created for that vendor), so under a documented account configuration the call initiates a payment workflow whose documented end state is a processed payment; pay is one of the designated actions requiring human approval.\n\nApproving a bill is registered as approve at the minimum R3 tier — BILL documents that approved bills can be paid — and approve is likewise irreversible; both irreversible actions require a person, and the registered cost ceiling on bill creation plus a policy budget are the second control. All reads are collection reads only: single-record reads (GET /v3/vendors/{vendorId}, GET /v3/bills/{billId}, GET /v3/payments/{paymentId}) exist in the API and are deliberately not registered.\n\nExcluded operations: payment creation (POST /v3/payments, POST /v3/payments/bulk and POST /v3/payments/mass — money moves, and BILL requires an MFA-trusted session), recording offline AP payments, cancelling or voiding payments, vendor creation/update/archive and all vendor bank account operations, recurring bills (including recurring-bill autoPayment), bill update/replace/archive/restore, bill approval policy management, the entire AR surface, the Spend & Expense API surface (which uses a different, token-based authentication), documents and attachments upload, webhook subscription management, MFA operations, and the v2 API.\n\nAn AP & AR sync token sign-in is the least-privilege credential shape for the reads and for bill creation (sync-token sessions have no payment and no approve/deny access); the approve capability requires a user-credential session, so a deployment that enables the approve capability must accept the broader session. AAES has not been certified by Bill.com; the endpoints here are configuration to review and test; the vendor has not endorsed it.", "credential": { "secret_ref_id": "secret-ref-billcom-v3-session", "custody": "customer_vault", "inject": "header", "inject_name": "sessionId", "note": "A BILL v3 API session id, held in the client's own secret manager. The stored material must be the complete sessionId header value — the session id itself, with no scheme prefix. An external token process mints it: POST https://gateway.prod.bill.com/connect/v3/login with username, password, organizationId and devKey — where username/password are either user credentials or an AP & AR sync token name/value generated in the BILL web app (Settings > Sync & Integrations > Tokens) — and stores only the returned sessionId; the sign-in credentials (user password or sync token value) are themselves secret material and stay with that external process.\n\nThe devKey has a different lifecycle: BILL documents devKey and sessionId as required headers on EVERY API call, not just login, so the devKey must also reach the trusted HTTP executor — it does not stay with the external sign-in process. The deployment must resolve the devKey from its own secret manager as a second secret reference (separate from this pack's sessionId reference), inject it into the devKey header on every call alongside the injected sessionId, and give it protections equivalent to the session id's: held in executor memory only for the lifetime of a call, never written to logs, traces or diagnostics, and never present in crash dumps.\n\nThat second-secret wiring is outside this pack's single injection point and is a pre-enablement review item — if the executor cannot supply the devKey header, this pack is not enableable as wired.\n\nExpiry and revocation: BILL documents that a session minted from user credentials expires after 35 minutes idle, and a session minted from a sync token after 48 hours idle, so the external process must re-login on expiry — the executor must not attempt renewal itself; signing out with POST /v3/logout terminates the session, and an expired value fails closed; revoking a sync token in the BILL web app prevents that token minting new sessions — preventing issuance is a different event from invalidating sessions already minted, and BILL's documentation does not describe credential or sync-token changes as ending sessions already in flight before their documented idle expiry.\n\nLeast privilege: a sync-token session has no payment operations, no approve/deny and no MFA-protected operations, and is the right shape for the reads and bill creation; the approve capability needs a user-credential session, which BILL documents as unrestricted within the user's permissions — choose the underlying BILL user's role accordingly. MFA note: payment creation requires an MFA-trusted session, which this pack never uses because it does not register payment creation.\n\nExecutor hygiene: the session id must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must never appear in crash reports; the executor's memory, log and crash handling are otherwise the deployment's review." }, "capabilities": [ { "capability_id": "billcom.vendors.read", "version": "1.0.0", "kind": "tool", "risk_tier": "R0", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "pii", "egress_allowlist": [ "gateway.prod.bill.com" ], "endpoint": "https://gateway.prod.bill.com/connect/v3/vendors", "method": "GET", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-billcom-v3-session", "inject": "header", "inject_name": "sessionId", "actions": [ "read" ], "resource_id": "billcom-vendors", "description": "Query the vendors collection: vendor names, account numbers, emails, phones, addresses and network/payment status — vendor records carry named contacts and can identify individual persons, so the read is classified as pii (personal data) (a deployment whose policy classifies vendor master data differently may change it).\n\nThe registered path covers the collection read only — single-vendor reads (GET /v3/vendors/{vendorId}) and vendor bank account details are not registered by this pack.", "requires_review": true }, { "capability_id": "billcom.bills.read", "version": "1.0.0", "kind": "tool", "risk_tier": "R0", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "financial", "egress_allowlist": [ "gateway.prod.bill.com" ], "endpoint": "https://gateway.prod.bill.com/connect/v3/bills", "method": "GET", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-billcom-v3-session", "inject": "header", "inject_name": "sessionId", "actions": [ "read" ], "resource_id": "billcom-bills", "description": "Query the bills collection: bill headers with vendors, invoice numbers, amounts, currencies, due dates, approval statuses and payment statuses, classified as financial data.\n\nThe registered path covers the collection read only — single-bill reads (GET /v3/bills/{billId}) and bill documents are not registered by this pack.", "requires_review": true }, { "capability_id": "billcom.payments.read", "version": "1.0.0", "kind": "tool", "risk_tier": "R0", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "financial", "egress_allowlist": [ "gateway.prod.bill.com" ], "endpoint": "https://gateway.prod.bill.com/connect/v3/payments", "method": "GET", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-billcom-v3-session", "inject": "header", "inject_name": "sessionId", "actions": [ "read" ], "resource_id": "billcom-payments", "description": "Query the payments collection: payment objects with vendors, amounts, funding accounts, process dates, disbursement types and statuses, classified as financial data.\n\nThe registered path covers the collection read only — single-payment reads (GET /v3/payments/{paymentId}) and check image data are not registered by this pack.", "requires_review": true }, { "capability_id": "billcom.bills.create", "version": "1.0.0", "kind": "tool", "risk_tier": "R3", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "financial", "egress_allowlist": [ "gateway.prod.bill.com" ], "endpoint": "https://gateway.prod.bill.com/connect/v3/bills", "method": "POST", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-billcom-v3-session", "inject": "header", "inject_name": "sessionId", "actions": [ "pay" ], "resource_id": "billcom-bills", "cost_ceiling_usd": 500, "description": "Create a bill with POST /v3/bills. The response confirms bill creation and request acceptance, not that money moved. Explicit payment uses the separate MFA-gated POST /v3/payments endpoint, which this pack excludes.\n\nAutomatic-payment effect: BILL documents that creating a bill for a vendor with autoPay enabled initiates its automatic payment workflow. Review the vendor’s autoPay setting before enabling. This is why the capability declares pay at the minimum R3 tier and requires human approval on supported AAES-mediated execution paths; it does not stop observation-only or bypass calls.\n\nBudget limit: the gateway refuses a declared amount above the registered ceiling and commits the ceiling against the task budget. It does not constrain the amount encoded in the provider request.", "requires_review": true }, { "capability_id": "billcom.bills.approve", "version": "1.0.0", "kind": "tool", "risk_tier": "R3", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN", "data_class": "financial", "egress_allowlist": [ "gateway.prod.bill.com" ], "endpoint": "https://gateway.prod.bill.com/connect/v3/bill-approvals/actions", "method": "POST", "connector": "http", "custody": "customer_vault", "secret_ref_id": "secret-ref-billcom-v3-session", "inject": "header", "inject_name": "sessionId", "actions": [ "approve" ], "resource_id": "billcom-bill-approvals", "description": "Approve or deny bills through POST /v3/bill-approvals/actions, with one array entry per bill. The call records the approver’s judgement and releases the corresponding approval gate. A bill subject to an approval policy cannot be paid until all required approvers have approved.\n\nPayment effect: the call itself moves no money. Explicit payment uses the excluded MFA-gated POST /v3/payments endpoint. However, BILL also documents vendor auto-pay and recurring-bill autoPayment; releasing an approval gate can allow configured automatic payment processing. Excluding the explicit payment endpoint does not exclude every payment-initiation path.\n\nClassification: approve, minimum R3.\n\nOn supported AAES-mediated execution paths, an authorized person must approve the irreversible action. This cannot stop observation-only or bypass calls.\n\nCredential requirement: approve/deny needs a user-credential session. AP & AR sync-token sessions cannot perform it.", "requires_review": true } ], "resources": [ { "resource_id": "billcom-vendors", "kind": "api", "locator": "https://gateway.prod.bill.com/connect/v3/vendors", "data_class": "pii", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN" }, { "resource_id": "billcom-bills", "kind": "api", "locator": "https://gateway.prod.bill.com/connect/v3/bills", "data_class": "financial", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN" }, { "resource_id": "billcom-payments", "kind": "api", "locator": "https://gateway.prod.bill.com/connect/v3/payments", "data_class": "financial", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN" }, { "resource_id": "billcom-bill-approvals", "kind": "api", "locator": "https://gateway.prod.bill.com/connect/v3/bill-approvals/actions", "data_class": "financial", "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN" } ], "review": { "state": "library", "date": "2026-09-22", "sources": [ "https://developer.bill.com/llms.txt (retrieved 2026-09-21)", "https://developer.bill.com/reference/login.md (retrieved 2026-09-21)", "https://developer.bill.com/docs/bill-keys-tokens.md (retrieved 2026-09-21)", "https://developer.bill.com/docs/token-based-sign-in.md (retrieved 2026-09-21)", "https://developer.bill.com/reference/listvendors.md (retrieved 2026-09-21)", "https://developer.bill.com/reference/listbills.md (retrieved 2026-09-21)", "https://developer.bill.com/reference/listpayments.md (retrieved 2026-09-21)", "https://developer.bill.com/reference/createbill.md (retrieved 2026-09-21)", "https://developer.bill.com/reference/billapprovedenyactions.md (retrieved 2026-09-21)", "https://developer.bill.com/docs/ap-bill-approvals.md (retrieved 2026-09-21)", "https://developer.bill.com/docs/ap-bills.md (retrieved 2026-09-21)", "https://developer.bill.com/docs/vendor-payment-options.md (retrieved 2026-09-21)", "https://developer.bill.com/docs/ap-payments.md (retrieved 2026-09-21)" ], "reviewer_id": "aaes-eng" } }