Estimates

Staff have access to the API calls listed below if the Estimates tab is enabled for staff. Staff users can only access estimates that belong to clients they are assigned to.

estimate.create

Create a new estimate and return the corresponding estimate_id.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.create">
  <estimate>
    <client_id>13</client_id>              <!-- Client being invoiced -->
	<!-- Contacts optional -->
	<contacts>
		<contact>
			<contact_id>0</contact_id>
		</contact>
	</contacts>
    <status>draft</status>                 <!-- Ignored -->

    <date>2007-06-23</date>                <!-- If not supplied, defaults to today's date (Optional) -->
    <po_number>2314</po_number>            <!-- Purchase order number (Optional) -->
    <discount>10</discount>                <!-- Percent discount (Optional) -->
    <currency_code>CAD</currency_code>     <!-- Currency code (Optional) -->
    <language>en</language>                <!-- Language, see language.list for codes (Optional) -->
    <notes>Due upon receipt.</notes>       <!-- Notes (Optional) -->
    <terms>Payment due in 30 days.</terms> <!-- Terms (Optional) -->
    <first_name>John</first_name>          <!-- (Optional) -->
    <last_name>Smith</last_name>           <!-- (Optional) -->
    <organization>ABC Corp</organization>  <!-- (Optional) -->
    <p_street1></p_street1>                <!-- (Optional) -->
    <p_street2></p_street2>                <!-- (Optional) -->
    <p_city></p_city>                      <!-- (Optional) -->
    <p_state></p_state>                    <!-- (Optional) -->
    <p_country></p_country>                <!-- (Optional) -->
    <p_code></p_code>                      <!-- (Optional) -->
    <!-- e.g. 'VAT Number' (Optional) -->
    <vat_name></vat_name>
    <!-- If set, shown with vat_name under client address (Optional) -->
    <vat_number></vat_number>

    <lines>                                <!-- Specify one or more line elements (Optional) -->
      <line>
        <name>Yard Work</name>                     <!-- (Optional) -->
        <description>Mowed the lawn.</description> <!-- (Optional) -->
        <unit_cost>10</unit_cost>                  <!-- Default is 0 -->
        <quantity>4</quantity>                     <!-- Default is 0 -->
        <tax1_name>GST</tax1_name>                 <!-- (Optional) -->
        <tax2_name>PST</tax2_name>                 <!-- (Optional) -->
        <tax1_percent>8</tax1_percent>             <!-- (Optional) -->
        <tax2_percent>6</tax2_percent>             <!-- (Optional) -->
        <type>Item</type>                          <!-- (Optional) -->
  <!-- One of 'Item' or 'Time'. If omitted, the line's type defaults to 'Item' -->
      </line>
    </lines>
  </estimate>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <estimate_id>103</estimate_id>
</response>

estimate.update

Update an existing estimate.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.update">
  <estimate>
    <estimate_id>103</estimate_id>
    <status>sent</status>                 <!-- Ignored -->

    <!-- Remaining arguments same as estimate.create -->

  </estimate>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

estimate.get

Retrieve an existing estimate.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.get">
  <estimate_id>21</estimate_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <estimate>
    <estimate_id>00000000001</estimate_id>
    <number>0000001</number>
    <client_id>5</client_id>
	<contacts>
		<contact>
			<contact_id>0</contact_id>
		</contact>
	</contacts>
    <staff_id>1</staff_id>
    <organization>Sample Organization</organization>
    <first_name>John</first_name>
    <last_name>Smith</last_name>
    <p_street1>123 Fake St.</p_street1>
    <p_street2>Apt 123</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>
    <vat_name></vat_name>
    <vat_number></vat_number>
    <po_number>84</po_number>
    <folder>active</folder>
    <status></status>
    <amount>40</amount>
    <currency_code>CAD</currency_code>
    <language>en</language>
    <date>2009-07-21</date>
    <notes>Some notes for the customer to see.</notes>
    <terms>Once accepted, payment must be made in 30 days.</terms>
    <discount>10</discount>
    <url deprecated="true">https://sample.freshbooks.com/view/3R8gdDNVJ8uDpC6X</url>
    <auth_url deprecated="true">https://sample.freshbooks.com/estimates/00000000001</auth_url>
    <links>
      <client_view>https://sample.freshbooks.com/view/3R8gdDNVJ8uDpC6X</client_view>
      <view>https://sample.freshbooks.com/estimates/00000000001</view>
    </links>
    <lines>
      <line>
        <name>Yard Work</name>
        <description>Mowed the Lawn</description>
        <unit_cost>10</unit_cost>
        <quantity>4</quantity>
        <amount>40</amount>
        <tax1_name>GST</tax1_name>
        <tax2_name>PST</tax2_name>
        <tax1_percent>5</tax1_percent>
        <tax2_percent>8</tax2_percent>
        <type>Item</type>
      </line>
    </lines>
  </estimate>
</response>

estimate.delete

Delete an existing estimate.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.delete">
  <estimate_id>103</estimate_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

estimate.list

Returns a list of estimates. You can optionally filter by client_id, folder, and date.

Note: This method uses pagination

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.list">
  <client_id>3</client_id>            <!-- Filter by client (Optional) -->
  <date_from>2007-01-01</date_from>   <!-- Return estimates dated after this arg (Optional) -->
  <date_to>2007-04-01</date_to>       <!-- Return estimates dated before this arg (Optional) -->
  <page>1</page>                      <!-- Page number to return, default is 1 (Optional) -->
  <per_page>10</per_page>             <!-- Number of results per page, default is 25 (Optional) -->
  <folder>active</folder>             <!--One of 'active', 'archived', 'deleted' (Optional) -->
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <estimates page="1" per_page="10" pages="3" total="26">
    <estimate>
      <estimate_id>00000000001</estimate_id>
      <number>0000001</number>
      <client_id>5</client_id>
		<!-- Contacts optional -->
		<contacts>
			<contact>
				<contact_id>0</contact_id>
			</contact>
		</contacts>
      <staff_id>1</staff_id>
      <organization>Sample Organization</organization>
      <first_name>John</first_name>
      <last_name>Smith</last_name>
      <p_street1>123 Fake St.</p_street1>
      <p_street2>Apt 123</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>
      <vat_name></vat_name>
      <vat_number></vat_number>
      <po_number>84</po_number>
      <status></status>
      <folder>active</folder>
      <amount>40</amount>
      <currency_code>CAD</currency_code>
      <language>en</language>
      <date>2009-07-21</date>
      <notes>Some notes for the customer to see.</notes>
      <terms>Once accepted, payment must be made in 30 days.</terms>
      <discount>10</discount>
      <url deprecated="true">https://sample.freshbooks.com/view/3R8gdDNVJ8uDpC6X</url>
      <auth_url deprecated="true">https://sample.freshbooks.com/estimates/00000000001</auth_url>
      <links>
        <client_view>https://sample.freshbooks.com/view/3R8gdDNVJ8uDpC6X</client_view>
        <view>https://sample.freshbooks.com/estimates/00000000001</view>
      </links>
      <lines>
        <line>
          <name>Yard Work</name>
          <description>Mowed the Lawn</description>
          <unit_cost>10</unit_cost>
          <quantity>4</quantity>
          <amount>40</amount>
          <tax1_name>GST</tax1_name>
          <tax2_name>PST</tax2_name>
          <tax1_percent>5</tax1_percent>
          <tax2_percent>8</tax2_percent>
          <type>Item</type>
        </line>
      </lines>
    </estimate>
    <estimate>
    ...
    </estimate>
  </estimates>
</response>

estimate.sendByEmail

Send an estimate to the associated client via e-mail.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.sendByEmail">
  <estimate_id>21</estimate_id>
</request>
Custom Emails

If you would like to send a custom email, include a message element. If a subject element is not included, the default subject line will be used.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.sendByEmail">
  <estimate_id>21</estimate_id>
  <subject>This is a custom subject!</subject>
  <message>You have a new estimate. Get it here: ::estimate link::</message>
</request>

Search