Oracle NetSuite and BambooHR integration

What moves between them

The flow runs from BambooHR into Oracle NetSuite. ml-connector reads employee creates, updates, and terminations from BambooHR and writes them onto NetSuite employee records, so the NetSuite people list reflects HR hires, role and department moves, and departures. BambooHR department and division values are mapped to NetSuite departments, classes, and locations so the org structure used for accounting dimensions stays aligned. Because BambooHR has no vendors, invoices, or GL accounts, no finance records move in either direction, and ml-connector does not write HR fields such as compensation history back into BambooHR.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the NetSuite side it signs a JWT with the customer private key, exchanges it for an M2M access token, and refreshes that token when it expires after 60 minutes, addressing the correct account-specific URL per customer. On the BambooHR side it uses OAuth refresh tokens or API key Basic auth against the customer subdomain, since BambooHR token URLs are subdomain-scoped rather than global. When BambooHR pushes a webhook, ml-connector verifies the HMAC-SHA256 signature with a timing-safe comparison, then calls GET on the employee by ID to pull the current fields, because the webhook payload only names the employee and changed fields. Employees are matched to existing NetSuite records by external ID, and a POST with that external ID upserts so retries and duplicate webhook deliveries do not create duplicate employees. A scheduled BambooHR poll backfills anything a webhook missed. BambooHR throttling returns 503 with Retry-After and NetSuite returns 429, so ml-connector backs off and retries on both. Department and division are mapped first, so every synced employee references a NetSuite department, class, or location that already exists.

A real-world example

A professional services firm of about 600 people runs Oracle NetSuite for finance and project accounting and uses BambooHR as the HR system of record. Before the integration, an admin re-keyed every new hire, transfer, and termination into NetSuite by hand, and the employee list drifted out of date between updates, so expense approvals and project staffing in NetSuite referenced people who had already left or moved teams. With Oracle NetSuite and BambooHR connected, each BambooHR change reaches NetSuite within the sync window, departments line up with NetSuite accounting dimensions, and the finance team stops maintaining a second copy of the staff roster by hand.

What you can do

• •Sync new hires, role and department changes, and terminations from BambooHR onto Oracle NetSuite employee records.
• •Map BambooHR department and division to NetSuite department, class, and location for consistent dimension tagging.
• •Bridge BambooHR OAuth or API key auth and the NetSuite certificate-signed M2M token, refreshing each before it expires.
• •Verify each BambooHR webhook signature, then re-fetch the changed employee to apply current field values.
• •Match employees by external ID so retries and duplicate webhook deliveries never create duplicate NetSuite records.

Questions

Which direction does data move between Oracle NetSuite and BambooHR?

The flow runs from BambooHR into Oracle NetSuite. Employee records and org structure move from BambooHR, the HR system of record, onto NetSuite employee records and accounting dimensions. BambooHR has no vendors, invoices, or GL accounts, so no finance data moves the other way, and ml-connector does not write HR fields back into BambooHR.

How does ml-connector handle the different authentication on each side?

NetSuite uses certificate-based OAuth 2.0 Client Credentials, where the connector signs a JWT with a private key and there is no client secret, and tokens expire after 60 minutes. BambooHR uses OAuth 2.0 Authorization Code with subdomain-scoped token URLs, or legacy API key Basic auth. ml-connector stores both credential sets encrypted and refreshes each token before it expires.

What happens when a BambooHR webhook arrives?

ml-connector verifies the HMAC-SHA256 signature over the raw body plus timestamp using a timing-safe comparison. Because the BambooHR payload only carries the employee ID and the list of changed fields, the connector then calls the get-employee endpoint to fetch current values before writing to NetSuite. A scheduled poll backfills any change a webhook missed.