FreshBooks and Deel integration

What moves between them

The primary flow runs from Deel into FreshBooks. Worker invoices, payslips, and contract payroll inputs from Deel are read and mapped into FreshBooks as bills or expenses, linked to vendors matching Deel contractors. Deel employee and contractor data flows into FreshBooks expense categories and client records so payroll allocations land on valid accounts. Payments in FreshBooks can be reconciled back to Deel invoice records. The second flow reads FreshBooks bills and expenses to validate that all open Deel contractor invoices have a matching FreshBooks bill or expense, and alerts on mismatches. Reference data such as contractors and vendors is aligned in both directions so Deel payments land on valid FreshBooks accounts.

How ml-connector handles it

ml-connector stores both credential sets encrypted. For FreshBooks it handles user-delegated OAuth 2.0 authorization, redirecting users to https://auth.freshbooks.com/oauth/authorize and exchanging the code for an access token scoped to their account. For Deel it accepts either an API token or OAuth2 credentials and refreshes the access token when API calls return 401. It listens for Deel webhooks (contract.created, hris.employee.created, hris.employee.updated, hris.employee.terminated) and verifies each with HMAC-SHA256 signature verification using the raw request body. For FreshBooks, since webhooks may be unavailable on older plans, it polls invoices, bills, and payments on a scheduled basis. It maps Deel contractor names to FreshBooks vendor records and creates or updates bills and expenses as needed, matching Deel payroll structure to FreshBooks chart of accounts. Payment reconciliation checks that every open Deel worker invoice has a corresponding FreshBooks bill payment. Rate limit retries use exponential backoff on HTTP 429 responses. Idempotency-Key headers (UUID v4) are sent with Deel POST and PATCH calls to prevent duplicate charges across retries. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A digital agency with 15 contractors across 5 countries uses Deel for global payroll and EOR compliance, and FreshBooks for invoicing and accounting. Before the integration, contractors invoiced Deel, Deel paid them and generated invoices for the agency, and the finance team manually created corresponding vendor bills in FreshBooks each month, then reconciled contractor costs against actual payments. This reconciliation took 6 hours and often surfaced discrepancies between Deel records and FreshBooks bills. With Deel and FreshBooks connected, Deel contractor invoices flow into FreshBooks as bills automatically, mapped to contractor vendor records. Each month, the finance team receives an alert if any Deel invoice is missing from FreshBooks, and payroll costs are ready for reconciliation the day Deel publishes them. The manual bill entry step is gone, and discrepancies are caught immediately.

What you can do

• •Sync Deel worker invoices and payslips into FreshBooks as bills or expenses mapped to contractor vendors.
• •Reconcile Deel payments against FreshBooks bill payments and alert on mismatches.
• •Map Deel contractors and employees to FreshBooks vendors and clients so payroll allocations land on valid accounts.
• •Authenticate FreshBooks with user-delegated OAuth 2.0 and Deel with API token or OAuth2 bearer, handling token refresh and webhook signature verification.
• •Poll FreshBooks and listen to Deel webhooks on a schedule you control, with automatic retries and a full audit trail on every record.

Questions

Which direction does data move between FreshBooks and Deel?

The main flow is Deel into FreshBooks. Worker invoices, payslips, and payroll inputs from Deel flow into FreshBooks as bills or expenses mapped to contractor vendors. Payments in FreshBooks can be reconciled back to Deel invoice records. Reference data such as contractors and vendors is aligned in both directions.

Why does FreshBooks require user-delegated OAuth 2.0 instead of Client Credentials?

FreshBooks does not offer Client Credentials OAuth grant and requires user authorization at https://auth.freshbooks.com/oauth/authorize. ml-connector handles this by redirecting the user to authorize, exchanging the code for an access token scoped to their account, and storing the token encrypted. Users authorize once, and the token is refreshed automatically on subsequent API calls.

How does ml-connector handle Deel webhook real-time delivery and FreshBooks polling?

ml-connector listens for Deel webhooks (contract.created, employee created/updated/terminated) and verifies each signature with HMAC-SHA256. FreshBooks may not support webhooks on all plans, so ml-connector polls invoices, bills, and payments on a scheduled basis. Both transports trigger the same mapping logic, so data flows consistently whether Deel pushes or FreshBooks polling pulls.