Accessing invoices by id

Hi

I’m trying to access invoices by invoice number.

There’s a sparsely documented reference to this:

Get a single invoice:
GET https://api.freeagent.com/v2/invoices/:id

Frustratingly ‘id’ is not defined in this context, and only seems to be mentioned in the updating / deleting section where even there the definition is really unhelpful:

id	ID of the invoice item to update	Integer

So what is the id exactly? I was assuming it was the invoice number I have attributed in Freeagent but it’s really not clear. If it’s not that, what is it?

I currently get the response:

Resource not found

Help!

Thanks
Bruce

1 Like

The id is the number you see at the end of the URL when you are viewing an invoice on FreeAgent’s website. It is not the invoice reference number.

As far as I know there’s no way to get a single invoice directly by reference number. You have to get a list from the invoices endpoint and iterate over it looking for the one you want.

Yours,
Andrew

1 Like

Hi @weblaunch,

Thanks for your question. Our API follows the REST convention of allowing you to pass an item’s unique ID into the request URL to show a single resource from a collection. This ID can be retrieved from the url attribute of the item, e.g. when listing all invoices:

{
    "invoices": [
        {
            "url": "https://api.sandbox.freeagent.com/v2/invoices/97336",
            "contact": "https://api.sandbox.freeagent.com/v2/contacts/83986",
            "dated_on": "2019-12-12",
            "due_on": "2019-12-17",
            "reference": "004",
            "contact_name": "Test Contact",
            ...
        },
        {
            "url": "https://api.sandbox.freeagent.com/v2/invoices/97337",
            "contact": "https://api.sandbox.freeagent.com/v2/contacts/83986",
            "dated_on": "2019-12-12",
            "due_on": "2019-12-17",
            "reference": "005",
            "contact_name": "Test Contact",
            ...
        }
    ]
}

you can get the individual item’s ID from the url (in the example above 97336 and 97337). Subsequently making a GET request to https://api.sandbox.freeagent.com/v2/invoices/97336 will allow you to view the details of that invoice only.

I hope this helps!

Best wishes,

Ewa

Thanks for the replies, guys.

Wow. I saw a post from 2013 asking for this feature. I can’t comprehend why it hasn’t been implemented. This seems such a heavy-handed, resource-sucking way to achieve what must be a common task, I would have thought!

Also, would be good to get the documentation updated just to make this clear :slight_smile:

2 Likes

And 5 hours later I’m still trying to retrieve one invoice by its reference by loading in ALL the invoices, using the pagination etc etc

"Why Freeagent - WHY?!?! " he cried into the abyss.

2 Likes

I saw a post from 2012 asking for this, in fact: FreeAgent V2 Unsupported Operations - #4 by Chris_Page

It’s quite frustrating, getting on for 8 years later, to still not have any efficient way of retrieving an invoice by reference. For the end users (including customers), the reference will be the most common and natural way they refer to the invoice - so not having an easy way to use that to do a lookup makes development much less straightforward.

It also can’t be good for FreeAgent server load - to have to repeatedly respond to requests for the list of all invoices, just to track down an invoice with a matching reference, is surely a waste of resources at the API end.

FreeAgent team - could this please be added to the feature request list? Something like the following would be ideal:

GET https://api.freeagent.com/v2/invoices?ref=14882220

FreeAgent team: it’s been 9 months without any visible progress on this. Would appreciate a reply. As I explained in my previous message, invoice reference is the most obvious unique search term for an end user, so it makes sense to me for the API to have a facility to lookup by invoice reference.

Hi there,

I’m Steven, one of the support engineers here at FreeAgent :wave: I’m really sorry we’ve taken so long to get back to you!

I can definitely see the case for retrieving invoices by their reference and so I understand your frustration at the lack of support for this. I have now spoken with the relevant product manager and passed on your request for this feature making them aware of this thread, so it will now be under consideration with the engineering team responsible.

Kind Regards,

Steven

1 Like

Thank you, Steven for taking some ownership. Let’s hope common sense prevails and the engineering team take up this most basic requirement which will save us all server load.

1 Like

Thanks Steven, that’s a welcome bit of news. Hoping for further positive developments on this score in due course.

Hello Steven. Any update on this? Hoping that after three months, implementation isn’t too far off. Thanks.

Dear Steven. It’s now been a year without any update (and three years since this thread was started).

Is there any prospect at all of this being implemented, please?

Hi SpinnerWebs,

Thanks for your message; I’m sorry there’s been no news on this for quite some time.

I’ve taken your request to the product managers of the team that is responsible for invoicing (amongst many other areas) to check in on the progress of your previous feature request and ask for an update on how likely we are to implement this. The team is currently very busy working on new features and other obligations, so unfortunately, this request is not something we can pick up right now. However, later in the year, perhaps autumn/winter, the team will be focussing on some improvements to invoicing in particular. The product managers can understand your frustration with the current solution and so have said that they provisionally will look to incorporate your request into the improvement work. As the changes required to implement your request are as yet undefined, they can’t make any promises – although they will do their best!

Our product management processes have to prioritise feature requests that will deliver the most impact and improve the experience for the most users. Thank you for raising this request again. If there are more users who would like to see this implemented, then please reply to this thread so that your voice can be heard and we can prioritise appropriately.

Kind regards,

Steven

1 Like

Thanks for the detailed update, Steven. It’s a shame to hear it’s not yet part of any definite implementation plan, but I’m glad it’s at least on the radar. Will be grateful of further regular updates if possible, please, so that we can schedule our development accordingly (interacting with the FreeAgent API may take a lower priority compared to other development tasks, if it’s going to be as cumbersome as it is).

Would be great to get this feature, seems like a big oversight, unless there’s another smart way of searching for invoices that I haven’t discovered.

1 Like