FreshBooks and ADP integration

What moves between them

The flow runs from ADP into FreshBooks. After each payroll run, ml-connector reads ADP's general ledger documents and posts the labor cost as journal entries into FreshBooks against the matching chart of accounts, and can record employer costs as FreshBooks expenses where that suits the books. Cost centers and departments from ADP validation tables are aligned to FreshBooks accounts so each posting references an account that already exists. The cadence is tied to your payroll calendar, running after each pay period rather than continuously. ADP general ledger documents are output-only, so ml-connector never writes financial entries back into payroll.

How ml-connector handles it

ml-connector stores both credential sets encrypted and presents the ADP client certificate at the TLS layer on every request, re-calling the ADP token endpoint with client credentials when a call returns 401. On the FreshBooks side it runs the user-delegated OAuth flow, refreshes the single rotating refresh token, and reads the identity endpoint to capture the accountId and businessId every accounting path needs. Cost centers and departments from ADP validation tables are mapped to FreshBooks chart of accounts first, so every payroll journal line references an account that already exists. Because FreshBooks webhook delivery is not real time, payroll reads run on a schedule rather than on a push, and ADP general ledger documents and worker data are polled after each pay run. New FreshBooks journal entries are written through the journal entries endpoint, and supplying a stable reference per posting keeps a retry from creating a duplicate. Both APIs return HTTP 429 under throttling, so ml-connector backs off and retries, tracks the ADP certificate expiry so a renewal does not turn into an outage, and keeps a full audit trail so any failed posting can be replayed.

A real-world example

A 40-person creative agency invoices clients in FreshBooks and runs payroll for its staff through ADP Workforce Now. Before the integration, the bookkeeper downloaded the payroll register from ADP every pay period and hand-entered wages, taxes, and employer costs into FreshBooks as journal entries, then reconciled them against the bank at month end. The manual entry was slow and the labor accounts drifted whenever a number was transposed. With FreshBooks and ADP connected, each payroll run's general ledger document posts into FreshBooks automatically, split across the correct accounts, and month-end close starts with the labor accounts already in agreement.

What you can do

• •Post ADP payroll general ledger documents into FreshBooks as journal entries after every pay run.
• •Record ADP employer costs as FreshBooks expenses against the matching chart of accounts where that fits the books.
• •Map ADP cost centers and departments to FreshBooks accounts so each payroll line lands on a valid account.
• •Bridge ADP OAuth2 client credentials with mutual TLS and FreshBooks user-delegated OAuth, refreshing each token type.
• •Poll on a schedule tied to your payroll calendar, with backoff on 429, certificate expiry tracking, and a full audit trail.

Questions

Which direction does data move between FreshBooks and ADP?

The flow is one direction, ADP into FreshBooks. ADP payroll general ledger documents and the related cost data move into FreshBooks as journal entries and expenses. ADP general ledger documents are read-only output artifacts, so ml-connector never writes financial entries back into payroll.

Does ADP's mutual TLS certificate requirement need special setup?

Yes. On top of OAuth2 client credentials, ADP requires a signed client certificate at the TLS layer on every call, and the handshake fails without it. ml-connector stores the certificate encrypted, presents it on each request, and tracks its expiry so a renewal is handled before it can cause an outage.

Why does the integration poll FreshBooks instead of using its webhooks?

FreshBooks does offer outbound webhooks, but their delivery latency is not guaranteed and can range from seconds to several minutes, which is not reliable enough for payroll-driven postings. ml-connector instead reads ADP general ledger documents and worker data on a schedule tied to your pay calendar and posts the matching entries into FreshBooks.