API Updates: Project Staff, Custom Emails and payment.delete

by Paul Osman 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!

1 comments

Staff API Access: No More Restrictions!

by Paul Osman 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.

4 comments

FreshBooks API List Methods: Now All You Need

by Paul Osman 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.

List Request

<request method="invoice.list" />

Response

<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.

2 comments