FreshBooks and Ramp integration

What moves between them

Bills and expenses flow from FreshBooks into Ramp. When a bill is created or updated in FreshBooks, ml-connector reads the bill vendor and bill details and writes them to Ramp as a bill if the vendor exists or creates the vendor implicitly via the bill POST. Expenses in FreshBooks are mapped to Ramp transactions, with FreshBooks bill vendors normalized to Ramp vendor records and FreshBooks expense categories mapped to Ramp GL accounts. The flow is unidirectional into Ramp; Ramp transaction and bill changes do not feed back into FreshBooks.

How ml-connector handles it

ml-connector manages two different OAuth credential models: it stores FreshBooks user-delegated OAuth tokens encrypted and refreshes them when a call returns 401, while Ramp Client Credentials tokens are refreshed every 10 days before expiry. On webhook receipt from FreshBooks, ml-connector validates the HMAC-SHA256 signature and queues the bill or expense for sync. When syncing a bill, it looks up or creates the vendor in Ramp (since Ramp requires vendors to exist before bill writes), maps the FreshBooks bill vendor name and payment terms, and posts the bill with GL account allocations from the expense category mapping. FreshBooks chart of accounts and Ramp GL accounts are pre-mapped in the flow configuration so every bill line references a valid Ramp account. Webhook signature validation happens on both sides, and every bill and transaction carries a full audit trail for replay if a downstream call fails.

A real-world example

A services firm uses FreshBooks to manage client invoicing, vendor bills, and expenses. The firm's accounting team also uses Ramp for corporate card spending and bill pay across three departments. Before the integration, the accounting team manually logged vendor bills from FreshBooks into Ramp and re-entered expense category allocations to the correct GL accounts, creating duplicate records and reconciliation overhead. With FreshBooks and Ramp connected, each bill created in FreshBooks (entered by the accounts payable clerk) flows directly into Ramp, vendor names stay consistent, and expense categories automatically map to the firm's GL account structure. Month-end reconciliation between vendor ledgers and the GL is now automatic.

What you can do

• •Sync FreshBooks bills and bill vendors into Ramp, creating vendors implicitly where needed.
• •Map FreshBooks expense categories to Ramp GL accounts so accounting dimensions align across both systems.
• •Validate HMAC-SHA256 signatures on FreshBooks webhooks and normalize vendor names and payment terms between systems.
• •Manage user-delegated OAuth refresh on the FreshBooks side and Client Credentials token rotation on the Ramp side.
• •Maintain a full audit trail on every bill and transaction with error replay if a sync fails.

Questions

Which direction does data move between FreshBooks and Ramp?

Bills and expenses flow from FreshBooks into Ramp. When a bill is created or updated in FreshBooks, ml-connector writes it to Ramp as a bill with the vendor name and category-to-GL mapping. Ramp transaction and bill changes do not flow back into FreshBooks.

How does ml-connector handle the two different OAuth models?

FreshBooks uses user-delegated OAuth 2.0, so ml-connector stores the customer's FreshBooks token encrypted and refreshes it when API calls return 401. Ramp uses Client Credentials (server-to-server), so ml-connector refreshes the token proactively every 10 days before expiry to avoid outages during syncs.

What happens if a vendor does not exist in Ramp when a FreshBooks bill arrives?

ml-connector creates the vendor implicitly by POSTing the bill to Ramp with the vendor name and payment terms from FreshBooks. The vendor is created on first reference, so no manual vendor setup is required before bills can sync.