Skip to main content

QuickBooks Query Tools

Connect your QuickBooks Online account to enable AI-powered financial queries for customers, vendors, invoices, bills, payments, and financial reports.

Overview​

QuickBooks Query Tools allow your AI agents to access financial data from QuickBooks Online. Agents can query customer information, vendor details, invoice status, generate financial reports, and more to answer questions and automate workflows.

Use Cases​

  • Customer Lookup - Find customer balances, contact information, and transaction history
  • Vendor Management - Search vendors and review payment status
  • Invoice Analysis - Query invoices by status, date range, or customer
  • Bill Tracking - Monitor bills and payment schedules
  • Financial Reporting - Generate Balance Sheet, Profit & Loss, and Cash Flow reports for any date range
  • Custom Queries - Execute custom SELECT queries against QuickBooks data

How It Works​

QuickBooks Connection          Dynamic Tools           Agent Queries
        │                           │                       │
        ▼                           ▼                       ▼
┌─────────────────┐         ┌─────────────────┐     ┌─────────────────┐
│ OAuth 2.0       │    →    │ Auto-created    │  →  │ Secure API      │
│ Authorization   │         │ Query Tools     │     │ Calls with      │
│                 │         │                 │     │ Rate Limiting   │
└─────────────────┘         └─────────────────┘     └─────────────────┘

When you connect a QuickBooks account via OAuth, a default query tool is automatically created. You can create additional specialized tools for specific use cases.

Getting Started​

Prerequisites​

Before connecting QuickBooks:

  1. QuickBooks Online Account - You need an active QuickBooks Online subscription
  2. Admin Access - You must be an admin on the QuickBooks account to authorize the connection
  3. Feature Enabled - QuickBooks tools must be enabled in your Control Bridge settings

Step 1: Enable QuickBooks Tools​

  1. Navigate to Build > Connections > QuickBooks
  2. Go to the Settings tab
  3. Toggle Enable QuickBooks Query Tool to on
  4. Click Save Changes

Step 2: Connect Your QuickBooks Account​

  1. Go to the Connections tab
  2. Click Connect QuickBooks
  3. You'll be redirected to Intuit's authorization page
  4. Sign in to your QuickBooks account
  5. Select the company to connect
  6. Click Authorize to grant access
  7. You'll be returned to Control Bridge with your connection established

Step 3: Grant Tool Access​

After creating a connection, Control Bridge automatically creates a default query tool and displays the Tool Grant dialog. This lets you immediately grant access to your agents without leaving the page.

The Tool Grant dialog shows all available agents organized by type:

Agent TypeDescription
AI Chief of Staff (AICOS)Enable for organizational and financial queries
Subject Matter Experts (SMEs)Enable for specialized domain agents
Email AgentsEnable for email processing workflows

Select the agents that should have access and click Grant Access. You can also skip this step and assign tools to agents later.

tip

The Tool Grant dialog also appears when you create additional specialized tools from the Tools tab. This makes it easy to grant access immediately without navigating to each agent's configuration.

Step 4: Verify the Connection​

  1. Find your new connection in the Connections tab
  2. Click the Test button to verify connectivity
  3. Confirm you see your company name in the success message

Managing Connections​

Connection Details​

Each connection displays:

FieldDescription
Display NameFriendly name for the connection
Company NameQuickBooks company name
Queries TodayCurrent day's query count vs. limit
Write OpsWhether write operations are enabled
Token ExpiresDays until access token expiration

Token Management​

QuickBooks access tokens expire periodically:

  • Access Token - Expires after ~60 minutes (auto-refreshed)
  • Refresh Token - Expires after ~100 days (requires re-authorization)

Token Warnings:

  • Yellow Warning - Token expires within 7 days, consider refreshing
  • Red Warning - Token expired, click Refresh or re-authorize

Actions:

  • Test - Verify the connection is working
  • Refresh - Manually refresh the access token
  • Edit - Modify connection settings
  • Delete - Remove the connection and all associated tools

Editing a Connection​

Click the Edit button to modify:

  • Display name and description
  • Hourly and daily query limits
  • Write operation permissions
  • Approval workflow settings

Write Operations​

By default, connections are read-only. To enable limited write operations:

  1. Edit the connection
  2. Toggle Allow Write Operations to on
  3. Configure Require Approval if you want human review before changes
  4. Click Save

Supported Write Operations:

  • Update customer contact information (email, phone, address)
  • Update vendor contact information (email, phone, address)
warning

Write operations do not allow financial changes like modifying invoices, bills, or payments. Only contact information updates are supported.

Managing Tools​

Default Tool​

When you create a connection, a default General Query tool is automatically created. This tool can:

  • Query all supported entity types
  • List and search customers
  • List and search vendors
  • Query invoices, bills, and payments
  • Get company information
  • Run financial reports (Balance Sheet, Profit & Loss, Cash Flow)

Creating Specialized Tools​

You can create additional tools with specific capabilities:

  1. Go to the Tools tab
  2. Click Add Tool
  3. Select the connection to use
  4. Configure the tool settings:
SettingDescription
Tool NameUnique identifier (e.g., qb_vendors_acme)
Display NameFriendly name for agents
Operation TypeWhat the tool can do (see below)
Max ResultsLimit on returned records
Result FormatJSON, Markdown, or Summary
Require ConfirmationAsk before executing
  1. Click Save
  2. The Tool Grant dialog appears - grant access to agents immediately or skip for later

Operation Types​

Read Operations:

TypeDescription
query_allGeneral purpose query tool (includes all read and report operations)
query_companyGet company information only
query_customersList and search customers
query_vendorsList and search vendors
query_invoicesQuery invoices with filters
query_billsQuery bills with filters
query_paymentsQuery payments
query_reportsRun financial reports (agent selects report type at runtime)
report_balance_sheetBalance Sheet report for a date range
report_profit_and_lossProfit & Loss statement for a date range
report_cash_flowCash Flow Statement for a date range
custom_queryExecute custom SELECT queries

Write Operations (when enabled):

TypeDescription
update_customer_contactUpdate customer contact info
update_vendor_contactUpdate vendor contact info
info

The query_all operation type is the most flexible. It includes all read operations and all report operations in a single tool. Use specialized operation types when you want to limit an agent's access to specific data.

Assigning Tools to Agents​

If you skipped the Tool Grant dialog during creation, you can assign tools later:

  1. Go to Build > AI Agents > Agents
  2. Edit the agent that should use QuickBooks
  3. In the Tools section, find your QuickBooks tools
  4. Enable the tools you want the agent to use
  5. Save the agent

Financial Reports​

QuickBooks Query Tools can generate three standard financial reports. These are powerful tools for agents answering questions about company finances, trends, and performance.

Available Reports​

ReportDescriptionCommon Use Cases
Balance SheetSnapshot of assets, liabilities, and equity at a point in time"What's our current cash position?" / "Show total assets"
Profit & LossRevenue and expenses over a date range"What were last quarter's revenues?" / "Show monthly expenses"
Cash Flow StatementCash inflows and outflows over a date range"How much cash did we generate this year?" / "Show operating cash flow"

Report Parameters​

All financial reports accept the following parameters:

ParameterRequiredFormatDescription
Start DateYesYYYY-MM-DDBeginning of the reporting period
End DateYesYYYY-MM-DDEnd of the reporting period
Accounting MethodNoCash or AccrualDefaults to the company's configured accounting method

Report Operation Types​

There are two ways agents can generate financial reports:

Direct report operations - Use a specific operation type to request a particular report. Best when you know exactly which report an agent needs:

  • report_balance_sheet - Always generates a Balance Sheet
  • report_profit_and_loss - Always generates a Profit & Loss statement
  • report_cash_flow - Always generates a Cash Flow Statement

The query_reports meta-operation - Lets the agent choose which report to generate at runtime by specifying a reportType parameter. Best when an agent needs flexibility to decide which report is most relevant based on the user's question.

tip

If your agent only needs one type of report (e.g., a P&L for monthly reviews), create a specialized tool with the direct operation type. If an agent needs to answer general financial questions, use query_all or query_reports so it can pick the right report dynamically.

Report Output​

Financial reports return structured data with two formats:

  • Structured rows - Hierarchical data with account labels, amounts, nesting depth, and row types (header, data, total). Useful for programmatic analysis.
  • Formatted text - A pre-formatted plain text summary ready for inclusion in agent responses. Agents typically use this when presenting results to users.

Example of the formatted text output for a Balance Sheet:

Balance Sheet (Accrual) for 2025-01-01 to 2025-12-31

ASSETS
  Current Assets
    Checking: 45,000.00
    Accounts Receivable: 12,500.00
  Total Current Assets: 57,500.00
TOTAL ASSETS: 57,500.00

LIABILITIES AND EQUITY
  Current Liabilities
    Accounts Payable: 8,200.00
  Total Current Liabilities: 8,200.00
  Equity
    Retained Earnings: 49,300.00
  Total Equity: 49,300.00
TOTAL LIABILITIES AND EQUITY: 57,500.00

Agent Query Examples​

Here are real-world examples of how agents use QuickBooks Query Tools. These show the operations and parameters agents send when responding to user requests.

Customer Lookup with Filters​

User asks: "What's the outstanding balance for Acme Corporation?"

Agent calls the tool with:

{
  "operation": "list_customers",
  "filters": { "companyName": "Acme Corporation" },
  "maxResults": 5
}

The agent receives customer records including display name, email, phone, and current balance, then summarizes the results.

Invoice Status Query​

User asks: "Show me all unpaid invoices from last month."

Agent calls the tool with:

{
  "operation": "list_invoices",
  "filters": {
    "status": "unpaid",
    "startDate": "2026-01-01",
    "endDate": "2026-01-31"
  },
  "maxResults": 100
}

The agent receives invoice details including document numbers, customer names, amounts, balances, and due dates.

Vendor Analysis​

User asks: "List all our active vendors and their total balances."

Agent calls the tool with:

{
  "operation": "list_vendors",
  "maxResults": 100
}

The agent receives vendor records with names, balances, contact info, and payment terms, then can aggregate and summarize the data.

Financial Report Generation​

User asks: "Generate a P&L report for Q4 2025 using the accrual method."

Agent calls the tool with:

{
  "operation": "report_profit_and_loss",
  "startDate": "2025-10-01",
  "endDate": "2025-12-31",
  "accountingMethod": "Accrual"
}

The agent receives the full Profit & Loss report with revenue, expense, and net income breakdowns.

Dynamic Report Selection​

User asks: "How is our financial health looking this year?"

Agent calls the tool with the query_reports meta-operation, choosing the report type dynamically:

{
  "operation": "query_reports",
  "reportType": "balance_sheet",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31"
}

The agent may follow up with additional reports (P&L, Cash Flow) to build a comprehensive financial overview.

Custom Query​

User asks: "Find all invoices over $10,000 for ACME Corp."

Agent calls the tool with:

{
  "operation": "query",
  "query": "SELECT * FROM Invoice WHERE CustomerRef = '123' AND TotalAmt > '10000'"
}
warning

Custom queries use QuickBooks Query Language, not standard SQL. Only SELECT statements are allowed. The agent cannot use INSERT, UPDATE, or DELETE via custom queries.

Get Specific Record by ID​

User asks: "Show me the details for invoice INV-2026-042."

Agent calls the tool with:

{
  "operation": "get_invoice",
  "entityId": "456"
}

The agent receives full invoice details including line items, payment status, customer info, and due dates.

Write Approval Queue​

When write operations require approval:

  1. Agent requests a contact update
  2. Request enters the Approvals queue
  3. Admin reviews current vs. proposed values
  4. Admin approves or denies the request
  5. If approved, changes are applied to QuickBooks

Reviewing Approvals​

  1. Go to the Approvals tab
  2. Review pending requests showing:
    • Entity type (Customer/Vendor)
    • Current values
    • Proposed changes
    • Requesting agent
  3. Click Approve or Deny
  4. Optionally add notes explaining your decision

Viewing Logs​

The Logs tab shows all QuickBooks API activity:

ColumnDescription
ConnectionWhich connection was used
OperationQuery type performed
RecordsNumber of records returned
StatusSuccess or failure
DurationResponse time in milliseconds
AgentWhich agent made the request
TimeWhen the query occurred

Filtering Logs​

Use the filters to narrow results:

  • Connection - Select specific connection
  • Operation - Filter by query type
  • Status - Success or failed only
  • Date Range - Start and end dates
  • Agent - Filter by requesting agent

Log Statistics​

View aggregated statistics:

  • Total queries and success rate
  • Average response time
  • Queries by operation type
  • Queries by connection

Rate Limiting​

QuickBooks tools include built-in rate limiting to protect your account:

  • Hourly Limit - Maximum queries per hour (default: 100)
  • Daily Limit - Maximum queries per day (default: 500)

When limits are reached, agents receive a clear message and can retry later.

Adjusting Limits​

  1. Edit the connection
  2. Modify Queries Per Hour and Queries Per Day
  3. Save changes
tip

Start with the default limits and increase only if agents are regularly hitting them. You can monitor usage on the connection card's "Queries Today" counter and in the Logs tab statistics.

Troubleshooting​

Connection Test Fails​

Problem: "Test" returns an error

Solutions:

  1. Check if the token has expired (look for red/yellow warnings)
  2. Click Refresh to get a new access token
  3. If refresh fails, re-authorize by creating a new connection
  4. Verify your QuickBooks account is still active

Token Expired​

Problem: Token shows as expired

Solutions:

  1. Click Refresh to attempt automatic renewal
  2. If refresh token is also expired (~100 days), you must re-authorize:
    • Create a new connection
    • Delete the old connection
    • Update agent tool assignments

Rate Limit Exceeded​

Problem: Queries fail with quota message

Solutions:

  1. Wait for the hourly/daily reset
  2. Increase limits in connection settings
  3. Optimize agent instructions to reduce unnecessary queries

Agent Can't Find Tool​

Problem: Tool doesn't appear in agent configuration

Solutions:

  1. Verify the tool is Active (not disabled)
  2. Check that the parent connection is Active
  3. Refresh the page
  4. Verify you have quickbooks:tools:read permission

Query Returns Empty Results​

Problem: Valid queries return no data

Solutions:

  1. Verify the QuickBooks company has data for that entity type
  2. Check filter parameters match existing records
  3. Test directly in QuickBooks to confirm data exists
  4. Review agent instructions for correct query formation

Report Returns Unexpected Data​

Problem: Financial report doesn't match what you see in QuickBooks

Solutions:

  1. Verify the date range is correct (use YYYY-MM-DD format)
  2. Check the accounting method - Cash and Accrual produce different numbers
  3. Ensure the date range covers the expected transactions
  4. Compare with QuickBooks Online directly using the same parameters

Security​

Data Protection​

  • OAuth tokens encrypted with AES-256-CBC
  • No QuickBooks credentials stored (OAuth only)
  • All API calls logged for audit purposes
  • Tenant isolation ensures data separation

Access Control​

  • Only authorized users can create connections
  • Write operations can require approval workflow
  • All actions logged with user attribution
  • Connections can be disabled without deletion

Query Restrictions​

  • Only SELECT queries allowed (no INSERT/UPDATE/DELETE via custom query)
  • Write operations limited to contact information only
  • Financial data is read-only (no invoice/bill modifications)

Best Practices​

Agent Instructions​

Help your agents use QuickBooks effectively by including guidance in their system instructions:

When looking up customer information:
1. Use the quickbooks_query tool with operation "list_customers"
2. Include relevant filters like email or company name
3. Summarize key details: name, balance, contact info
4. If no results, check for alternate spellings

When generating financial reports:
1. Always confirm the date range with the user before running a report
2. Use "report_profit_and_loss" for revenue/expense questions
3. Use "report_balance_sheet" for asset/liability questions
4. Use "report_cash_flow" for cash movement questions
5. Default to Accrual method unless the user specifies Cash

Connection Organization​

  • Use descriptive display names that identify the company
  • Create separate connections for different business units if needed
  • Set appropriate rate limits based on expected query volume

Tool Organization​

  • Use the default query_all tool for general-purpose agents
  • Create specialized tools (e.g., query_customers only) for agents that should have limited access
  • Use report_balance_sheet or report_profit_and_loss tools when an agent only needs specific reports

Security​

  • Enable approval workflow for write operations in production
  • Regularly review the logs for unusual activity
  • Re-authorize connections before refresh tokens expire