FreshBooks and SFTP / Flat Files integration

What moves between them

Invoices and bills created or updated in FreshBooks trigger webhooks that ml-connector receives and converts to CSV or EDI format, then uploads to the SFTP partner's inbound folder on a schedule you set. Conversely, incoming remittance files (payments) and GL journal files from the SFTP server are polled, parsed according to the mapping, and posted back into FreshBooks as payments and journal entries. Vendor and customer reference data is synchronized bidirectionally to keep the two systems aligned. All transfers include EDI acknowledgments where required, and every record carries an audit trail.

How ml-connector handles it

ml-connector authenticates to FreshBooks using the OAuth 2.0 authorization token you provide and subscribes to invoice, bill, and payment webhook events. When events arrive, ml-connector buffers them and converts the JSON records into the file format and layout specified for your SFTP partner (typically CSV, but X12 or EDIFACT if required). On the outbound schedule you set, ml-connector connects to the SFTP server using SSH key authentication or username and password, uploads the formatted files to the inbound folder, and moves any processed files to the processed folder. For inbound files, ml-connector polls the SFTP inbound folder on schedule, downloads new files, parses them according to the column mapping you provide, and creates payments and journal entries in FreshBooks. If a file fails to parse or a FreshBooks call returns an error, the file is moved to the error folder and logged so you can replay it manually. Host key verification is required for production SFTP connections to prevent man-in-the-middle attacks.

A real-world example

A small business runs FreshBooks for invoicing and accounting and ships products to a mid-market distributor that accepts orders and remittances only via SFTP as CSV files. Before the integration, the accounting team exported invoices from FreshBooks manually once a week, formatted them as CSV, and uploaded them to the distributor's SFTP server. The distributor sent back payment files weekly, and the team had to download, parse, and re-enter each payment into FreshBooks by hand. With FreshBooks and SFTP / Flat Files connected, invoices flow automatically as formatted CSV files, and incoming payment files are parsed and posted into FreshBooks as payment records without manual intervention. The accounting team now spends minutes on what once took hours each week.

What you can do

• •Convert FreshBooks invoices and bills to CSV or EDI format and upload them to your SFTP partner's inbound folder on schedule.
• •Receive payment and remittance files from SFTP, parse them according to your column mapping, and post payments into FreshBooks automatically.
• •Authenticate FreshBooks via OAuth 2.0 and SFTP partners via SSH keys or username and password, with full credential encryption.
• •Handle webhook signature verification on FreshBooks events and keep audit logs of every record transferred, with error files moved to a separate folder for manual replay.
• •Sync vendor and customer reference data bidirectionally so both systems stay aligned and payments post to the correct accounts.

Questions

What file formats does the integration support for SFTP?

The connector supports CSV, X12 EDI (850 purchase orders, 810 invoices, 820 payments, 997 acknowledgments), EDIFACT (ORDERS, INVOIC, REMADV, CONTRL), XML, and fixed-width text files. The format and column layout are configured per trading partner based on the mapping spec you provide.

How often does the integration sync files between FreshBooks and SFTP?

Outbound synchronization (FreshBooks to SFTP) runs on a schedule you set, typically 5 to 60 minutes. Inbound polling (SFTP to FreshBooks) also runs on a schedule you choose. FreshBooks webhook events are received in real-time, but file uploads happen only on the outbound schedule you define.

What happens if an incoming SFTP file fails to parse or a FreshBooks post fails?

ml-connector moves files that fail to parse to the error folder and logs the failure. You can then manually correct the file and re-upload it, or replay the original file from the processed folder. If a FreshBooks API call fails, ml-connector retries with exponential backoff before moving the file to error.