QuickBooks Desktop and BambooHR integration

What moves between them

The main flow runs from BambooHR into QuickBooks Desktop. When BambooHR records a new hire, a termination, or an employee field change, ml-connector reads the current employee through the BambooHR API and writes it into the QuickBooks Desktop employee list, adding new staff and updating name, status, and department on existing ones. Department and division from BambooHR job information can be carried into QuickBooks as a class or account dimension so labor is grouped consistently. BambooHR holds no vendors, invoices, purchase orders, or GL accounts, so nothing financial is written back to BambooHR; the cadence follows BambooHR webhooks with a polling pass each Web Connector cycle as a safety net.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the BambooHR side it uses the OAuth 2.0 bearer token, refreshes it when a call returns 401 since the token lasts only one hour, and keeps the per-company subdomain because BambooHR scopes both its API and its token URL to that subdomain. On the QuickBooks side it answers the Web Connector authenticate call, hands back a session ticket, and returns QBXML blobs for each request, since QuickBooks Desktop must be running and only the Web Connector can reach the company file. BambooHR webhooks are verified with the shared HMAC SHA-256 key using a constant-time compare, and because the payload is lightweight the connector then calls GET /api/v1/employees/{id} for the full record. Each worker is matched by name or by a stored ListID, so a retried sync updates rather than duplicates, and every EmployeeMod re-queries the current EditSequence first or QuickBooks rejects it with error 3200. Every record carries a full audit trail and can be replayed if a downstream write fails.

A real-world example

A growing services firm of about 300 staff runs payroll and the books in QuickBooks Desktop Enterprise on a Windows server, and HR runs BambooHR for hiring, departments, and terminations. Before the integration, every new starter and leaver was typed into BambooHR by HR and then keyed again into the QuickBooks employee list by the bookkeeper, so payroll runs missed people, paid leavers, or used stale departments until someone caught it. With QuickBooks Desktop and BambooHR connected, a hire or a termination in BambooHR flows into the QuickBooks employee list on the next Web Connector cycle with the right department, the double entry disappears, and the payroll roster reflects who actually works there at run time.

What you can do

• •Create and update employees in the QuickBooks Desktop employee list from BambooHR hires, terminations, and field changes.
• •Carry BambooHR department and division into QuickBooks Desktop as a class or dimension so labor is grouped consistently.
• •Bridge BambooHR OAuth 2.0 tokens with the QuickBooks Web Connector session handshake on each customer subdomain.
• •Listen to BambooHR employee webhooks and poll QuickBooks on each Web Connector cycle as a safety net.
• •Match each worker by name or stored ListID with audit and replay on every record so retries never duplicate staff.

Questions

Which direction does data move between QuickBooks Desktop and BambooHR?

The main flow is BambooHR into QuickBooks Desktop. Employee records, hires, terminations, and department changes move from BambooHR into the QuickBooks employee list. BambooHR has no vendors, invoices, or GL accounts, so ml-connector does not write any financial data back into BambooHR.

How does the integration reach QuickBooks Desktop when it has no cloud API?

QuickBooks Desktop has no hosted endpoint, so ml-connector exposes a SOAP service that the free QuickBooks Web Connector polls on a set interval. The Web Connector authenticates with a session ticket and relays QBXML employee messages to QuickBooks. QuickBooks must be running and the company file open for a sync cycle to process.

How are duplicate employees and conflicting edits avoided?

ml-connector matches each BambooHR worker to a QuickBooks employee by name or by a stored ListID, so a retried or repeated sync updates the existing record instead of adding a second one. Before any update it re-queries the current EditSequence, which QuickBooks requires or it returns error 3200. BambooHR duplicate emails return 409 Conflict, which acts as a further guard.