FreshBooks and UKG integration

What moves between them

The primary flow is UKG into FreshBooks. After each payroll run, ml-connector reads UKG payroll journal data via /services/payroll/v1/thirdpartypay, maps the GL account segments and cost centers to corresponding FreshBooks accounts, and posts the labor cost journals into FreshBooks' chart of accounts. Employee master data flows the same direction: ml-connector fetches the employee roster from UKG (via the two-pass employee fetch), and writes or updates employee records in FreshBooks so headcount and compensation details stay aligned. Reference data such as cost centers and GL account mappings are configured once and reused for every payroll cycle. Journal entries in FreshBooks are created by ml-connector and can be read back for audit; no data flows back to UKG.

How ml-connector handles it

ml-connector stores both credential sets encrypted and bridges two different authentication models: FreshBooks' user-delegated OAuth and UKG's Basic Auth plus API keys (or UKG's OAuth 2.0 client credentials if webhooks are enabled). On the UKG side, ml-connector handles the two-pass employee fetch by first calling /personnel/v1/employee-ids to get internal UUIDs, then fetching each employee's full profile from /personnel/v1/employees/{id}. If using UKG webhooks, OAuth tokens expire after 1 hour and must be refreshed before calls fail. On the FreshBooks side, ml-connector maps UKG's GL account segments and cost center codes to FreshBooks' chart of accounts, ensuring every payroll journal line references an account that exists. Because FreshBooks accepts journal entries via its journal_entries endpoint, ml-connector creates a single journal entry per payroll run with multiple lines, one for each cost center and GL account combination. ml-connector polls on a cadence tied to your payroll calendar (weekly, bi-weekly, or monthly) so payroll journals are reliably captured regardless of webhook delivery delays. Every record carries a full audit trail and can be replayed if a downstream journal entry fails to post.

A real-world example

A small professional services firm runs FreshBooks for invoicing and accounting, and UKG for payroll and time tracking across two offices. Before integration, the accounting team exported payroll registers from UKG monthly and manually re-entered the labor costs into FreshBooks' general ledger, allocating amounts to the correct office and expense categories. With UKG and FreshBooks connected, each monthly payroll run automatically posts the labor journal into FreshBooks, keyed to the matching office cost centers, and employee changes in UKG are reflected in FreshBooks' staff records. The manual re-keying step is eliminated, and month-end close begins with labor accounts already reconciled.

What you can do

• •Post UKG payroll GL journals into FreshBooks' chart of accounts, allocated to the correct cost centers, after every pay run.
• •Keep FreshBooks employee records synchronized with UKG hires, terminations, and compensation changes.
• •Map UKG GL account segments and cost center codes to FreshBooks accounts so payroll entries land on valid GL lines.
• •Handle UKG's two-pass employee fetch, OAuth token refresh, and FreshBooks user-delegated OAuth.
• •Poll on a schedule tied to your payroll calendar, with a full audit trail on every journal entry and employee record.

Questions

What employee and payroll data moves from UKG into FreshBooks?

Employee master records, including names, IDs, and compensation details, flow from UKG into FreshBooks so staff records stay current. Payroll GL journal data flows the same direction: after each payroll run, ml-connector reads UKG's payroll GL output (including GL account segments, cost centers, debit/credit amounts) and posts the labor cost journal into FreshBooks' general ledger, allocated to matching GL accounts per cost center.

How does ml-connector handle UKG's two-pass employee fetch and OAuth token expiry?

ml-connector first calls UKG's /personnel/v1/employee-ids endpoint to get internal employee UUIDs, then makes a second call per employee to /personnel/v1/employees/{id} to fetch the full profile. If you use UKG's OAuth 2.0 client credentials (required for webhooks), ml-connector automatically refreshes the bearer token every hour before expiry so payroll reads never fail.

How are cost centers and GL accounts mapped between UKG and FreshBooks?

Cost centers and GL account mappings are configured once per customer and stored encrypted. During each payroll run, ml-connector looks up the matching FreshBooks GL account for each UKG GL segment and cost center combination, ensuring every journal line references an account that exists. If a cost center or GL code is missing, ml-connector flags the record in the audit trail for manual review before posting.