Getting started with QuickBooks Desktop

This guide is for you, the Apideck customer building an integration. It covers enabling the connector, understanding how a QuickBooks Desktop connection works, onboarding your first consumer, and making your first API call through Unify.

QuickBooks Desktop is on-premises: your consumer's data lives in a company file on a Windows machine, and the connection runs through the QuickBooks Web Connector. Apideck hosts the server side, so there is no OAuth app to register and no partnership to apply for — a free Intuit Developer Account is all that's needed, and only for testing.

💡 New to QuickBooks Desktop? It has no cloud sandbox. To try the full flow end to end you'll need a real QuickBooks Desktop install on Windows. See the Test Instance Guide for the quickest way to stand one up.

---

Prerequisites

• An Apideck account with the QuickBooks Desktop connector enabled (Unify → Configure → QuickBooks Desktop).
• For testing: a QuickBooks Desktop install on Windows (sample company file, a 30-day Enterprise trial, or a free NFR developer copy). See the Test Instance Guide.
• No Intuit app credentials, partnership, or IP allow-listing are required.

---

How a connection works

Unlike OAuth connectors, QuickBooks Desktop is configured per consumer on their own machine:

1. You enable the connector and create a connection for a consumer (via the Vault UI or the Vault API).
2. Vault generates a Web Connector setup file (apideck.qwc) and a Web Connector password for that connection.
3. Your consumer installs the .qwc in the QuickBooks Web Connector on the Windows machine that runs QuickBooks Desktop, and enters the password.
4. The Web Connector polls Apideck's hosted sync service on a schedule (about every minute by default) and syncs data both ways.

A connection stays in state: "added" and is not yet callable until the Web Connector authenticates for the first time. Once it does, the connection becomes callable and data starts flowing.

---

Step 1 — Enable the connector

In the Apideck dashboard, go to Unify → Configure → QuickBooks Desktop and enable it. There are no credentials to fill in — QuickBooks Desktop has no OAuth app model, so enabling the connector is all that's required on your side.

Step 2 — Onboard a consumer

Create a connection for the consumer (through Vault — either the hosted Vault UI or the Vault API) and share the connection details with them. The consumer then completes the Web Connector setup on their Windows machine.

The full consumer-facing walkthrough — downloading apideck.qwc, adding it to the Web Connector, entering the password, and confirming the sync — is documented in the connection guide. Point your consumers there.

Step 3 — Confirm the connection is live

After the consumer finishes the Web Connector setup, the connection moves out of state: "added" and becomes callable. You can check the connection's state in the dashboard or via the Vault API. Until then, API calls against the connection return a "connection not yet authorized" error — this is expected while setup is still in progress.

Step 4 — Make your first API call

Once the connection is callable, call any Accounting resource through Unify with the standard Apideck headers (x-apideck-service-id: quickbooks-desktop):

curl 'https://unify.apideck.com/accounting/customers' \
  -H 'Authorization: Bearer {APIDECK_API_KEY}' \
  -H 'x-apideck-app-id: {APP_ID}' \
  -H 'x-apideck-consumer-id: {CONSUMER_ID}' \
  -H 'x-apideck-service-id: quickbooks-desktop'

{
  "status_code": 200,
  "data": [
    { "id": "80000001-1234567890", "display_name": "Acme Co", "company_name": "Acme Co" }
  ],
  "meta": { "items_on_page": 20, "cursors": { "next": "…" } }
}

---

What you can do

QuickBooks Desktop supports 11 unified Accounting resources. Full CRUD unless noted (R = read-only):

Resource	Operations
customers, suppliers	CRUD
invoices, credit-notes	CRUD
invoice-items	CRUD
bills, purchase-orders	CRUD
payments, bill-payments	CRUD
journal-entries	CRUD
ledger-accounts	CRUD
tax-rates	R

For connector-specific behaviors and limitations, see the Gotchas tab.

Good to know

• Sync cadence. With the Web Connector's auto-run on (the default, ~1 minute), the connection behaves close to live but syncs on a short background cycle. A change may take about a minute to appear — that delay is normal.
• Keep the Web Connector open. Syncing only runs while the Web Connector is open and the machine is awake. Minimizing it, closing it, or letting the machine sleep stops syncing. This is the most common cause of "it stopped working."
• Pagination. List endpoints paginate by cursor — follow meta.cursors.next until it's null. QuickBooks Desktop does not return a total record count, so meta.total_count won't appear.
• Writes. Some resources only accept a minimal field set on create and need a follow-up update for header/metadata fields; line items on invoices, bills, credit notes, and purchase orders can't be changed on update (recreate to change lines). See the Gotchas tab for the specifics per resource.

Next steps

• 🧪 Test Instance Guide — stand up QuickBooks Desktop on Windows for development.
• 🔌 Connection guide — the consumer-facing Web Connector walkthrough.
• ⚠️ Gotchas — connector-specific behaviors per resource.