FreshBooks and Paylocity integration

What moves between them

After each payroll run, ml-connector reads Paylocity pay statements, deductions, and earnings, then posts corresponding bill records or expense entries into FreshBooks, mapped to FreshBooks chart of accounts and vendors. Cost center data from Paylocity is mapped to FreshBooks expense categories or bill line items. The integration polls Paylocity on a payroll cycle schedule rather than relying on Paylocity webhooks alone, since webhook payloads carry identifiers only and require full data fetches. Reference data such as employees and vendors are aligned in both directions.

How ml-connector handles it

ml-connector stores Paylocity client credentials and FreshBooks OAuth tokens encrypted. On the Paylocity side, it uses client credentials OAuth and refreshes the bearer token every 3600 seconds. On the FreshBooks side, it holds the user-delegated OAuth tokens and respects FreshBooks granular scopes; write operations use the expenses and bills scopes. Because Paylocity webhook payloads carry only identifiers, ml-connector polls the Paylocity API for complete pay statement, deduction, and earning records after the Payroll Processed event. FreshBooks has no employee resource and no vendor API on the Paylocity side, so ml-connector maps employee names and cost centers to FreshBooks vendors and chart of accounts. It translates Paylocity deduction types into FreshBooks expense categories and constructs bill line items with the correct account codes. FreshBooks webhook signatures are validated with HMAC-SHA256 before processing. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized staffing agency runs payroll for 200 contractors across three regions in Paylocity and uses FreshBooks for accounting and invoicing. Before the integration, payroll specialists exported pay registers from Paylocity every week and manually entered labor costs into FreshBooks as bills, mapping each regional cost center to the correct GL account. The process took 4 hours per week and created reconciliation delays. With FreshBooks and Paylocity connected, each payroll run's earnings and deductions flow into FreshBooks automatically, allocated to the correct regions and accounts. The manual data entry is gone, and the accounting team can close books faster.

What you can do

• •Read employee earnings and deductions from Paylocity after each payroll run and post them into FreshBooks as bills or expenses.
• •Map Paylocity cost centers and employees to FreshBooks chart of accounts and vendors so labor costs land on the correct GL accounts.
• •Authenticate Paylocity with client credentials OAuth and FreshBooks with user-delegated OAuth, respecting granular scopes on the FreshBooks side.
• •Poll Paylocity on a payroll cycle schedule, and validate FreshBooks webhook signatures before processing any event.
• •Carry a full audit trail on every record and replay failed bill or expense posts if a downstream call fails.

Questions

How does the integration handle Paylocity webhook payloads that carry only identifiers?

Paylocity webhook payloads do not include complete record data, only identifiers. When ml-connector receives a Payroll Processed event, it polls the Paylocity API to fetch the full pay statements, deductions, and earnings for the affected employees, then constructs FreshBooks bills or expense entries from that data.

Can the integration write data back into Paylocity?

No. Paylocity has no vendor, invoice, or AP object, so there is nothing on the Paylocity side to write back. The integration is pull-only on the Paylocity side. FreshBooks expense and bill data is not sent back to Paylocity.

Why does FreshBooks use user-delegated OAuth instead of client credentials?

FreshBooks does not support Client Credentials OAuth grant. Every integration must use user-delegated OAuth, which requires explicit user login and authorization. ml-connector respects FreshBooks granular scopes; write operations request the expenses and bills scopes only, not full account access.