by Paul in API Additions, Development on October 23, 2009
On Wednesday we released some pretty exciting updates to our API and wanted to make sure you were aware of them.
Project Results
If you are an administrator or a staff member who is assigned as a project manager to a project, project.get and project.list methods now return the ids of users who are assigned to that project. Up until now it was impossible to determine if a user was assigned to a project when listing them. Because of this, our OS X time tracker for instance would list all projects that a user could see, not just the ones that they were assigned to. If the user clicked on "Submit" after selecting a project that they weren't assigned to, they would get an error because you can't track time to a project you aren't assigned to. What a headache! See the updated documentation for details.
Custom Emails
You can now send custom email messages with invoice.sendByEmail and estimate.sendByEmail. Just include both a subject and a message element in your request. You can use any of the variables that are available when customizing messages within FreshBooks (i.e. ::invoice link::, ::payment amount::, ::estimate link::). See examples on the invoice and estimate documentation pages.
Delete Payments
We've added a payment.delete method. This will allow you to permanently delete payments. If the payment being deleted was made against an invoice, the status of the invoice will be updated. Check out the documentation.
So there you go, three great new features!
by Paul in API Additions, Integrations, Development on September 30, 2009
As of today, the FreshBooks API is fully functional for Staff members, not just Administrators. Ever since its debut, the API has used a more restrictive set of permissions than the application. This made things a little simpler for us, but it didn't help our users or third-party add-on developers. It meant that certain third-party applications simply weren't as useful for customers who had multiple staff members sharing a single FreshBooks account. We've received many requests from developers to open up permissions in the API so that they more closely follow the permission settings in the application. You have been heard!
Staff now have access to all of the API methods as long as they are given the appropriate permissions from the application settings. This means that if the invoices tab is enabled for staff in the application, they can view and edit invoices from the API for clients who they are assigned to. Likewise, if the estimates tab is enabled, they will have API access to estimates for clients who they are assigned to. Ditto for Recurring Profiles, Payments and Items.
We hope that this change will make existing applications more useful and encourage new kinds of third-party add-ons that were simply not possible before. Having the API be more consistent with the application should help make FreshBooks more useful for everybody.
by Paul in API Additions on August 12, 2009
I'm happy to announce a recent change that we've made to the way *.list methods are handled in the FreshBooks API. Instead of returning a subset of the fields returned by the corresponding *.get method, *.list methods now return all of the data.
What does this mean? Well, for example, previous to this change calling invoice.list would return a list of invoices with the following fields: invoice_id, number, client_id, recurring_id, organization, status, amount, amount_outstanding, and date. If you wanted more information, you would have to iterate over each of the results and call invoice.get for each one. This was cumbersome, and if you had a lot of records to go through, it would take quite a bit of time and unnecessarily eat up your daily API request limit. Now you can get all of that information in one invoice.list request.
<request method="invoice.list" />
<response xmlns="http://www.freshbooks.com/api" status="ok">
<invoices page="1" per_page="25" pages="1" total="2">
<invoice>
<invoice_id>344</invoice_id>
<client_id>3</client_id>
<number>FB00004</number>
<amount>45.6</amount>
<amount_outstanding>0</amount_outstanding>
<status>paid</status>
<date>2009-06-23</date>
<po_number></po_number>
<discount>0</discount>
<notes>Due upon receipt.</notes>
<terms>Payment due in 30 days.</terms>
<url deprecated="true">https://2ndsite.freshbooks.com/inv/1-1-6d30b</url>
<auth_url deprecated="true">https://2ndsite.freshbooks.com/inv/1-1-6d30b-z</auth_url>
<links>
<client_view>https://2ndsite.freshbooks.com/inv/1-1-6d30b</client_view>
<view>https://2ndsite.freshbooks.com/inv/1-1-6d30b-z</view>
<edit>https://2ndsite.freshbooks.com/inv/1-1-6d30b-e</edit>
</links>
<recurring_id>15</recurring_id>
<organization>ABC Corp</organization>
<first_name>John</first_name>
<last_name>Doe</last_name>
<p_street1>123 Fake St.</p_street1>
<p_street2>Unit 555</p_street2>
<p_city>New York</p_city>
<p_state>New York</p_state>
<p_country>United States</p_country>
<p_code>553132</p_code>
<lines>
<line>
<amount>40</amount>
<name>Yard work</name>
<description>Mowed the lawn</description>
<unit_cost>10</unit_cost>
<quantity>4</quantity>
<tax1_name>GST</tax1_name>
<tax2_name>PST</tax2_name>
<tax1_percent>8</tax1_percent>
<tax2_percent>6</tax2_percent>
</line>
</lines>
</invoice>
<invoice>
<invoice_id>345</invoice_id>
<client_id>3</client_id>
<number>FB00005</number>
<amount>570.0</amount>
<amount_outstanding>0</amount_outstanding>
<status>paid</status>
<date>2009-06-24</date>
<po_number></po_number>
<discount>0</discount>
<notes>Due upon receipt.</notes>
<terms>Payment due in 30 days.</terms>
<url deprecated="true">https://2ndsite.freshbooks.com/inv/1-2-6d30b</url>
<auth_url deprecated="true">https://2ndsite.freshbooks.com/inv/1-2-6d30b-z</auth_url>
<links>
<client_view>https://2ndsite.freshbooks.com/inv/1-2-6d30b</client_view>
<view>https://2ndsite.freshbooks.com/inv/1-2-6d30b-z</view>
<edit>https://2ndsite.freshbooks.com/inv/1-2-6d30b-e</edit>
</links>
<recurring_id></recurring_id>
<organization>XYZ Publishing Co</organization>
<first_name>Jane</first_name>
<last_name>Author</last_name>
<p_street1>321 Notreal St.</p_street1>
<p_street2>Suite 380</p_street2>
<p_city>Toronto</p_city>
<p_state>Ontario</p_state>
<p_country>Canada</p_country>
<p_code>M5S2M2</p_code>
<lines>
<line>
<amount>20</amount>
<name>Consulting</name>
<description>Reviewed draft of book</description>
<unit_cost>100</unit_cost>
<quantity>5</quantity>
<tax1_name>GST</tax1_name>
<tax2_name>PST</tax2_name>
<tax1_percent>6</tax1_percent>
<tax2_percent>8</tax2_percent>
</line>
</lines>
</invoice>
</invoices>
</response>
This, along with the update tracking changes we've made should help reduce the amount of effort it takes to get at your FreshBooks data. As always, you can get the whole story at our API documentation pages.
by Owen in API Additions on March 26, 2009
For those of you out there who use FreshBooks as part of a storefront, we have a new feature just for you. FreshBooks invoices created through the API can now have a “return-to-merchant” link. When one of your customers pays an invoice that has a link, they’re given the option to return to your site via whatever URL you specify when you create the invoice. This feature is only available through the API (for now) - try it out and let us know what you think.
Creating an invoice with a return-to-merchant link.
If you already have code that creates new invoices, adding return-to-merchant links when creating an invoice means adding one more element to the <invoice /> element in your request: <return_uri>YOUR URL HERE</return_uri>. The URI from your API request will be used verbatim, so remember to include the http:// or https:// at the beginning.
<?xml version="1.0" encoding="utf-8"?>2 http://invoices.example.com/thanks-for-paying
The <return_uri /> element is supported in invoice.update, and it’s returned from invoice.get requests.
What will your customers see?
The return-to-merchant link is shown to your customers only after they’ve paid their invoices. The payment summary page has an extra link, which will send them to… well, anywhere you want. We’ve also streamlined the payment landing page so that it acts more like the rest of FreshBooks: it now has a clear confirmation message, then the next steps to take, and finally extra information.
Recurring profiles can have return-to-merchant links too.
You can include <return_uri />s in recurring.create and recurring.update, too. When an invoice is created from a recurring profile, some variable substitution takes place, so that the generated link can include a reference back to the invoice.
Let’s say you set your recurring profile’s return_uri to
http://invoices.example.com/invoices/::invoice id::/paid
The invoice ID (invoice_id in the invoice.get API response) of the generated invoices will show up in each invoice’s <recurring_uri> - for example, if the generated invoice ID is 16, then the return-to-merchant link will point to
http://invoices.example.com/invoices/16/paid
This works with ::invoice number:: and the invoice_number of the generated invoices, too.
What about…
There are lots of things we’d like to do with this in the future to make the FreshBooks API support more scenarios. I’m sure some of you have software you’d like to have notified when a customer pays an invoice, for example - that comes up a lot with PayPal’s basic integration, which uses a similar “return to merchant” feature to implement notifications. We’d love to hear other ways of extending the API to better fit how you want to use FreshBooks.
by Sunir in API Additions on February 11, 2009
We made some big updates to recurring billing in today’s release that will make life much easier for many of you. If you’re running a subscription-based billing service on top of FreshBooks, please take note:
Recurring invoices now default to auto-bill
We have changed the default so that recurring invoices automatically bill client credit cards for future invoices, rather than asking the client if they’d like this. We feel this fits better with everyone’s expectations of what should happen. You should expect less confusion around customers needing to enter credit cards multiple times. Note that you will need to purchase enough auto-bills in your system.
Recurring profiles starting today will invoice immediately.
Previously, you could only create recurring profiles starting on a future date. Now, if you create a recurring profile with today’s date, an invoice will be created and sent immediately. The response XML includes the created invoice_id.
This means you can set up a recurring profile immediately at the time of initial purchase, and then immediately redirect your customer to pay the invoice. This should dramatically speed up the time it takes for you get paid, as well as lower attrition rates on payment.
Hopefully these changes will really help your business. Let us know how it goes!
Enjoy!
by Mike G in API Additions on December 17, 2008
Well that makes sense now. Now the little <category_id> on expense operations means something. With the introduction of Expense Categories to the API, you now have the flexibility to manipulate them freely. This includes any taxes that may apply.
The taxation mechanism is flexible to your requirements, but it’s also a relationship that you are required to maintain. <tax1> and <tax2> can be used to track your own tax ID against chosen categories, and then calculated and displayed on the individual expense via <tax1_name>, <tax1_percent> and <tax1_amount>. Three more fields for <tax2_ now appear on expense.get operations as well, and match the preceeding format.
These changes have been reflected in the Expenses API documentation, and a new link for categories has been added. Please feel free to discuss or ask questions in the forum.
by Mike G in API Additions on December 8, 2008
The object URI changes we made a while back appear to be helpful. So much so, we’ve been getting some granular requests that are object specific, and we can see some of the benefits in bringing them to you. But first, and a FreshBooks API first, we’ve added our first deprecation to the API.
I’ve secretly hated the look/feel/sound of our current URI responses in the form of <url> and <auth_url> on invoices, estimates and clients. While they still exist today, you may notice a new property on the <url> and <auth_url> elements, and that is ‘deprecated=“true”’. Make use of them while you can, because in some future update, they will just vanish. API version 3? 2.2? I promise nothing. Consider this a 2 minute warning, of a sort.
The new format consists of a <links> parent which will contain <client_view>, replacing <url>, and <view>, replacing <auth_url>. Your output should look something like this:
https://sample.freshbooks.com/inv/514-24-d4622 https://sample.freshbooks.com/inv/514-24-d4622-z
Links is part of the <invoice>, <estimate> and <client> response when you execute the appropriate .get operation successfully.
Our object specific update of the day is just for invoice.get and fits into the <links> response element. The new link directly takes an authenticated administrator to the target invoice for editing. It should look something like this:
https://sample.freshbooks.com/inv/514-24-d4622-e
As always, comments and further suggestions are welcome and encouraged.
by Mike G in API Additions on December 3, 2008
At long last, I present to you, the people (the Freshies), the Expenses API!
<suitably long pause for applause… keep going I can wait.>
We’re releasing the Expenses API in two phases. This phase contains the core Expenses data. The next phase will include Expense Categories. That will be out Very Soon(tm). (famous last words)
Expenses are also dependent on staff and client associations; so, in the expenses response, we’ve provided a staff_id and a client_id. You can use the Clients API to acquire client details, and the new Staff API to acquire staff details.
We’re also releasing the Staff API in phases. For now, the Staff API only has the staff.get and staff.list commands. That should be enough to make the Expenses API useable.
Please note that staff_id 1 is the administrative account.
by Mike G in API Additions on September 26, 2008
Good day, eh. There’s been a small update to the API that some of you might already have noticed. We added an <auth_url /> element, in the style our existing <url /> tag, for invoices, estimates and clients.
The new <auth_url /> requires an authorized session to work, and is intended to provide an administrative link to your target object. Since we didn’t have a client <url /> element in the client.get response, we’ve included that for consistency.
<auth_url /> will honour an existing administrative session, if you have already logged into the application in some way. It will NOT auto-magically direct you to a secure administrative page without prompting you for user and password if you haven’t already logged in. So don’t get’em mixed. <url /> is for client links, <auth_url /> is for you.
Summary:
Our API documentation has been updated to include this element where necessary.
by Taavi in API Additions on May 15, 2008
We’re happy to announce that we’ve extended the FreshBooks API to allow staff access to time tracking functions! Yes, that includes our OSX Widget, and other time tracker add-ons.
First of all, the admin user has to enable the FreshBooks API. Then any staff member can browse over to his or her Profile page (link at the top, beside Help and Logout). The token and access URL will be displayed at the bottom of the page. The admin user can also find any staff member’s token, by Editing the staff member in question.
Of course, there are always caveats. In order to release this feature as soon as possible for your use-while maintaining the same security you expect from FreshBooks-we’ve only implemented the client, project, task, and time_entry API methods. Staff members trying to access unimplemented features will receive an API error response.
We’ve made a few other updates to the API:
We’ll be updating the API docs today to reflect these changes. So go forth and track time, and let us know what you think. Enjoy!
by Ben in API Additions on April 7, 2008
Howdy folks - a couple of small API changes to announce:
As always, if you have questions or comments, please let us know on the developer forums.
FreshBooks is now eating its own dog food.
On Wednesday we released some pretty exciting updates to our API and wanted to make sure you were aware of them.
Ever since its debut, the API has used a more restrictive set of permissions than the application. This made things a little simpler for us, but it didn't help our users or third-party add-on developers. It meant that certain third-party applications simply weren't as useful for customers who had multiple staff members sharing a single FreshBooks account. We've received many requests from developers to open up permissions in the API so that they more closely follow the permission settings in the application. You have been heard!
On January 4, 2010, we will be disabling SSLv2 and ciphers with keys smaller than 128 bits.
North America
United Kingdom
Ireland
International
1-866-303-6061
0808-101-3408
1-800-949-046
+1 416-481-6946
We love to help our customers! Send us an email through our online support request form any time you need help!
FreshBooks is an online invoicing and timetracking application. Find out more on our website.
