Epicor Kinetic and BambooHR integration

What moves between them

The flow runs one direction, from BambooHR into Epicor Kinetic. ml-connector reads new hires, job and department changes, and terminations from BambooHR and keeps the matching payee record and headcount reference in Epicor aligned, mapping each worker to a valid Epicor record by a stable BambooHR employee id. Department and cost center come from BambooHR job information and are carried so downstream expense and labor postings in Epicor land on real dimensions. Because BambooHR holds no vendors, invoices, purchase orders, or GL accounts, ml-connector never reads finance data from it and never writes financial entries back into BambooHR; the Epicor ledger stays authoritative.

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, refreshes the one-hour access token before it expires using the offline_access refresh token, and scopes every call to the customer's subdomain since the token URL is subdomain-specific. On the Epicor side it sends Basic Auth plus the x-api-key header, or an OAuth2 bearer plus the API Key, and includes the mandatory Company segment in every v2 path. BambooHR webhooks arrive signed with HMAC-SHA256 over the raw body plus timestamp, so each is verified with a timing-safe compare and then triggers a GET on the employee to pull current fields, because the payload itself carries only the id and changedFields. Epicor has no push, so it is polled on a schedule with $top and $skip paging and a date filter for changed rows. Worker writes into Epicor follow its two-step GetNew then UpdateMaster pattern, and since neither system has an idempotency key header, ml-connector dedupes on the BambooHR employee id and a BullMQ jobId, using Epicor's own uniqueness validation as a backstop. It honors a BambooHR 503 with Retry-After and treats a 409 on a duplicate email as an existing record rather than an error. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized contract manufacturer with roughly 400 employees across two plants runs Epicor Kinetic for production, procurement, and finance, and uses BambooHR as its HRIS. Before the integration, HR added and offboarded staff in BambooHR while a finance clerk separately keyed the same people into Epicor as expense payees and updated their department whenever someone transferred, which meant terminated staff lingered as active payees and labor costs were tagged to the wrong cost center. With Epicor Kinetic and BambooHR connected, each hire, transfer, and termination flows into Epicor within the polling window, the payee record is created or deactivated to match, and the department and cost center from BambooHR job information ride along so postings reconcile. The duplicate data entry stops and the people side of the ledger stays current.

What you can do

• •Sync BambooHR new hires, role changes, and terminations into Epicor Kinetic payee and reference records.
• •Carry department and cost center from BambooHR job information so Epicor postings land on valid dimensions.
• •Verify each BambooHR webhook by HMAC-SHA256, then fetch the full employee before updating Epicor.
• •Bridge BambooHR OAuth 2.0 token refresh and Epicor Basic Auth plus API Key, with the mandatory Company segment.
• •Poll Epicor on a schedule with dedup on the employee id, retries, and a full audit trail on every record.

Questions

Which direction does data move between Epicor Kinetic and BambooHR?

The flow is one direction, from BambooHR into Epicor Kinetic. Employees, job and department changes, and terminations move from BambooHR into Epicor as payee and reference records. BambooHR has no vendors, invoices, purchase orders, or GL accounts, so ml-connector never reads finance data from it and never writes financial entries back into BambooHR.

Does BambooHR push changes, or does ml-connector poll for them?

BambooHR pushes signed webhooks on employee created, updated, and deleted events, which ml-connector verifies by HMAC-SHA256. The payload is lightweight and carries only the employee id and a changedFields list, so ml-connector then calls GET on that employee to pull current values. Epicor Kinetic has no native webhooks, so it is read by polling on a schedule with OData $top and $skip paging.

How does the integration handle authentication on each side?

On BambooHR it runs OAuth 2.0 Authorization Code and refreshes the one-hour access token using the offline_access refresh token, scoping each call to the customer subdomain since the token URL is subdomain-specific. On Epicor Kinetic it sends Basic Auth plus the x-api-key header, or an OAuth2 bearer plus the API Key, and always includes the Company segment required by the v2 URL. Both credential sets are stored encrypted.