Xero Accounting Integration

Connect Xero to give your AI agents read-only financial visibility into your accounting data for instant answers to business questions about invoices, payments, contacts, and financial reports.

Overview

The Xero Accounting Integration allows AI agents to query your organization's Xero accounting data through 7 read-only tools. Agents can search invoices and contacts, retrieve payment history, generate financial reports, and view fixed asset schedules - all without any risk of modifying your accounting data.

The integration uses OAuth 2.0 with single-use refresh tokens and distributed locking to prevent token replay attacks. Once connected, a "Xero" tool group is automatically created and ready to assign to any agent.

info

All 7 Xero tools are strictly read-only. No agent can create, update, or delete records in Xero through this integration. Write operations are not supported.

Use Cases

• Overdue Invoice Follow-up - Agent queries overdue receivables to prepare collection follow-up emails or escalate to the finance team
• Daily Financial Briefing - AICOS generates a Profit and Loss report each morning and includes the summary in the Business Owner's daily briefing
• Vendor Payment History - Agent checks payment history for a specific vendor before responding to a billing inquiry
• Fixed Asset Planning - Agent retrieves fixed asset depreciation schedules to support budget planning discussions
• Cash Flow Visibility - Agent generates a Bank Summary report and answers questions about current cash position
• Contact Lookup - Agent retrieves a contact's outstanding balance when processing a customer service request

How It Works

IT Admin connects Xero       7 tools created             Agents query Xero
via OAuth 2.0                in "Xero" tool group        using tool group
       |                            |                           |
       v                            v                           v
+--------------+          +------------------+        +------------------+
| Select Xero  |          | xero_search      |        | Query invoices,  |
| organization |   --->   | xero_get_report  |  --->  | generate reports,|
| to link      |          | xero_search_     |        | look up contacts |
|              |          |   invoices, etc. |        | and payments     |
+--------------+          +------------------+        +------------------+

Each tool's description includes your organization name and base currency so agents understand which Xero organization they are querying.

Getting Started

Prerequisites

Before connecting Xero:

1. Pro Plus+ Subscription - The Xero integration requires the custom.xero feature code on your subscription
2. Xero Account - Your organization must have an active Xero subscription with the data you want agents to access
3. Xero Administrator Access - You must be a Xero administrator to authorize the OAuth connection
4. Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration

Step 1: Connect Xero via OAuth

1. Navigate to Build > Connections > Xero
2. Click Connect Xero
3. You are redirected to Xero's authorization page
4. Sign in with your Xero administrator account
5. Select the Xero organization to link (if your account has multiple organizations, choose the correct one)
6. Click Allow access to authorize the connection
7. You are redirected back to Control Bridge upon success

tip

If your Xero account manages multiple organizations, you can only connect one organization per Control Bridge tenant. Choose the primary accounting organization your agents need access to.

Step 2: Verify the Connection

After connecting:

1. The Xero connections page shows your organization name, base currency, and connection status
2. Click Test Connection to verify the integration is working
3. The system confirms that the access token is valid and the Xero organization is reachable

Step 3: Assign the Xero Tool Group to Agents

Xero tools are bundled into a "Xero" tool group automatically created at connection time:

1. Navigate to Build > AI Agents > Agents
2. Edit the agent that should have financial data access
3. Go to the Tools tab
4. In the Tool Groups section, enable the Xero group
5. Save the agent

All 7 Xero tools are assigned together as a single unit via the tool group.

warning

Only assign the Xero tool group to agents that genuinely need financial data access. Agents with Xero access can retrieve sensitive financial information including invoice amounts, payment history, and bank transaction data.

Available Tools

When Xero is connected, 7 read-only tools are created and grouped under the "Xero" tool group.

1. Xero Search (xero_search)

Search invoices, contacts, and bank transactions with structured filters and pagination.

Parameter	Type	Required	Description
entityType	string	Yes	invoices, contacts, or bankTransactions
filters	array	No	Structured filter objects (see below)
order	string	No	Sort field and direction (e.g., UpdatedDateUTC DESC)
page	number	No	Page number, 1-indexed, 100 results per page
modifiedSince	string	No	ISO date - only return records modified after this date
statuses	string	No	Comma-separated status filter (invoices only)
contactIds	string	No	Comma-separated contact ID filter (invoices only)

Filter format:

[
  { "field": "Status", "operator": "equals", "value": "AUTHORISED" },
  { "field": "DueDate", "operator": "before", "value": "2026-03-01" }
]

Supported operators: equals, not_equals, contains, starts_with, ends_with, greater_than, less_than, before (date), after (date)

Example queries agents can answer:

• "Show me all unpaid sales invoices" - entityType="invoices", filter by Type equals ACCREC and Status equals AUTHORISED
• "Find overdue invoices" - entityType="invoices", filter by DueDate before today
• "Search for a contact named Acme" - entityType="contacts", filter by Name contains Acme

2. Xero Get Report (xero_get_report)

Generate financial reports with configurable date ranges and comparison periods.

Parameter	Type	Required	Description
reportType	string	Yes	Report type (see table below)
fromDate	string	No	Start date (YYYY-MM-DD) for P&L, BankSummary
toDate	string	No	End date (YYYY-MM-DD) for P&L, BankSummary
date	string	No	Point-in-time date for BalanceSheet, TrialBalance
periods	number	No	Number of comparison periods
timeframe	string	No	MONTH, QUARTER, or YEAR
contactId	string	No	Required for AgedReceivables/Payables reports
standardLayout	boolean	No	Use standard vs. custom report layout
paymentsOnly	boolean	No	Cash-basis reporting

Available report types:

Report Type	Description
ProfitAndLoss	Income and expense statement for a date range
BalanceSheet	Assets, liabilities, and equity at a point in time
TrialBalance	All account balances at a point in time
BankSummary	Cash movements across bank accounts
BudgetSummary	Budgeted vs. actual figures
ExecutiveSummary	High-level business performance snapshot
AgedReceivablesByContact	Outstanding receivables by customer
AgedPayablesByContact	Outstanding payables by supplier

3. Xero Search Invoices (xero_search_invoices)

Retrieve an individual invoice by its ID to view full details including line items, amounts, and status.

Parameter	Type	Required	Description
action	string	Yes	Must be get
invoiceId	string	Yes	Invoice UUID

Returns full invoice data including line items, tax amounts, contact details, and payment status.

Invoice status lifecycle: DRAFT -> SUBMITTED -> AUTHORISED -> PAID. Terminal states: VOIDED, DELETED.

4. Xero Search Contacts (xero_search_contacts)

Retrieve an individual contact by ID to view their full details and outstanding balances.

Parameter	Type	Required	Description
action	string	Yes	Must be get
contactId	string	Yes	Contact UUID

Returns contact details including balances, account status, and contact information.

5. Xero Search Payments (xero_search_payments)

Retrieve or list payment records with optional filters.

Parameter	Type	Required	Description
action	string	Yes	get or list
paymentId	string	For get	Payment UUID
page	number	For list	Page number, 1-indexed
filters	array	For list	Structured filter objects (same format as xero_search)

6. Xero Search Assets (xero_search_assets)

Read-only access to fixed assets, asset types, and depreciation settings.

Parameter	Type	Required	Description
action	string	Yes	get, list, list_types, or get_settings
assetId	string	For get	Asset UUID
status	string	For list	Draft, Registered, or Disposed
page	number	No	Page number
pageSize	number	No	Results per page (default: 10)
orderBy	string	No	AssetName, AssetNumber, PurchaseDate, or PurchasePrice
sortDirection	string	No	asc or desc
filterBy	string	No	Text filter on asset name, number, or description

Returns asset records including current book value, accumulated depreciation, and depreciation settings.

7. Xero Get Overview (xero_get_overview)

Retrieve organization information, chart of accounts, tax rates, tracking categories, and currencies.

Parameter	Type	Required	Description
category	string	Yes	organisation, accounts, taxRates, trackingCategories, or currencies
where	string	No	Filter expression for accounts (e.g., Type=="REVENUE")
includeArchived	boolean	No	Include archived records (default: false)

Use this tool to help agents understand your chart of accounts structure before running reports.

Security & Limitations

Security

• OAuth 2.0 with single-use refresh tokens - Prevents token replay attacks through distributed locking
• Read-only access - All API calls are GET requests only; no write operations are possible through this integration
• Tenant isolation - Each tenant's Xero connection and tools are scoped to that tenant only
• Encrypted token storage - OAuth tokens are stored encrypted at rest
• Audit logging - Every tool execution is logged with the agent, query parameters, and results

Rate Limits

The Xero API enforces rate limits that apply to your connection:

Limit	Value	Scope
Per-minute	60 calls/minute	Per Xero organization
Daily	5,000 calls/day	Per Xero organization
Concurrent	5 simultaneous	Per Xero organization

If an agent hits a rate limit, the tool automatically retries with exponential backoff up to 3 times.

Limitations

• Read-only - Cannot create, update, or delete any Xero records
• Single organization - Only one Xero organization per Control Bridge tenant
• Report formats - Reports are flattened into structured JSON for agent consumption; the raw Xero report format is not exposed
• No file attachments - Cannot access files or attachments linked to Xero records
• Date-limited usage data - Azure usage reports and similar time-series data may have availability constraints based on your Xero plan

Troubleshooting

OAuth Connection Fails

Problem: Authorization fails or you are redirected back with an error

Solutions:

1. Ensure you are signed in to Xero as an administrator before clicking Connect
2. Verify your Xero subscription is active
3. Check that your browser allows popups from the Xero domain
4. Try a different browser if the issue persists

Connection Test Fails After Connecting

Problem: The Test Connection button returns an error

Solutions:

1. Your Xero OAuth token may have expired - click Reconnect to re-authorize
2. Verify your Xero account still has an active subscription
3. Check that the Xero organization you connected is still accessible in your Xero account

Agent Cannot Find Xero Tools

Problem: Xero tools do not appear when editing an agent

Solutions:

1. Verify the Xero connection is active at Build > Connections > Xero
2. Check that the "Xero" tool group exists at Build > AI Agents > Tool Groups
3. Assign the Xero tool group (not individual tools) to the agent
4. Refresh the page and try again

Agent Returns "Xero Connection Needs Reauthorization"

Problem: Agent execution returns an authorization error

Solutions:

1. Navigate to Build > Connections > Xero
2. Click Reconnect to re-authorize via OAuth
3. After reconnecting, run the Test Connection to confirm it works
4. Retry the agent execution

Report Returns No Data

Problem: xero_get_report returns empty results

Solutions:

1. Verify the date range is correct - some reports (P&L, BankSummary) require fromDate and toDate
2. Confirm the Xero organization has transactions in the specified date range
3. For AgedReceivables/AgedPayables reports, ensure a valid contactId is provided
4. Check that your Xero subscription includes the requested report type

Rate Limit Errors

Problem: Agent receives "Xero API rate limit reached"

Solutions:

1. The agent will automatically retry with backoff - wait a moment and the request should succeed
2. If errors persist, reduce the frequency of Xero queries by spacing out agent executions
3. Avoid running multiple agents that query Xero simultaneously

Best Practices

Agent Instructions

Help your agents use Xero tools effectively:

When working with Xero financial data:
1. Use xero_search to find invoices or contacts before retrieving details
2. For financial reports, always specify date ranges to get meaningful data
3. Use the xero_get_overview with category="accounts" to understand the chart
   of accounts before interpreting report results
4. When looking up a specific invoice, search for it first to get the ID,
   then use xero_search_invoices to retrieve full details

Configuration

• Assign the Xero tool group only to agents that genuinely need financial data access
• Consider creating a dedicated "Finance Agent" with the Xero tool group rather than adding it to general-purpose agents
• Test your agents with common financial queries after setup to verify they interpret data correctly

Security

• Regularly review agent execution logs to monitor what financial queries are being run
• If an employee who managed the Xero connection leaves, reconnect with an active administrator account
• Disconnect the Xero integration if your organization stops using Xero or switches accounting platforms

Related Topics

• Tools Overview - All available agent tools
• Agents - Configure agents to use tools
• Agent Executions - View tool execution logs
• QuickBooks Tools - Alternative accounting integration for QuickBooks Online