API - Bank Transactions

I am looking at your API documents and am a bit confused about Bank Transactions and Bank Transaction Explanations. Please clarify or confirm the below:

  1. It seems the only way you can create a bank transaction on freeagent is to upload a CSV file with the transactions
  2. The CSV details are very low so you would need to create a bank transaction explanation for each of the bank transaction that you upload to add detail like sales type code and stuff like that.
  3. If I create a bank transaction explanation without the bank transaction already being there, what happens?
  4. I am trying to automatically create a bank transaction on freeagent, when my booking system has been marked as paid for a particular booking. What is the simplest way to do this? I just need to create a bank transaction with adequately detail each time a booking is made on my hotel booking system.


  1. You can also add a bank transaction on your bank account’s page by clicking the More dropdown, then Add Transaction. There is another way which is to use the API.
  2. Yes, you need to create one or more explanations for each transaction you add.
  3. You cannot do that; the system will stop it.
  4. The simplest way is to add a transaction as per step 1 above, and explain it as a payment or sales or whatever makes sense for your needs.

Hope that helps!

Andrew Stewart

https://doubleagent.io | DoubleAgent - automate your FreeAgent account

Hello again,

Normally you would wait for a bank transaction to appear automatically in your bank account, and then explain it. You wouldn’t ordinarily need to add individual transactions to your bank account…

Andrew Stewart

Hi Andrew,

Thanks for your explanations to my queries before. To your statement “You wouldn’t ordinarily need to add individual transactions to your bank account…” am not sure why you would say that. I have one such use case where this is needed already. I use a reservation/booking system to manage hotel bookings and it has a good interface with a calendar for users to book rooms in a guest house. But I use freeagent to handle my accounts and keep track of expenses and invoices and such. So when a booking is marked as paid in my hotel reservation system, I need that to translate to an entry in my bank account as a “money in” through sales. So there is absolutely a use case for it and in this use case I do need to insert a transaction into the bank account. I am writing some interfacing code on AWS lambda to get this working now.

So the method you suggest is as I have understood from the API docs which is to upload a CSV with the transaction and then create a transaction explanation. So in my use case, a booking gets marked as paid and the amount paid then needs to be made into a single line csv and uploaded through freeagent api, and then a transaction explanation be created to explain said transaction correct? Its quite a long winded process.

Alternatively, from your statement earlier, it seems like freeagent expects the transaction itself to be synchronised directly from the bank, which I can understand except:

  1. I have tried to connect my bank to freeagent and it has never worked to sync the bank account. It just doesnt do it at all. Not sure why. Logging on to the bank seems to work fine, but getting the statement across automatically doesnt work. No error message either

  2. Even if it did work, this synchronisation is not immediate as I understand and sometimes can take a day or two for the freeagent bank details to show the transactions that are on the bank account. Which means that when I or my colleague marks the booking as paid on our booking system, the immediate triggering of that event cannot create a freeagent transaction explanation because that transaction isn’t there yet, and so the explanation will be rejected. Is this a correct understanding?

So if (2) is correct, then I would be forced to upload a single line CSV file for transaction followed by a transaction explanation for each booking paid event. Is this correct?

Thank you for your explanation


Hello Zee,

I had similar difficulties myself when I started using Freeagent last year. And mucking around with CSVs definitely isn’t the way to go!

If you add a bank transaction explanation through the API - without a bank transaction already being there - Freeagent makes a bank transaction for you - or at least it looks and behaves very much like a manual bank transaction entry. Even nicer, when (or in your case, if :wink: ) the bank feed catches up it more often than not will match the transaction to the explanation that you entered, provided it is within a day or so of the actual transaction… I do this all the time for short-term cashflow forecasting, so it should work for you too.

Only worked this out after three months loading tiny little spreadsheets!


Hi Paul,

Thanks for your advice and pointers from personal experience. I definitely agree mucking around posting CSV’s just seems retarded and so 80s. I kinda understand why freeagent api would be like that because they want to preserve the integrity of the bank transaction record because I suppose you could screw it up badly if you were doing something silly. Maybe some checks and restrictions need to be in place… I get that but forcing devs to post csv files is so retarded.

I will try to create a transaction explanation and hope it automatically creates the transaction as you have suggested. Andrew (above) seems to think this will result in an error.

Thank you very much for your suggestion and sharing.


Hi Zee,

First, sorry for the slow reply – I had thought that the forum software would tell me when you replied but it didn’t.

Anyway, I was assuming that your FreeAgent account was synchronising itself with your bank account, so that transactions in your bank account would appear automatically in FreeAgent – albeit after a delay of a day or so. If this isn’t working for you, I suggest contacting FreeAgent support and asking them to help get it working.

Paul is right about adding a bank transaction explanation through the API – that doesn’t require an existing bank transaction. I think I did know that but had forgotten – sorry. When you’re using FreeAgent’s web interface, there does of course need to be a transaction to explain.

When it comes to adding bank transactions / explanations through the API, I personally use the explanations endpoint directly instead of trying to craft and upload a CSV. I have pushed over 30k explanations via the endpoint and it works well.

To synchronise paid bookings between your hotel system and FreeAgent, I would suggest (a) getting your bank feed fixed so transactions appear automatically in FreeAgent; (b) using your AWS lambda code to look for the previous day’s booking payments in your hotel system, and then to call FreeAgent’s API to explain each one (because the transaction should have appeared by then).

I would prefer explaining existing transactions to creating explanations for pending transactions and hoping FreeAgent matches them up correctly when the transactions do appear subsequently.


Are there plans to add the ability to create raw transactions without a bank statement? I don’t want to have to create transaction explanations just to create transactions as I don’t yet know the categories. I want to setup a Starling bank webhook that goes through my backend and directly inputs new transactions into my Freeagent account.

Yeah the Bank feeds dont work. They get sync’ed once and then never again. I dont know why. I will ask Freeagent about it, but in any case it doesn’t help my use case because I need to immediately create an explanation when a booking is marked as paid. So I will try to create an explanation and hope that works.

Doesn’t seem like. As Andrew and Paul advises, you could just create an explanation and it will get matched up to the transaction when that becomes available.


You can now create a one or more (unexplained) transactions in JSON through the v2/bank_transactions/statement endpoint.

We accept the statement parameter as an array of transaction objects, each with a date, description and amount.

This update will now allow you to integrate to Starling without having to synthesise CSV files containing your transactions.

Link to the announcement: Improvements to uploading statements

Link to the updated docs: https://dev.freeagent.com/docs/bank_transactions#upload-a-bank-statement