Adding attachments to Bank Transaction Explanations via the API

Documentation
1

I would like to “Update” existing Bank Transaction Explanations via the API and add attachments to them.

Unfortunately, although I can work out what the attachment data needs to look like, ie:

“attachment”:
{
“file_name”: “2017-06-08 7.50.pdf”,
“data”: “JVBERi0xLjMKJcT —— (lots and lots more in here) —— IF0gPj4Kc3RhcnR4cmVmCjQwMjE2MwolJUVPRgo=”,
“description”: “(auto upload)”,
“content_type”: “application/x-pdf”
}

If I try and run an update on the bank_transaction_explanation object i get a 400 bad request response.

My current thinking is to take the JSON from the existing “bank_transaction_explanation” object and PUT the whole thing back to the API with the attachment object now in it. That didn’t work. So I then tried just doing a PUT with the transaction ID and the attachment object only (assuming it only wanted the fields that I wanted to update), but that didn’t work either (same response 400 error).

I stumbled across this topic - How to upload attachments for explanations? - #3 by Cberridge - but it’s akin to an old xKCD cartoon - “What did you see Cberridge?!?! What did you see?!”. He seems like he was trying to do the same thing as me, then somehow worked it out but didn’t explain how, what, why.

If someone could give me an example PUT request to update a bank_transaction_explanation which adds an attachment, that would be great - preferably with dummy data. Would be great if the documentation was then also updated with this info for anyone in the future.

2

Does your data contain any line feeds? I seem to recall when I was writing code to do this I had to use Ruby’s strict_encode64, not encode64 (which adds line feeds every 60 encoded characters).

I can’t see anything wrong with your JSON snippet. What does your whole JSON payload look like?

3

Sure, so I’m doing a PUT (not a post) to

https://api.freeagent.com/v2/bank_transaction_explanations/24XXXX153

And the body is:

{
“bank_transaction_explanation”: {
“dated_on”: “2021-02-08”,
“gross_value”: “-7.99”,
“bank_transaction”: “https://api.freeagent.com/v2/bank_transactions/24XXXX153”,
“attachment”: {
“file_name”: “R10.pdf”,
“data”: “JVBERi0xLjQKJdPr6eEKM XXXXX LOADS OF TEXT XXXXX”,
“description”: “R10.pdf”,
“content_type”: “application/x-pdf”
}
}
}

4

As a note, I’ve confirmed that the base64 encoding is correct and that there are no carriage returns anywhere in the payload.

5

Then I don’t know, sorry – it all looks fine to me.

I’m sure someone from FreeAgent will figure it out.

6

One final check: is your access token up to date? They expire after 1 hour.

7

Hi Peter,

Ewa here from the Engineering Team at FreeAgent — thanks for your message on our forum and I’ll do my best to help out.

I believe I managed to isolate your API requests in our application logs – the main thing that strikes me is that I don’t see the parsed details of your request body at all, which may mean that the body is not getting properly included. I can see that the status of the responses you’re getting is 400, what error message is it accompanied by?

Best wishes,

Ewa

8

Hi Ewa,

Thanks for coming back to me, i’d be happy to share with you the full post body, is there a support email address I can send it to?

The response I get is just “400 (Bad Request)” no more than that unfortunately…

Do you have an example of using the Put method to update a bank transaction explanation with an attachment? I can then cross reference.

I literally just tried now so you should be able to see another request at 17:37:47

Peter

9

Hi Ewa,

I’ve just worked it out. I wasn’t sending a “Content-Type” header, which needed to be “application/json” as soon as I did that, it all sprung into life.

I assume that your API is actually throwing my body data away as it doesn’t see a content-type header which is why you’re seeing nothing at your end.

Hope this helps someone in the future!

Cheers

Peter

10

Glad you managed to resolve it, Peter! :tada:

11

Thanks Peter for leaving this here for others to use. I too want to upload a pdf to a bank transaction explanation. I’m a api newbie, using n8n to access the api and can’t get this to work for me.

App name: My FA app
Timestamp: 05/02/2025, 07:57:10

I’m doing a PUT to
https://api.freeagent.com/v2/bank_transaction_explanations/59xxxxxx2

with body:

{
“bank_transaction_explanation”: {
“dated_on”: “2025-02-03”,
“gross_value”: “-0.63”,
“bank_transaction”: “https://api.freeagent.com/v2/bank_transactions/59xxxxx12”,
“attachment”: {
“file_name”: “Invoice-7777E77D-0001.pdf”,
“data”: “JVBERi0xLjQKJ-etc-etc”,
“description”: “RENDER.COM +14158304762 USA Amount: USD -0.78. Conversion rate: 1.238095.//PAYMENT/£0.63”,
“content_type”: “application/x-pdf”
}
}
}

my header:
{
“Authorization”: “Bearer TOKEN”,
“Content-Type”: “application/json”
}

I’m getting error:
404 - “{"errors":{"error":{"message":"Resource not found"}}}”

but when I ask for the api to get the transactions, it shows up in the list.

Any idea where I’m going wrong?

Thanks, Pete