Sage 50 and BambooHR integration

What moves between them

The main flow runs from BambooHR into Sage 50. ml-connector reads new hires, terminations, role and org changes, and compensation updates from BambooHR and writes them into the Sage 50 Employee object through the local agent, creating or updating each record. BambooHR department and division values are aligned with Sage 50 nominal or GL account codes so headcount maps to the right ledger dimensions. The cadence is event-driven where possible: a BambooHR webhook signals a change, ml-connector calls the BambooHR employee endpoint to pull the current fields, and the agent applies them to Sage 50 on its next interactive run. A scheduled poll backfills anything a webhook missed. BambooHR remains the HR system of record, so ml-connector does not write payroll or finance data back into it.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the BambooHR side it runs the OAuth 2.0 Authorization Code flow against the customer's own subdomain, requests offline_access so it holds a refresh token, and refreshes the one-hour access token before it expires; for older tenants it can fall back to API key Basic auth. The Sage 50 side cannot be reached over the internet, so a lightweight agent on the customer's Windows machine opens the company file with the dedicated Sage 50 username, password, and US Application ID, and applies employee changes through the SDK. Because that SDK needs an interactive desktop session and takes an exclusive lock, the agent must not run while a user has Sage 50 open under the same account, and the machine has to stay logged in. BambooHR webhooks are verified with SHA-256 HMAC over the raw body plus the dispatch timestamp using a constant-time compare, then the current employee is fetched, since the payload only carries the employee id and a changedFields list. BambooHR has no idempotency key, so ml-connector dedupes on the BambooHR employee id and stores the Sage-assigned internal id in its own mapping table, querying Sage 50 for an existing record before creating one. Department and division codes are mapped first so every employee lands on a valid Sage nominal or GL dimension. BambooHR throttling returns 503 with a Retry-After header, which ml-connector honors with backoff, and the SDK version is pinned to the installed Sage 50 year so an upgrade does not break the agent. UK-only fields such as VAT and CIS are left untouched on the finance side. Every record carries a full audit trail and can be replayed if a downstream write fails.

A real-world example

A 180-person engineering firm in the UK runs Sage 50 Accounts for its books and BambooHR for HR. Before the integration, every hire, leaver, and promotion was entered twice: once by HR in BambooHR and again by the finance team into the Sage 50 employee list and the department codes used for cost reporting. Leavers were often missed on the Sage side for weeks, and department reassignments drifted out of step, so labor cost reports were tagged to the wrong nominal codes. With Sage 50 and BambooHR connected, a hire or status change in BambooHR flows into the Sage 50 Employee object within the agent's next run, and the department mapping keeps each person on the correct nominal dimension. The duplicate entry is gone and the finance employee list matches HR.

What you can do

• •Create and update Sage 50 employee records from BambooHR hires, terminations, and role changes through the local Windows agent.
• •Align BambooHR departments and divisions with Sage 50 nominal or GL account codes so headcount maps to the right ledger dimensions.
• •Bridge BambooHR OAuth 2.0 on the customer subdomain with the Sage 50 SDK username, password, and Application ID login.
• •React to BambooHR employee webhooks, verified with SHA-256 HMAC, and poll on a schedule because Sage 50 cannot be pushed to.
• •Deduplicate on the BambooHR employee id with a stored Sage internal id, and replay any failed write from a full audit trail.

Questions

Which direction does data move between Sage 50 and BambooHR?

The main flow is BambooHR into Sage 50. Hires, terminations, role changes, and compensation updates move from BambooHR into the Sage 50 Employee object, and BambooHR departments and divisions are aligned to Sage 50 nominal or GL codes. BambooHR stays the HR system of record, so ml-connector does not write finance or payroll data back into it.

How does ml-connector reach Sage 50 if it has no cloud API?

Sage 50 is desktop software with no REST API, so ml-connector runs a small agent on the customer's Windows machine that uses the Sage 50 SDK, the .NET SDK in the US edition or Sage Data Objects in the UK. The agent signs in with a dedicated Sage 50 username and password and applies employee changes locally. It needs an interactive desktop session and an exclusive lock on the company file, so the machine must stay logged in and Sage 50 should not be open under the same account while it runs.

Does the integration use BambooHR webhooks or polling?

Both. BambooHR pushes employee.created, employee.updated, and employee.deleted webhooks signed with SHA-256 HMAC, which ml-connector verifies and uses to fetch the changed employee right away. Because Sage 50 itself cannot receive a push and the local agent only runs in an interactive session, a scheduled poll also runs to catch anything a webhook missed and to apply changes on the agent's next pass.