Setup guide

From nothing to QuickBooks data in HubSpot. The in-app setup wizard follows these same five steps and fills in your personal token and password for you.

1. Requirements

• QuickBooks Desktop Enterprise, Premier or Pro, 2019 or newer. One company file per install. Multi-currency company files aren't supported.
• QuickBooks Web Connector (it comes with QuickBooks Desktop).
• The Windows computer that hosts the company file, left switched on. It needs .NET Framework 4.8 and Windows PowerShell 5.1, which Windows 10, Windows 11 and current Windows Server already include.
• Windows administrator rights on that computer, and the QuickBooks Admin user.
• A HubSpot user who can install apps in your portal (a Super Admin, for example). Any HubSpot tier works.

2. Connect HubSpot

1. Open https://deskbridge.sctechnology.net/install and click Connect HubSpot.
2. Choose your portal and approve the access HubSpot lists. The install page explains why each item is needed.
3. You land in the DeskBridge setup wizard. In the background, DeskBridge adds its qbd_* properties and creates the QuickBooks Invoices deal pipeline. If step 1 of the wizard says they're missing, click Re-run HubSpot setup.

To come back later, sign in at https://deskbridge.sctechnology.net/login with your email and we'll send you a one-time link.

3. Install the agent on the QuickBooks computer

1. On the computer that hosts the company file, download agent.zip from wizard step 2 and unzip it (for example to C:\DeskBridge).
2. In the wizard, click Generate agent token. The token is shown once. Generating a new one cancels the old one.
3. Open Windows PowerShell as Administrator in the unzipped folder and run the command the wizard shows, which looks like:

   powershell -ExecutionPolicy Bypass -File .\install.ps1 -Token <your-token> -CloudUrl https://deskbridge.sctechnology.net

   Windows marks downloaded scripts as untrusted, which is why the command includes -ExecutionPolicy Bypass. You can also run Unblock-File .\install.ps1, .\uninstall.ps1 first.
4. The installer registers a Windows service that restarts itself after a failure, checks that the service responds, and confirms its first check-in with DeskBridge. The wizard page updates on its own once the agent connects.

4. Add the application to QuickBooks Web Connector

1. Download the .qwc file from wizard step 3 to the QuickBooks computer.
2. Open QuickBooks as Admin with the company file open. Single-user mode is easiest for this one step.
3. Open QuickBooks Web Connector → Add an Application → choose the .qwc file.
4. When QuickBooks asks for permission, choose "Yes, always; allow access even if QuickBooks is not running". This is what lets syncs run overnight while nobody has QuickBooks open.
5. In Web Connector, enter the password shown in the wizard, tick Auto-Run, and click Update Selected.
6. Back in the wizard, confirm the company file path (for example C:\Users\Public\Documents\Intuit\QuickBooks\Company Files\Acme.qbw) and save.

5. Choose what to sync

• Items → Products: on or off. You can limit it by item type (Inventory, Non-inventory, Service, Inventory Assembly), active items only, and name prefixes (for example WID-, SVC-). You can also choose where the SKU comes from. Items that later drop out of your filter are marked inactive in HubSpot, not deleted.
• Customers → Companies are always synced. Contacts (the customer's primary email) are optional. With Match existing companies by name on (the default), DeskBridge links to companies you already have instead of creating duplicates.
• Invoices → Deals: on or off. You can also set how far back the first sync goes (365 days by default, from 1 day to 10 years). Open invoices always come across, whatever their age.
• Schedule: how often Web Connector runs, every 5 to 120 minutes. 15 is the default, and 10–30 works well for most companies.
• Never overwrite: HubSpot fields that DeskBridge should never change after it creates the record.

You can change all of these later under Settings.

6. Run the baseline

Click Start baseline. The next Web Connector run starts pulling records, or click Update Selected in Web Connector to start straight away. Large company files take several runs. The status page shows progress, and syncing carries on by itself after that.

7. What you'll see in HubSpot

• Companies for each QuickBooks customer (jobs roll up to their parent), with qbd_ fields for list ID, customer type, terms, balance, total balance, active flag and last synced time.
• Contacts linked to their company, if you turned them on.
• Products for the items that match your filters.
• A QuickBooks Invoices deal pipeline with stages Open, Partially Paid, Paid (closed won) and Voided (closed lost). Each deal has the invoice total including tax, the invoice date as close date, the due date, balance and memo, plus line items linked to products.

If someone edits a standard field (like a company phone number) in HubSpot, that edit stays until the same field changes in QuickBooks. qbd_* fields always reflect QuickBooks.

8. Day to day: status, pause, alerts

• The Status page shows agent and Web Connector health, the last sync, record counts and recent activity.
• Pause stops all reads and HubSpot writes until you resume. While paused, no alerts are sent about the agent.
• You'll get an email if the agent is offline for more than 2 hours, if Web Connector stops running (no sync for three scheduled intervals), or if HubSpot gets disconnected. That last email includes a reconnect link. We're alerted too, and usually get in touch first.

9. Troubleshooting

Web Connector won't add the application, or keeps asking for permission

Open QuickBooks as Admin with the company file open, in single-user mode, then answer the permission prompt with "Yes, always; allow access even if QuickBooks is not running".

Web Connector is stuck on "Connecting to QuickBooks…"

Exit Web Connector completely, end any background QBW32.EXE process in Task Manager, reopen Web Connector and click Update Selected.

The status page says the agent is offline

On the QuickBooks computer, run sc.exe query DeskBridgeAgent. If it's stopped, start it with sc.exe start DeskBridgeAgent. If it's missing, generate a new token in the wizard and run the installer again.

The status page says the company file is unsupported (multi-currency)

DeskBridge v1 doesn't support multi-currency company files and stops safely without syncing. Tell us if you need it.

HubSpot disconnected

Use the reconnect link in the alert email, or open https://deskbridge.sctechnology.net/install and click Connect HubSpot again. QuickBooks keeps being read in the meantime, and the backlog is sent to HubSpot once you reconnect.

Still stuck? Email [email protected] with your HubSpot portal ID and company file name. More fixes are on the support page.

10. Uninstalling

1. In Web Connector, select the DeskBridge application and click Remove.
2. On the QuickBooks computer, run .\uninstall.ps1 from the agent folder in an Administrator PowerShell window. This removes the service and its URL reservation.
3. In HubSpot, open Settings → Integrations → Connected apps and uninstall DeskBridge.
4. Cancel your subscription, or email us to do it for you.

Records that were already synced stay in HubSpot. Ask us to delete what we store about your install, as described in the privacy policy.