High Level notes on an end client migrating to the breaking change: https://api-discuss.freeagent.com/t/breaking-change-notice-multiple-attachments-for-bank-transaction-explanations/6717

Uncategorized
1

"Since we were impacted by the recent breaking change Bank Transaction Explanation Attachments API Breaking Change, I had my AI agent execute and test a mitigation strategy over the weekend which has worked.

High-Level Migration Flow:

  1. Defensive Routing: Cloned the existing flow and introduced a router to detect payload shapes dynamically. This supports both the new attachments[] and legacy attachment.content_src formats, enabling a gradual rollout with a safe fallback path for auditing or rollback.

  2. Version Opt-In: Applied the new version header (X-Api-Version=2026-09-01) exclusively to the cloned route.

  3. Data Fetch & Fan-Out: Retrieved bank explanations (matching the legacy flow) and collected all attachment URLs, then fanned out to process each URL concurrently.

  4. Time-Sensitive Extraction: Extracted the content_src URLs. Because these are short-lived, signed AWS URLs (observed X-Amz-Expires=30), they are uploaded and persisted immediately to prevent expiry.

  5. Target System Ingestion of attachments: Uploaded the files directly via the AWS download URLs into the target system using a Sidewinder script. (note our target system supports this architecture, check if yours does too (aka; Upload file via URL)

  6. Fan-In & Fault Tolerance: Merged the processes by mapping the target system’s storage tokens back to the original explanation transaction key (mapping N attachments to 1 record). The batch is fault-tolerant; a single attachment failure will not abort the batch, but rather surface as a per-file error.

  7. Final Commit: Wrote the final bank explanation record to the target system once, containing the complete array of attachments."

Notes: FreeAgent says up to 50 attachments are supported , we tested x3 in 1 explanation and noticed that the UI only allows up x10 attachments at the moment. We use FreeAgent Global though.