You connect your AI client to DeepLedger once. That one connection reaches every QuickBooks Online company you have access to in DeepLedger. To move between companies, ask the AI agent to switch, confirm the company name, and keep working.
This guide follows the flow in order: see your companies, switch, confirm, and remember the one rule about how switching is shared. The last section is for developers running unattended agents. Everyone else can stop before it.
How It Works in 30 Seconds
- Each company connects to QuickBooks once. A QuickBooks admin authorizes that company in DeepLedger. Intuit documents who can connect and manage apps.
- You connect your AI client once. Claude, ChatGPT, Grok, or Claude Code signs in to DeepLedger as you. You can reach every company your DeepLedger account can.
- One company is active at a time. Every request goes to the active company. Switching changes which company that is.
- Your active company follows you. It is stored per person, not per client. Switch in Claude, and ChatGPT follows on its next request.
Connecting your AI client does not connect a company to QuickBooks. That happens per company, by its admin, and a company in your list may still need its QuickBooks connection repaired before reports and writes work.
If you have not connected a client yet, start with the Claude, ChatGPT, Grok, or Claude Code guide, then come back here.
Step 1: See Your Companies
Ask the AI agent:
Which companies can I work in? Show the active company and each QuickBooks connection status.
It lists every company you can reach, marks the active one, and shows whether each QuickBooks connection is healthy.
Step 2: Switch to the Company You Want
Ask:
Switch to Acme Consulting. Confirm its QuickBooks company name, then show its August 2026 profit and loss on an accrual basis. Do not record anything.
Use your own company name, period, and report basis. After the switch, every later request goes to that company until you switch again.
Two things can come up:
- Two companies have similar names. DeepLedger returns the matching candidates instead of guessing. Ask the AI agent to switch using the organization ID from that list.
- The switch works but the report fails. A switch can succeed even when that company's QuickBooks connection has expired. Reconnect the company in the portal, then try the report again.
Step 3: Confirm Before You Change Anything
Every tool result names the company it came from in a company field: the DeepLedger company name, the QuickBooks company name, and the QuickBooks realm ID when available. Before the AI agent records anything, ask:
Read the active company profile and confirm which books you will change before preparing any entries.
A chat answer that does not name the company is not confirmation. Read the name in the result.
The One Rule: Your Active Company Is Shared
Your active company is stored once per person, not once per client. That has one consequence worth remembering:
If you switch to Blue River Bakery in Claude, your next request in ChatGPT, Grok, or Claude Code also goes to Blue River Bakery.
For one person working one conversation at a time, this is what you want. Two of your sessions running at the same time can step on each other, because a switch in one moves the other. If you need sessions that stay on their own companies, pin each one as described in the developer section below.
DeepLedger adds a warning to the next result when the active company was changed from the portal. It does not add one when another AI client switched. Treat the warning as a courtesy, not a lock. The company named in each result is the record.
Switch From the Portal Instead
Open Settings, then the Company and QBO Connect tab. Each company card has a Use for AI button. Select it, and the card shows Active for AI.
The portal's own company selector is separate. Browsing company A's tasks does not move your AI agent off company B. Only Use for AI or a switch in chat does that.
After switching in the portal, ask the AI agent to read the company profile so you see the change from the AI side too.
For Developers: Unattended and Parallel Agents
Everything above also applies to a headless agent using your personal API key. The key acts as you and follows your active company.
One company at a time. Call qbCompanyProfile with:
{ "operation": "list" }
Pick the organizationId of the company you want, then switch:
{ "operation": "switch", "organizationId": "YOUR_DEEPLEDGER_ORGANIZATION_ID" }
Replace the placeholder with the ID from the list. A unique name also works, but the ID is safer in code. This pattern suits a supervised job that finishes one company before starting the next. It does not protect the job from a switch made in another client signed in as you.
Several companies at the same time. Send this header on every MCP request, alongside authentication:
X-Organization-Id: YOUR_DEEPLEDGER_ORGANIZATION_ID
Use the DeepLedger organization ID from the list, not the QuickBooks realm ID. The header selects the company for that request only and leaves your shared active company alone. DeepLedger still checks that you can access the organization.
Rules for pinned requests:
- Give each company's job its own client or request context. Do not share one mutable header between jobs running at once.
- A pinned caller cannot use the switch operation. Change the header to work in another company.
- Record the company named in each result next to the work it did.
Organization routine credentials are already fixed to one company. A header cannot move them.
For framework setup, see CrewAI, LangChain, and Copilot Studio.
If Something Does Not Match
| Symptom | What to do |
|---|---|
| A company is missing from the list | Check your DeepLedger membership or company assignment. |
| Two companies have similar names | Switch by the organization ID from the list. |
| The switch works but a report fails | Reconnect that company's QuickBooks connection in the portal. |
You see NO_ACTIVE_COMPANY | List your companies, then switch to one. |
You see SWITCH_NOT_ALLOWED | The request is pinned by a header or uses a fixed organization credential. Change the header instead. |
| The company changes in the middle of a job | Pause, review the work already done, then pin the remaining requests with a header. |
| The client cannot find the company operations | Refresh or reconnect the DeepLedger MCP server in the client, then try again. |
An existing connection does not tell you which company is active. Confirm it at the start of each session. If the company in a result still looks wrong, email support@deepledger.ai with the client name and the error. Do not include credentials.
Frequently Asked Questions
Can one DeepLedger connection reach multiple QuickBooks companies?
Yes. One personal connection reaches every company your DeepLedger account can access. Each company still needs its own QuickBooks connection. Connecting your AI client does not connect any company to QuickBooks.
How do I switch companies during a conversation?
Ask the AI agent to list your companies, then switch to the one you want and confirm its name. Behind the scenes it calls qbCompanyProfile with the switch operation. If two names are similar, pick the organization ID from the list it returns.
Does switching in one AI client affect another?
Yes. Your active company is stored once per person, so a switch in Claude carries over to your next request in ChatGPT, Grok, or Claude Code. Requests pinned with an X-Organization-Id header and organization routine credentials are the exceptions.
Will I always get a warning when the company changes?
No. A change made in the portal adds a warning to the next result, but a switch from another AI client does not. Read the company named in each result, and pin parallel jobs with a header.
Can I choose the active company in the portal?
Yes. Open Settings, then Company and QBO Connect, and select Use for AI on the company card. The portal's own company selector is separate, so browsing another company does not move your AI agent.
Can headless agents process different companies at the same time?
Yes, if each job sends an X-Organization-Id header on every request. Do not rely on the shared active company for parallel jobs. Organization routine credentials are already fixed to their company.