Change contact on invoice via api

Hi there,

Over the years, we’ve ended up with 20,000 duplicate contacts in Freeagent (don’t ask!) so we’re now doing a big clean up exercise.

Anyhow, I’d like to use the api to change the contact for Invoice A from Contact X_1 to Contact X_2.
Once Contact X_1 has no invoices associated with it, I can delete it, leaving only Contact X_2.

From what I can tell in the documentation, the api may not support changing an invoice’s contact. Is that right?


What we’ve found with Fabio is, the API can change an Invoice’s contact, but the Invoice must be in a DRAFT state, otherwise the following error is returned:

contact_id is locked and cannot be changed

Ah, thank you. That means we’re going to have to also use the api to remove the bank transaction explanation, make it draft, change the contact, mark as sent and reapply the bank transaction explanation. Ooof!

1 Like

Hi Bruno,

That’s right, once an invoice has been sent then the contact cannot be changed - only when it’s a draft. There isn’t functionality to merge contacts at present, but I’ve added a vote to our feature request for it.

There are common circumstances where you wouldn’t be able to edit old invoices or remove bank transaction explanations either, e.g. where tax returns have been filed for the same period, so it may not be possible to do this in full.

We’d generally suggest that the older duplicate contacts are marked as hidden (status attribute: docs) so they’re not shown in the FreeAgent interface, but I appreciate that this doesn’t solve the issue fully.

Kind regards,

Hi Dominic,
Is it possible to use the api to get the bank_transaction_explanation for a given invoice?
Here’s the scenario: to swap the contact of a paid invoice we need to…

  1. Mark it as draft
  2. To do that we need to delete the bank transaction but make a note of all the details
  3. Now we can make it draft
  4. Now we can change the contact
  5. Then we need to mark it as sent
  6. And recreate the bank transaction explanation using the details stored from step 2.

However, we’re getting stuck on step 2. We can’t seem to use the api to get the bank_transaction_explanation from the invoice url.
We’d like to pass in the invoice ID (paid_invoice) to the bank_transaction_explanation to model and get all the details of the transaction so that we can recreate the transaction in step 6.

We can only search for a bank transaction explanation if we already have its id/url.
It means we’re having to go through every url and check the paid_invoice column, one by one. But that’s never going to work with 60,000+ bank transactions.

Any advice please?

Hi Bruno,

Unfortunately we currently don’t support a way to get the bank_transaction_explanations associated with the invoice directly from the invoice GET endpoint.

However, one way you might be able to do this (provided that the invoice is fully paid) is to use the paid_on attribute in the response to the invoice endpoint. If you know the paid_on date, you could then use it to filter all the bank_transactions_explanations based on their dated_on attribute with a call like {{url}}/v2/bank_transaction_explanations?bank_account={{url}}/v2/bank_accounts/:id&from_date=2024-05-10&to_date=2024-05-10 to narrow it down to the one day (see bank_transaction_explanations GET endpoint documentation). This might make it more feasible to search through the returned transactions, as they are narrowed to the ones raised in a single day.

I’ve also let our product manager know about this and added a feature request for us for us to triage, so that the invoice GET API endpoint also returns the bank_transaction_explanations associated with the invoice.

I hope the proposed approach helps and makes sense. If not, please do get in touch again!

Kind regards,

Thanks for providing that suggestion Claudiu.

The problem, of course, is that I can’t get the paid_on date programmatically. I’d have to manually get that from the front-end, which defeats the purpose as I’ve got 20,000 contacts to merge. So I need a way to do it automatically.

Sounds like the only way is for us to make a local copy of every bank transaction and then use that.

the invoice GET API endpoint also returns the bank_transaction_explanations associated with the invoice

This would indeed be very valuable. Thank you for turning into a feature request.