Confused about the FreeAgent API

Hi all,

I’m having issues with the sparseness and lack of practical examples in the
FreeAgent API docs.

Because of the way authorisation works, am I to understand that any API
tasks performed must involve a user logging in and approving access? This
is my first stumbling block.

All I need to do is to generate an invoice at the point of sale and allow
the user to download it. But they won’t have a FreeAgent account (why would
they?) and so would have no account to ‘authorise’. Besides they can’t
authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?

Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc

  • every attribute throws up a new question.

It seems that the API is very powerful, and I’m impressed with what it
appears I can do with it, but without sufficient docs there seems to be a
lot of guesswork involved… I’m still not even sure if what I want to do is
possible, or if I’m completely missing the purpose of the API.

Thanks all,

Nathan

Hi Vipul, I had quite an information rich question, I’m afraid none of that
helps with it. I am aware of the docs, that’s how I know they’re sparse :slight_smile:
Thanks anyway!On 13 May 2014 12:07, vipul Kumar dashing.vipul@gmail.com wrote:

Hi Nathan,

I am also using free agent Api, and its quite intresting
https://dev.freeagent.com/docs/
Try this link for documentation, and
https://github.com/adoy/PHP-OAuth2
use this link for code.

U can get full hint from this url about code
http://outlandish.com/blog/freeagent-api-php-oauth2/

have a good day… :slight_smile:

On Wednesday, 5 March 2014 16:00:17 UTC+5:30, nat…@3degreesagency.comwrote:

Hi all,

I’m having issues with the sparseness and lack of practical examples in
the FreeAgent API docs.

Because of the way authorisation works, am I to understand that any API
tasks performed must involve a user logging in and approving access? This
is my first stumbling block.

All I need to do is to generate an invoice at the point of sale and allow
the user to download it. But they won’t have a FreeAgent account (why would
they?) and so would have no account to ‘authorise’. Besides they can’t
authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?

Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc

  • every attribute throws up a new question.

It seems that the API is very powerful, and I’m impressed with what it
appears I can do with it, but without sufficient docs there seems to be a
lot of guesswork involved… I’m still not even sure if what I want to do is
possible, or if I’m completely missing the purpose of the API.

Thanks all,

Nathan


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_api+unsubscribe@googlegroups.com.
To post to this group, send email to freeagent_api@googlegroups.com.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.

Nathan,

What is the actual workflow here? Who owns the FreeAgent account?

Is it your FreeAgent account (or a client’s for whom you are creating an
application for)? Are you then generating an invoice for an external
customer? Say a customer purchases something from your website, you wish to
generate an invoice you use for internal purposes and then give the PDF
version of that to the client?

As for some prerequisites:

  • Yes you need to authenticate against the API first. Exactly how you do
    this depends on your programming language and library. It basically
    involves hitting one URL to approve an app for the first time, and then
    getting an access token, and then refreshing that token before it runs out
    using another URL (e.g. hit https://api.freeagent.com/v2/approve_app to go
    through approval process, and
    then https://api.freeagent.com/v2/token_endpoint to get access tokens. This
    is detailed @ https://dev.freeagent.com/docs/oauth. But basically the auth
    step should be a one-time process done as an admin task, then your code
    deals with the access tokens and refreshing just before hitting the API to
    create invoices.

  • Yes you need a client. You could for example go and create a client
    ‘Automated Frontend’ manually and then store the URL in a configuration
    file for when you create an invoice. Or create a client before creating an
    invoice, not sure what makes sense for you.

  • Dates are ISO 8601 I believe
    (see http://en.wikipedia.org/wiki/ISO_8601). Should be no problem
    formatting these with whatever language you are using.

  • Money is in pounds (so 1.5 for £1.50). Obviously a little dependant on
    currency.

I think you may have more of a problem getting the PDF though, as I do not
believe there is an API call. It is possible to figure out the URL you can
grab the PDF from, from returned Url of invoice we remove prefix of
(https://api.freeagent.com/v2/invoices/) and replace with web version
(https://{subdomain}.freeagent.com/invoices/{invoiceId}). From there I
believe appending .pdf gets you the PDF. The problem is the code would not
be authenticated to access this URL as it’s not part of the API. Perhaps
FreeAgent devs here could point you at something that would work?

But on a whole I agree that the documentation is not particularly clear,
and at times misses important information such as defaults, formats
required, or even all of the options in a list (such as company type)

We have invoice integration from Timestamp and have worked with them quite
a bit, but the API has been a little trial and error at times :frowning:

Hope some of this helps!

Thanks,
Adam
Red SequenceOn Tuesday, 13 May 2014 12:12:04 UTC+1, Nathan Hornby wrote:

Hi Vipul, I had quite an information rich question, I’m afraid none of
that helps with it. I am aware of the docs, that’s how I know they’re
sparse :slight_smile: Thanks anyway!

On 13 May 2014 12:07, vipul Kumar <dashin...@gmail.com <javascript:>>wrote:

Hi Nathan,

I am also using free agent Api, and its quite intresting
https://dev.freeagent.com/docs/
Try this link for documentation, and
https://github.com/adoy/PHP-OAuth2
use this link for code.

U can get full hint from this url about code
http://outlandish.com/blog/freeagent-api-php-oauth2/

have a good day… :slight_smile:

On Wednesday, 5 March 2014 16:00:17 UTC+5:30, nat…@3degreesagency.comwrote:

Hi all,

I’m having issues with the sparseness and lack of practical examples in
the FreeAgent API docs.

Because of the way authorisation works, am I to understand that any API
tasks performed must involve a user logging in and approving access? This
is my first stumbling block.

All I need to do is to generate an invoice at the point of sale and
allow the user to download it. But they won’t have a FreeAgent account (why
would they?) and so would have no account to ‘authorise’. Besides they
can’t authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?

Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc

  • every attribute throws up a new question.

It seems that the API is very powerful, and I’m impressed with what it
appears I can do with it, but without sufficient docs there seems to be a
lot of guesswork involved… I’m still not even sure if what I want to do is
possible, or if I’m completely missing the purpose of the API.

Thanks all,

Nathan


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com <javascript:>.
To post to this group, send email to freeag...@googlegroups.com<javascript:>
.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.

Hi Nathan,

I am also using free agent Api, and its quite intresting
https://dev.freeagent.com/docs/
Try this link for documentation, and


use this link for code.

U can get full hint from this url about code

have a good day… :-)On Wednesday, 5 March 2014 16:00:17 UTC+5:30, nat...@3degreesagency.com wrote:

Hi all,

I’m having issues with the sparseness and lack of practical examples in
the FreeAgent API docs.

Because of the way authorisation works, am I to understand that any API
tasks performed must involve a user logging in and approving access? This
is my first stumbling block.

All I need to do is to generate an invoice at the point of sale and allow
the user to download it. But they won’t have a FreeAgent account (why would
they?) and so would have no account to ‘authorise’. Besides they can’t
authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?

Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc

  • every attribute throws up a new question.

It seems that the API is very powerful, and I’m impressed with what it
appears I can do with it, but without sufficient docs there seems to be a
lot of guesswork involved… I’m still not even sure if what I want to do is
possible, or if I’m completely missing the purpose of the API.

Thanks all,

Nathan

Funnily enough this all started with Zapier! Unfortunately their only
Freeagent integrations (at the time) were super basic (I think grabbing
contacts etc.), but in the future it would be nice if this was expanded on,
as Zapier is amazing (an dead easy).

It’s a shame actually because the documentation is nicely put together, but
yea, lacking. The API itself seems very feature packaged, would love to
take advantage of it a little more.

Thanks for all the advise anyway, really appreciate the effort. Even if we
don’t need it for that particular project I’d be surprised if we didn’t
make use of these features at some point.

Best of luck with whatever issue you were having, by the way!On 14 May 2014 15:41, Adam Barclay barclay.adam@gmail.com wrote:

Yeah, I’ve only looked on here twice. Come here to post an issue we are
having and happened to see your name pop up!

Thinking about it a little more I think it would probably be pretty simple
actually:

1. Authenticate via. OAuth somehow (would be nice to have just a

simple API key here to be honest for scenarios such as yours). Agree it can
be a bit of a headache, a lot of concepts to know about and infrastructure
to create for what could be just Basic authentication with an API key over
SSL… nevermind

2. On invoice option being selected create a new contact in FreeAgent

with name and email address, plus anything else you could fill in that
makes sense. You would want to try and find an existing contact first

3. Using the contact from step 2 create your invoice. This creates a

‘draft’ invoice (see https://dev.freeagent.com/docs/invoices).

4. Make one more call which sends out the invoice.(POST https://

api.freeagent.com/v2/invoices/:id/send_email). It may work by making a
call to ‘mark as sent’, but it is not totally obvious if that actually
sends out email, or just marks it as it has? The call for that is PUT
https://api.freeagent.com/v2/invoices/:id/transitions/mark_as_sent Again,
some confusion about how these calls exactly work, but should not be too
much trial and error. A good amount of work is really required from
FreeAgent on their docs.

We have done quite a bit with the API, we have data import scenarios so
loading all contacts, projects and tasks and matching them up on our end,
and also invoice creation and status checker. May look at timeslip syncing
from Timestamp to FreeAgent at some point so sure to find some more little
niggles. Overall though a pretty decent API.

On the note of automating a conversion funnel have a look at Zapier. They
integrate with a lot of services, including FreeAgent (
https://zapier.com/zapbook/freeagent/) so could help you automate some
parts of your workflow without custom code being written.

Thanks,
Adam

On Wednesday, 14 May 2014 15:19:34 UTC+1, Nathan Hornby wrote:

Hi Adam, small world!

The workflow is as follows (although admittedly isn’t really a
requirement anymore, so it has become an academic discussion):

  • Potential client selects services on a front-end form and checks-out
  • We ask the client if they wish to pay now via card, or later via
    invoice.
  • Assuming the user chooses the invoice option we then speak to our
    Freeagent account to create a new customer and generate an itemised invoice
    based on their selections.
  • The invoice gets sent to the client (the standard Freeagent method of
    doing this would be fine, but naturally more control is always nice).

It’s basically an automation of our standard conversion funnel (the idea
was to use it on a streamlined service that we’re likely abandoning now).

It seems like what we’re after might be possible, you’ve certainly done
the rounds with their API! We hit a wall quite quickly as we couldn’t see a
way to generate an invoice from scratch.

oAuth always gives me a headache to be honest - we’ve used it a handful
of times and it’s always baffling. I’m sure it’s very important and all
that, but man do I miss simple API feeds - of course in this case I
understand it to be pretty justified :slight_smile:

Cheers,

Nathan

On 14 May 2014 15:10, Adam Barclay barcla...@gmail.com wrote:

Nathan,

What is the actual workflow here? Who owns the FreeAgent account?

Is it your FreeAgent account (or a client’s for whom you are creating an
application for)? Are you then generating an invoice for an external
customer? Say a customer purchases something from your website, you wish to
generate an invoice you use for internal purposes and then give the PDF
version of that to the client?

As for some prerequisites:

  • Yes you need to authenticate against the API first. Exactly how you
    do this depends on your programming language and library. It basically
    involves hitting one URL to approve an app for the first time, and then
    getting an access token, and then refreshing that token before it runs out
    using another URL (e.g. hit https://api.freeagent.com/v2/approve_app to
    go through approval process, and then https://api.freeagent.
    com/v2/token_endpoint to get access tokens. This is detailed @
    https://dev.freeagent.com/docs/oauth. But basically the auth step
    should be a one-time process done as an admin task, then your code deals
    with the access tokens and refreshing just before hitting the API to create
    invoices.

  • Yes you need a client. You could for example go and create a client
    ‘Automated Frontend’ manually and then store the URL in a configuration
    file for when you create an invoice. Or create a client before creating an
    invoice, not sure what makes sense for you.

  • Dates are ISO 8601 I believe (see http://en.wikipedia.org/
    wiki/ISO_8601). Should be no problem formatting these with whatever
    language you are using.

  • Money is in pounds (so 1.5 for £1.50). Obviously a little dependant
    on currency.

I think you may have more of a problem getting the PDF though, as I do
not believe there is an API call. It is possible to figure out the URL you
can grab the PDF from, from returned Url of invoice we remove prefix of (
https://api.freeagent.com/v2/invoices/) and replace with web version
(https://{subdomain}.freeagent.com/invoices/{invoiceId}http://freeagent.com/invoices/{invoiceId}).
From there I believe appending .pdf gets you the PDF. The problem is the
code would not be authenticated to access this URL as it’s not part of the
API. Perhaps FreeAgent devs here could point you at something that would
work?

But on a whole I agree that the documentation is not particularly clear,
and at times misses important information such as defaults, formats
required, or even all of the options in a list (such as company type)

We have invoice integration from Timestamp and have worked with them
quite a bit, but the API has been a little trial and error at times :frowning:

Hope some of this helps!

Thanks,
Adam
Red Sequence

On Tuesday, 13 May 2014 12:12:04 UTC+1, Nathan Hornby wrote:

Hi Vipul, I had quite an information rich question, I’m afraid none of
that helps with it. I am aware of the docs, that’s how I know they’re
sparse :slight_smile: Thanks anyway!

On 13 May 2014 12:07, vipul Kumar dashin...@gmail.com wrote:

Hi Nathan,

I am also using free agent Api, and its quite intresting
https://dev.freeagent.com/docs/
Try this link for documentation, and
https://github.com/adoy/PHP-OAuth2
use this link for code.

U can get full hint from this url about code
http://outlandish.com/blog/freeagent-api-php-oauth2/

have a good day… :slight_smile:

On Wednesday, 5 March 2014 16:00:17 UTC+5:30, nat...@3degreesagency.com wrote:

Hi all,

I’m having issues with the sparseness and lack of practical examples
in the FreeAgent API docs.

Because of the way authorisation works, am I to understand that any
API tasks performed must involve a user logging in and approving access?
This is my first stumbling block.

All I need to do is to generate an invoice at the point of sale and
allow the user to download it. But they won’t have a FreeAgent account (why
would they?) and so would have no account to ‘authorise’. Besides they
can’t authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?

Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc

  • every attribute throws up a new question.

It seems that the API is very powerful, and I’m impressed with what
it appears I can do with it, but without sufficient docs there seems to be
a lot of guesswork involved… I’m still not even sure if what I want to do
is possible, or if I’m completely missing the purpose of the API.

Thanks all,

Nathan


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit https://groups.google.com/d/to
pic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com.
To post to this group, send email to freeag...@googlegroups.com.

Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit https://groups.google.com/d/
topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com.
To post to this group, send email to freeag...@googlegroups.com.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_api+unsubscribe@googlegroups.com.
To post to this group, send email to freeagent_api@googlegroups.com.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.

Yeah, I’ve only looked on here twice. Come here to post an issue we are
having and happened to see your name pop up!

Thinking about it a little more I think it would probably be pretty simple
actually:

1. Authenticate via. OAuth somehow (would be nice to have just a simple 

API key here to be honest for scenarios such as yours). Agree it can be a
bit of a headache, a lot of concepts to know about and infrastructure to
create for what could be just Basic authentication with an API key over
SSL… nevermind

2. On invoice option being selected create a new contact in FreeAgent 

with name and email address, plus anything else you could fill in that
makes sense. You would want to try and find an existing contact first

3. Using the contact from step 2 create your invoice. This creates a 

‘draft’ invoice (see https://dev.freeagent.com/docs/invoices).

4. Make one more call which sends out the invoice.(POST https:

//api.freeagent.com/v2/invoices/:id/send_email). It may work by making a
call to ‘mark as sent’, but it is not totally obvious if that actually
sends out email, or just marks it as it has? The call for that is PUT https://api.freeagent.com/v2/invoices/:id/transitions/mark_as_sent
Again, some confusion about how these calls exactly work, but should not be
too much trial and error. A good amount of work is really required from
FreeAgent on their docs.

We have done quite a bit with the API, we have data import scenarios so
loading all contacts, projects and tasks and matching them up on our end,
and also invoice creation and status checker. May look at timeslip syncing
from Timestamp to FreeAgent at some point so sure to find some more little
niggles. Overall though a pretty decent API.

On the note of automating a conversion funnel have a look at Zapier. They
integrate with a lot of services, including FreeAgent
(https://zapier.com/zapbook/freeagent/) so could help you automate some
parts of your workflow without custom code being written.

Thanks,
AdamOn Wednesday, 14 May 2014 15:19:34 UTC+1, Nathan Hornby wrote:

Hi Adam, small world!

The workflow is as follows (although admittedly isn’t really a requirement
anymore, so it has become an academic discussion):

  • Potential client selects services on a front-end form and checks-out
  • We ask the client if they wish to pay now via card, or later via invoice.
  • Assuming the user chooses the invoice option we then speak to our
    Freeagent account to create a new customer and generate an itemised invoice
    based on their selections.
  • The invoice gets sent to the client (the standard Freeagent method of
    doing this would be fine, but naturally more control is always nice).

It’s basically an automation of our standard conversion funnel (the idea
was to use it on a streamlined service that we’re likely abandoning now).

It seems like what we’re after might be possible, you’ve certainly done
the rounds with their API! We hit a wall quite quickly as we couldn’t see a
way to generate an invoice from scratch.

oAuth always gives me a headache to be honest - we’ve used it a handful of
times and it’s always baffling. I’m sure it’s very important and all that,
but man do I miss simple API feeds - of course in this case I understand it
to be pretty justified :slight_smile:

Cheers,

Nathan

On 14 May 2014 15:10, Adam Barclay <barcla...@gmail.com <javascript:>>wrote:

Nathan,

What is the actual workflow here? Who owns the FreeAgent account?

Is it your FreeAgent account (or a client’s for whom you are creating an
application for)? Are you then generating an invoice for an external
customer? Say a customer purchases something from your website, you wish to
generate an invoice you use for internal purposes and then give the PDF
version of that to the client?

As for some prerequisites:

  • Yes you need to authenticate against the API first. Exactly how you
    do this depends on your programming language and library. It basically
    involves hitting one URL to approve an app for the first time, and then
    getting an access token, and then refreshing that token before it runs out
    using another URL (e.g. hit https://api.freeagent.com/v2/approve_app to
    go through approval process, and then
    https://api.freeagent.com/v2/token_endpoint to get access tokens. This
    is detailed @ https://dev.freeagent.com/docs/oauth. But basically the
    auth step should be a one-time process done as an admin task, then your
    code deals with the access tokens and refreshing just before hitting the
    API to create invoices.

  • Yes you need a client. You could for example go and create a client
    ‘Automated Frontend’ manually and then store the URL in a configuration
    file for when you create an invoice. Or create a client before creating an
    invoice, not sure what makes sense for you.

  • Dates are ISO 8601 I believe (see
    http://en.wikipedia.org/wiki/ISO_8601). Should be no problem formatting
    these with whatever language you are using.

  • Money is in pounds (so 1.5 for £1.50). Obviously a little dependant on
    currency.

I think you may have more of a problem getting the PDF though, as I do
not believe there is an API call. It is possible to figure out the URL you
can grab the PDF from, from returned Url of invoice we remove prefix of (
https://api.freeagent.com/v2/invoices/) and replace with web version
(https://{subdomain}.freeagent.com/invoices/{invoiceId}http://freeagent.com/invoices/{invoiceId}).
From there I believe appending .pdf gets you the PDF. The problem is the
code would not be authenticated to access this URL as it’s not part of the
API. Perhaps FreeAgent devs here could point you at something that would
work?

But on a whole I agree that the documentation is not particularly clear,
and at times misses important information such as defaults, formats
required, or even all of the options in a list (such as company type)

We have invoice integration from Timestamp and have worked with them
quite a bit, but the API has been a little trial and error at times :frowning:

Hope some of this helps!

Thanks,
Adam
Red Sequence

On Tuesday, 13 May 2014 12:12:04 UTC+1, Nathan Hornby wrote:

Hi Vipul, I had quite an information rich question, I’m afraid none of
that helps with it. I am aware of the docs, that’s how I know they’re
sparse :slight_smile: Thanks anyway!

On 13 May 2014 12:07, vipul Kumar dashin...@gmail.com wrote:

Hi Nathan,

I am also using free agent Api, and its quite intresting
https://dev.freeagent.com/docs/
Try this link for documentation, and
https://github.com/adoy/PHP-OAuth2
use this link for code.

U can get full hint from this url about code
http://outlandish.com/blog/freeagent-api-php-oauth2/

have a good day… :slight_smile:

On Wednesday, 5 March 2014 16:00:17 UTC+5:30, nat…@3degreesagency.comwrote:

Hi all,

I’m having issues with the sparseness and lack of practical examples
in the FreeAgent API docs.

Because of the way authorisation works, am I to understand that any
API tasks performed must involve a user logging in and approving access?
This is my first stumbling block.

All I need to do is to generate an invoice at the point of sale and
allow the user to download it. But they won’t have a FreeAgent account (why
would they?) and so would have no account to ‘authorise’. Besides they
can’t authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?

Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc

  • every attribute throws up a new question.

It seems that the API is very powerful, and I’m impressed with what it
appears I can do with it, but without sufficient docs there seems to be a
lot of guesswork involved… I’m still not even sure if what I want to do is
possible, or if I’m completely missing the purpose of the API.

Thanks all,

Nathan


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit https://groups.google.com/d/
topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com.
To post to this group, send email to freeag...@googlegroups.com.

Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com <javascript:>.
To post to this group, send email to freeag...@googlegroups.com<javascript:>
.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.

Hi Adam, small world!

The workflow is as follows (although admittedly isn’t really a requirement
anymore, so it has become an academic discussion):

  • Potential client selects services on a front-end form and checks-out
  • We ask the client if they wish to pay now via card, or later via invoice.
  • Assuming the user chooses the invoice option we then speak to our
    Freeagent account to create a new customer and generate an itemised invoice
    based on their selections.
  • The invoice gets sent to the client (the standard Freeagent method of
    doing this would be fine, but naturally more control is always nice).

It’s basically an automation of our standard conversion funnel (the idea
was to use it on a streamlined service that we’re likely abandoning now).

It seems like what we’re after might be possible, you’ve certainly done the
rounds with their API! We hit a wall quite quickly as we couldn’t see a way
to generate an invoice from scratch.

oAuth always gives me a headache to be honest - we’ve used it a handful of
times and it’s always baffling. I’m sure it’s very important and all that,
but man do I miss simple API feeds - of course in this case I understand it
to be pretty justified :slight_smile:

Cheers,

NathanOn 14 May 2014 15:10, Adam Barclay barclay.adam@gmail.com wrote:

Nathan,

What is the actual workflow here? Who owns the FreeAgent account?

Is it your FreeAgent account (or a client’s for whom you are creating an
application for)? Are you then generating an invoice for an external
customer? Say a customer purchases something from your website, you wish to
generate an invoice you use for internal purposes and then give the PDF
version of that to the client?

As for some prerequisites:

  • Yes you need to authenticate against the API first. Exactly how you
    do this depends on your programming language and library. It basically
    involves hitting one URL to approve an app for the first time, and then
    getting an access token, and then refreshing that token before it runs out
    using another URL (e.g. hit https://api.freeagent.com/v2/approve_app to
    go through approval process, and then
    https://api.freeagent.com/v2/token_endpoint to get access tokens. This is
    detailed @ https://dev.freeagent.com/docs/oauth. But basically the auth
    step should be a one-time process done as an admin task, then your code
    deals with the access tokens and refreshing just before hitting the API to
    create invoices.

  • Yes you need a client. You could for example go and create a client
    ‘Automated Frontend’ manually and then store the URL in a configuration
    file for when you create an invoice. Or create a client before creating an
    invoice, not sure what makes sense for you.

  • Dates are ISO 8601 I believe (see http://en.wikipedia.org/wiki/ISO_8601).
    Should be no problem formatting these with whatever language you are using.

  • Money is in pounds (so 1.5 for £1.50). Obviously a little dependant on
    currency.

I think you may have more of a problem getting the PDF though, as I do not
believe there is an API call. It is possible to figure out the URL you can
grab the PDF from, from returned Url of invoice we remove prefix of (
https://api.freeagent.com/v2/invoices/) and replace with web version
(https://{subdomain}.freeagent.com/invoices/{invoiceId}http://freeagent.com/invoices/{invoiceId}).
From there I believe appending .pdf gets you the PDF. The problem is the
code would not be authenticated to access this URL as it’s not part of the
API. Perhaps FreeAgent devs here could point you at something that would
work?

But on a whole I agree that the documentation is not particularly clear,
and at times misses important information such as defaults, formats
required, or even all of the options in a list (such as company type)

We have invoice integration from Timestamp and have worked with them quite
a bit, but the API has been a little trial and error at times :frowning:

Hope some of this helps!

Thanks,
Adam
Red Sequence

On Tuesday, 13 May 2014 12:12:04 UTC+1, Nathan Hornby wrote:

Hi Vipul, I had quite an information rich question, I’m afraid none of
that helps with it. I am aware of the docs, that’s how I know they’re
sparse :slight_smile: Thanks anyway!

On 13 May 2014 12:07, vipul Kumar dashin...@gmail.com wrote:

Hi Nathan,

I am also using free agent Api, and its quite intresting
https://dev.freeagent.com/docs/
Try this link for documentation, and
https://github.com/adoy/PHP-OAuth2
use this link for code.

U can get full hint from this url about code
http://outlandish.com/blog/freeagent-api-php-oauth2/

have a good day… :slight_smile:

On Wednesday, 5 March 2014 16:00:17 UTC+5:30, nat…@3degreesagency.comwrote:

Hi all,

I’m having issues with the sparseness and lack of practical examples in
the FreeAgent API docs.

Because of the way authorisation works, am I to understand that any API
tasks performed must involve a user logging in and approving access? This
is my first stumbling block.

All I need to do is to generate an invoice at the point of sale and
allow the user to download it. But they won’t have a FreeAgent account (why
would they?) and so would have no account to ‘authorise’. Besides they
can’t authorise my websites ability to access my freeAgent account. So I’m
struggling to understand the purpose of the authorisation step and how it
fits into the workflow. This metaphore makes sense for, say, twitter,
because it’s an API focussed around allowing users to ‘connect’ their
accounts with an app, but this is an entirely different scenario. Anyone
able to explain this side of it to me? Maybe what I’m trying to do isn’t
possible because of the way authorisation works?

Secondly are there any practical examples of how to utilise the API
anywhere? As I say I just need to generate an invoice for a customer at the
point of sale - attempting to automate a part of the process. But it seems
that after a quick test API call in the Google sandbox that this has
prerequisites, such as creating a Client to assign the invoice to etc. Also
attribute formats, defaults etc. All very important info that I don’t seem
to be able to find anywhere? For example what format dates are accepted in,
how financials should be treated (pennies or pounds, i.e. 100 vs 1.00) etc

  • every attribute throws up a new question.

It seems that the API is very powerful, and I’m impressed with what it
appears I can do with it, but without sufficient docs there seems to be a
lot of guesswork involved… I’m still not even sure if what I want to do is
possible, or if I’m completely missing the purpose of the API.

Thanks all,

Nathan


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit https://groups.google.com/d/
topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_ap...@googlegroups.com.
To post to this group, send email to freeag...@googlegroups.com.

Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.


You received this message because you are subscribed to a topic in the
Google Groups “FreeAgent API” group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/freeagent_api/uCGtjmVHBCk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
freeagent_api+unsubscribe@googlegroups.com.
To post to this group, send email to freeagent_api@googlegroups.com.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.