Estimates

Minimum access level: Estimates and Invoices, unless stated otherwise.

Estimate Attributes

Required Attribute Description Kind
url The unique identifier for the estimate URI
status One of the following:

  • Draft
  • Sent
  • Open
  • Approved
  • Rejected
  • Invoiced

String
estimate_type One of the following:

  • Estimate
  • Quote
  • Proposal

String
contact The contact for whom the estimate is created URI
project Project being estimated URI
reference Free-text reference String
dated_on Date of estimate in YYYY-MM-DD format Date
currency Estimate's currency String
notes Additional text String
discount_percent The discount applied across the whole estimate Decimal
client_contact_name This name will override the default contact name on this estimate String
ec_status One of the following:

  • UK/Non-EC
  • EC Goods
  • EC Services
  • EC VAT MOSS

String
place_of_supply Place of supply when ec_status is EC VAT MOSS String
estimate_items Items for this estimate. See Estimate Item Attributes. Array
net_value Total value of the estimate calculated from its estimate items Decimal
created_at Creation of the estimate resource (UTC) Timestamp
updated_at When the estimate resource was last updated (UTC) Timestamp

Estimate Item Attributes

Required Attribute Description Kind
url The unique identifier for the estimate item URI
position Position on the estimate, starting at 1 Integer
item_type One of the following:

  • Hours
  • Days
  • Weeks
  • Months
  • Years

String
quantity Quantity Decimal
price Price Decimal
description Free-text description String
sales_tax_rate One of the standard sales tax rates Decimal
sales_tax_value Total amount of sales tax Decimal
second_sales_tax_rate One of the standaard second sales tax rates Decimal
second_sales_tax_value Total amount of second sales tax Decimal
category Accounting category the estimate item falls under URI
created_at Creation of the estimate item Timestamp
updated_at When the estimate item was last updated Timestamp

List all estimates

GET https://api.freeagent.com/v2/estimates

Input

View Filters

GET https://api.freeagent.com/v2/estimates?view=recent
  • all: (default)
  • recent: Show only recent estimates.
  • draft: Show only estimates marked as draft.
  • non_draft: Show only estimates the not marked as draft.
  • sent: Show only estimates marked as sent.
  • approved: Show only estimates marked as approved.
  • rejected: Show only estimates marked as rejected.
  • invoiced: Show only estimates marked as invoiced.

Date Filters

GET https://api.freeagent.com/v2/estimates?from_date=2012-01-01&to_date=2012-03-21
GET https://api.freeagent.com/v2/estimates?updated_since=2017-05-22T09:00:00.000Z
  • from_date
  • to_date
  • updated_since

Response

Status: 200 OK
{ "estimates": [
  {
    "url":"https://api.freeagent.com/v2/estimates/1",
    "contact":"https://api.freeagent.com/v2/contacts/1",
    "reference":"001",
    "estimate_type":"Estimate",
    "dated_on":"2011-09-15",
    "status":"Draft",
    "notes":"An example of some additional text.",
    "currency":"GBP",
    "net_value":"25.22",
    "sales_tax_value":"5.04266",
    "updated_at":"2011-09-15T10:30:32Z",
    "created_at":"2011-09-15T10:29:51Z"
  }
]}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <estimates type="array">
    <estimate>
      <url>https://api.freeagent.com/v2/estimates/1</url>
      <contact>https://api.freeagent.com/v2/contacts/1</contact>
      <reference>001</reference>
      <estimate-type>Estimate</estimate-type>
      <dated-on type="date">2011-09-15</dated-on>
      <status>Draft</status>
      <notes>An example of some additional text.</notes>
      <currency>GBP</currency>
      <net-value type="decimal">25.22</net-value>
      <sales-tax-value type="decimal">5.04266</sales-tax-value>
      <updated-at type="datetime">2011-09-15T10:30:32Z</updated-at>
      <created-at type="datetime">2011-09-15T10:29:51Z</created-at>
    </estimate>
  </estimates>
</freeagent>
Show as JSON

Get a single estimate

GET https://api.freeagent.com/v2/estimates/:id

Response

Status: 200 OK
{ "estimate":
  {
    "url":"https://api.freeagent.com/v2/estimates/1",
    "contact":"https://api.freeagent.com/v2/contacts/1",
    "reference":"001",
    "estimate_type":"Estimate",
    "dated_on":"2011-09-15",
    "status":"Draft",
    "notes":"An example of some additional text.",
    "currency":"GBP",
    "net_value":"25.22",
    "sales_tax_value":"5.04266",
    "updated_at":"2011-09-15T10:30:32Z",
    "created_at":"2011-09-15T10:29:51Z",
    "estimate_items": [
      {
        "url":"https://api.freeagent.com/v2/estimate_items/1",
        "position":"1",
        "item_type":"Hours",
        "quantity":"1.03333333",
        "price":"12.2",
        "description":"sada",
        "sales_tax_value":"20.0",
        "category":"https://api.freeagent.com/v2/categories/001",
        "updated_at":"2011-09-15T10:30:22Z",
        "created_at":"2011-09-15T10:30:22Z"
      }
    ]
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <estimate>
    <url>https://api.freeagent.com/v2/estimates/1</url>
    <contact>https://api.freeagent.com/v2/contacts/1</contact>
    <reference>001</reference>
    <estimate-type>Estimate</estimate-type>
    <dated-on type="date">2011-09-15</dated-on>
    <status>Draft</status>
    <notes>An example of some additional text.</notes>
    <currency>GBP</currency>
    <net-value type="decimal">25.22</net-value>
    <sales-tax-value type="decimal">5.04266</sales-tax-value>
    <updated-at type="datetime">2011-09-15T10:30:32Z</updated-at>
    <created-at type="datetime">2011-09-15T10:29:51Z</created-at>
    <estimate-items type="array">
      <estimate-item>
        <url>https://api.freeagent.com/v2/estimate_items/1</url>
        <position type="integer">1</position>
        <item-type>Hours</item-type>
        <quantity type="decimal">1.03333333</quantity>
        <price type="decimal">12.2</price>
        <description>sada</description>
        <sales-tax-value type="decimal">20.0</sales-tax-value>
        <category>https://api.freeagent.com/v2/categories/001</category>
        <updated-at type="datetime">2011-09-15T10:30:22Z</updated-at>
        <created-at type="datetime">2011-09-15T10:30:22Z</created-at>
      </estimate-item>
    </estimate-items>
  </estimate>
</freeagent>
Show as JSON

Get a single estimate as PDF

GET https://api.freeagent.com/v2/estimates/:id/pdf

Notes

For compatibility purposes, the API returns a base64-encoded representation of the PDF data inside a JSON or XML payload. After fetching the response, simply look inside the pdf.content node and base64-decode its value to get the PDF.

The encoded data complies with RFC 2045.

Response

{
  "pdf": {
    "content": "... base64 encoded PDF data ..."
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <pdf>
    <content>... base64 encoded PDF data ...</content>
  </pdf>
</freeagent>
Show as JSON
GET https://api.freeagent.com/v2/estimates?contact=https://api.freeagent.com/v2/contacts/2
GET https://api.freeagent.com/v2/estimates?project=https://api.freeagent.com/v2/projects/2
GET https://api.freeagent.com/v2/estimates?invoice=https://api.freeagent.com/v2/invoices/2

Create an estimate

POST https://api.freeagent.com/v2/estimates

Payload should have a root estimate element, containing elements listed under Estimate Attributes.

Response

Status: 201 Created
Location: https://api.freeagent.com/v2/estimates/9
{ "estimate":
  {
    "url":"https://api.freeagent.com/v2/estimates/9",
    "contact":"https://api.freeagent.com/v2/contacts/1",
    "reference":"001",
    "estimate_type":"Estimate",
    "dated_on":"2011-09-15",
    "status":"Draft",
    "notes":"An example of some additional text.",
    "currency":"GBP",
    "net_value":"25.22",
    "sales_tax_value":"5.04266",
    "updated_at":"2011-09-15T10:30:32Z",
    "created_at":"2011-09-15T10:29:51Z",
    "estimate_items": [
      {
        "url":"https://api.freeagent.com/v2/estimate_items/1",
        "position":"1",
        "item_type":"Hours",
        "quantity":"1.03333333",
        "price":"12.2",
        "description":"sada",
        "sales_tax_value":"20.0",
        "category":"https://api.freeagent.com/v2/categories/001",
        "updated_at":"2011-09-15T10:30:22Z",
        "created_at":"2011-09-15T10:30:22Z"
      }
    ]
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <estimate>
    <url>https://api.freeagent.com/v2/estimates/1</url>
    <contact>https://api.freeagent.com/v2/contacts/1</contact>
    <reference>001</reference>
    <estimate-type>Estimate</estimate-type>
    <dated-on type="date">2011-09-15</dated-on>
    <status>Draft</status>
    <notes>An example of some additional text.</notes>
    <currency>GBP</currency>
    <net-value type="decimal">25.22</net-value>
    <sales-tax-value type="decimal">5.04266</sales-tax-value>
    <updated-at type="datetime">2011-09-15T10:30:32Z</updated-at>
    <created-at type="datetime">2011-09-15T10:29:51Z</created-at>
    <estimate-items type="array">
      <estimate-item>
        <url>https://api.freeagent.com/v2/estimate_items/1</url>
        <position type="integer">1</position>
        <item-type>Hours</item-type>
        <quantity type="decimal">1.03333333</quantity>
        <price type="decimal">12.2</price>
        <description>sada</description>
        <sales-tax-value type="decimal">20.0</sales-tax-value>
        <category>https://api.freeagent.com/v2/categories/001</category>
        <updated-at type="datetime">2011-09-15T10:30:22Z</updated-at>
        <created-at type="datetime">2011-09-15T10:30:22Z</created-at>
      </estimate-item>
    </estimate-items>
  </estimate>
</freeagent>
Show as JSON

Update an estimate

To update the status of an estimate you must use the status transitions to mark an estimate as Draft, Sent, Approved or Rejected.

PUT https://api.freeagent.com/v2/estimates/:id

Payload should have a root estimate element, containing elements listed under Estimate Attributes that should be updated.

Response

Status: 200 OK

Create an estimate item

POST https://api.freeagent.com/v2/estimate_items

Payload should have two root elements:

  • estimate, URL of the estimate to which the item should be added
  • estimate_item, containing elements listed under Estimate Item Attributes

Response

Status: 200 OK
Location: https://api.freeagent.com/v2/estimates_items/2
{ "estimate_item":
  {
    "url":"https://api.freeagent.com/v2/estimate_items/2",
    "position":"1",
    "item_type":"Hours",
    "quantity":"1.03333333",
    "price":"12.2",
    "description":"sada",
    "sales_tax_value":"20.0",
    "category":"https://api.freeagent.com/v2/categories/001",
    "updated_at":"2011-09-15T10:30:22Z",
    "created_at":"2011-09-15T10:30:22Z"
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <estimate-item>
    <url>https://api.freeagent.com/v2/estimate_items/2</url>
    <position type="integer">1</position>
    <item-type>Hours</item-type>
    <quantity type="decimal">1.03333333</quantity>
    <price type="decimal">12.2</price>
    <description>sada</description>
    <sales-tax-value type="decimal">20.0</sales-tax-value>
    <category>https://api.freeagent.com/v2/categories/001</category>
    <updated-at type="datetime">2011-09-15T10:30:22Z</updated-at>
    <created-at type="datetime">2011-09-15T10:30:22Z</created-at>
  </estimate-item>
</freeagent>
Show as JSON

Update an estimate item

PUT https://api.freeagent.com/v2/estimate_items/:id

Payload should have a root estimate_item element, containing elements listed under Estimate Item Attributes that should be updated.

Response

Status: 200 OK

Delete an estimate item

DELETE https://api.freeagent.com/v2/estimate_items/:id

Response

Status: 200 OK

Delete an estimate

DELETE https://api.freeagent.com/v2/estimates/:id

Response

Status: 200 OK

Mark estimate as sent

PUT https://api.freeagent.com/v2/estimates/:id/transitions/mark_as_sent

Response

Status: 200 OK

Mark estimate as draft

PUT https://api.freeagent.com/v2/estimates/:id/transitions/mark_as_draft

Response

Status: 200 OK

Mark estimate as approved

PUT https://api.freeagent.com/v2/estimates/:id/transitions/mark_as_approved

Response

Status: 200 OK

Mark estimate as rejected

PUT https://api.freeagent.com/v2/estimates/:id/transitions/mark_as_rejected

Response

Status: 200 OK