Estimates

Estimates in FreshBooks provides Owners and Clients a way to agree and negotiate on the price and scope of work before it commences

Access Requirements

Access	Requires Authorization
Scopes	`user:estimates:read` `user:estimates:write`

Estimate Statuses

Code	Status	Description
1	Draft	An Estimate that has been created, but not yet sent
2	Sent	An Estimate that has been sent to a Client or marked as sent by the Admin
3	Viewed	An Estimate that has been viewed by a Client
4	Replied	An Estimate that has a comment by the Client. This is a feature of FreshBooks Classic only
5	Accepted	An Estimate that has been accepted by either the Admin or Client
6	Invoiced	An Estimate that has been converted to an invoice, and that invoice has been sent to a Client

UI Statuses

UI status fields give a descriptive name to states which can be used in filters, and apply to many invoices, estimates, and recurring profiles

Value	Description
created	Estimate is created and in no other state
draft	Estimate is saved in draft status
sent	Estimate has been sent
viewed	Estimate has been viewed by recipient
replied	A comment related to the Estimate has been added by the recipient
accepted	Estimate has been accepted
invoiced	An Invoice related to the Estimate has been sent

Includes

Include Name	Description
audit_logs	Show estimate view/send history
comments	Comments made on estimate
contacts	List of client contacts
lines	Estimate lines
owner	Owner info
presentation	Presentation type
project	Projects
invoices	Invoices
system	Estimate-owner’s system

Filters

Filter Type	Name	Field	Description
Equals	estimateid	estimateid	Matches exact estimateid
In	estimateids	estimateid	Matches list of estimateids, one per query argument specified
Like	estimate _number _like	estimate_number	Estimate number containing parameter
Equals	estimate _number	estimate_number	Matches exact estimate number
Like	notes	notes	Notes containing parameter
StatusEq Filter	statusid	special	Matches exact estimate status
StatusIn Filter	statusids	special	Matches list of estimate statuses, one per query argument specified
Equals	currency _code	currency _code	Matches exact currency code
Equals	currency	currency _code	Alternative to currency_code filter
Between	date_min	create_date	Date greater than or equal to parameter, YYYY-MM-DD format
Between	date_max	create_date	Date less than parameter, YYYY-MM-DD format
Between	amount_min	amount	Amount greater than or equal to parameter
Between	amount_max	amount	Amount less than parameter
Like	po_number	po_number	po_number containing parameter
Equals	clientid	clientid	Matches exact clientid
In	clientids	clientids	Matches list of clientids, one per query argument specified
Between	date_min	date	Date date greater than or equal to parameter, YYYY-MM-DD format
Between	date_max	date	Date date less than parameter, YYYY-MM-DD format
ItemName Filter	item_name	name	Item name containing the parameter
ItemDescriptionFilter	item _description	description	Item description containing the parameter

Field Descriptions

underlined fields are required on creation

Computed Fields (read only)
Field	Type	Description
Writable on Create
Field	Type	Description
Data Fields (writable)
Field	Type	Description
estimateid	string	Unique-to-this-system estimate id
id	int	Unique-to-this-system estimate id, duplicate of estimateid
accounting _systemid	string	Unique id for system
ui_status	string	See Estimate UI Status table
status	string	See Estimate Status table
amount	string	Total amount of estimate, to two decimal places
amount	string	Amount paid on estimate, to two decimal places
code	string	Three-letter currency code
discount_total	object	subfields: Amount and code
amount	string	Amount of discount, to two decimal places
code	string	Three-letter currency code
description	string	Description of first line of estimate
current _organization	string	Name of organization being estimated — denormalized from client
invoiced	boolean	Indicator of whether this estimate has been converted to an invoice that was sent
ownerid	int	Id of creator of estimate. 1 if business admin, other if created by e.g. a contractor
estimateid	int	Id of associated estimate, 0 if none
sentid	int	Userid of user who sent the estimate, typically 1 for admin
created_at	datetime	Time the estimate was created, YYYY-MM-DD HH:MM:SS format
updated	datetime	Time estimate last updated at, YYYY-MM-DD HH:MM:SS format
display_status	string	Description of status shown in FreshBooks UI, one of ‘draft’, ‘sent’, or ‘viewed’
reply_status	string	(Deprecated) Description of status shown in Classic FreshBooks’ UI, one of ‘replied’ or ‘resolved’
estimate_number	string	User-specified and visible estimate id
customerid	int	Unique-to-this-system client-id
create_date	date	Date estimate was created, YYYY-MM-DD format
discount_value	string	Decimal-string amount
po_number	string	Post Office box number for address on estimate
template	string	(Internal, deprecated) choice of rendering style
currency_code	string	Three-letter currency code for estimate
language	string	Two-letter language code, e.g. “en”
terms	string	Terms listed on estimate
notes	string	Notes listed on estimate
address	string	First line of address on estimate
ext_archive	int	(deprecated) 0 or 1 indicating archived or not
vis_state	int	0 for active, 1 for deleted
street	string	Street for address on estimate
street2	string	Second line of street for address on estimate
city	string	City for address on estimate
province	string	Province for address on estimate
code	string	Zip code for address on estimate
country	string	Country for address on estimate
organization	string	Name of organization being estimated
fname	string	First name of Client on estimate
lname	string	Last name of client being estimated
vat_name	string	Value Added Tax name if provided
vat_number	string	Value Added Tax number if provided
lines	array	Lines of the estimate

Estimate Lines

Estimate lines are used to determine the amount of an estimate

Computed Fields (read only)
Field	Type	Description
lineid	int	Unique-to-this-estimate line id
amount	object	Amount total of an estimate line, calculated with unit cost, quantity and tax. subfields: amount and code
amount	string	Amount of estimate line item account, to two decimal places
code	string	Three-letter currency code
updated	datetime	Time estimate line last updated at, YYYY-MM-DD HH:MM:SS format
Data Fields (writable)
Field	Type	Description
type	int	Estimate line type, 0 for normal estimate line
qty	int	Quantity of the estimate line unit, multiplied against unit_cost
unit_cost	object	Unit cost of the line item. subfields: amount and code
amount	string	Unit cost amount, to two decimal places
code	string	Three-letter currency code
description	string	Description for the estimate line item
name	string	Name for the estimate line item
taxName1	string	Name for the first tax on the estimate line
taxAmount1	string	First tax amount, in percentage, up to 3 decimal places
taxName2	string	Name for the second tax on the estimate line
taxAmount2	string	Second tax amount, in percentage, up to 3 decimal places

Converting an Estimate to an Invoice

Associating an estimate with an invoice, is done when creating an invoice. The invoice POST body must contain the estimateid of estimate you wish to convert.

Please note, including the estimateid will not automatically copy any estimate attributes such as customerid, lines, etc… to the invoice. The attributes will have to supplied in the invoice POST body.

When an invoice is created, the estimate’ status will only change to ‘accepted’. It will only change to ‘invoiced’ once the invoice is sent.

Get Single Estimate

Request: GET https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<estimateid>

Response:

{
  "response": {
    "result": {
      "estimate": {
        "status": 2,
        "create_date": "2016-09-09",
        "code": "",
        "ownerid": 1,
        "vat_number": "",
        "id": 2201278,
        "vat_name": "",
        "ui_status": "sent",
        "invoiced": false,
        "reply_status": null,
        "country": "United States",
        "lname": "Client",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Test Client",
        "province": "",
        "updated": "2016-09-09 16:04:42",
        "terms": null,
        "description": "",
        "street2": "",
        "estimateid": 2201278,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000003",
        "customerid": 2185379,
        "discount_value": "0",
        "accounting_systemid": "KAG77",
        "organization": "Test Client",
        "language": "en",
        "po_number": null,
        "display_status": "sent",
        "notes": "",
        "amount": {
          "amount": "800.00",
          "code": "USD"
        },
        "street": "",
        "city": "",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Test",
        "created_at": "2016-09-09 14:37:59",
        "accountid": "KAG77"
      }
    }
  }
}

Create Single Estimate

Request: POST https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates

{
  "estimate": {
     "email": "[email protected]",
     "customerid": 1831231,
     "create_date": "2016-04-04"
  }
}

Response:

{
  "response": {
    "result": {
      "estimate": {
        "status": 1,
        "create_date": "2016-04-04",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "vat_name": "",
        "ui_status": "draft",
        "invoiced": false,
        "reply_status": null,
        "country": "Australia",
        "lname": "Gates",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "street2": "",
        "estimateid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000007",
        "customerid": 1831231,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "amount": {
          "amount": "0.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "accountid": "zDmNq"
      }
    }
  }
}

Create Single Estimate With Estimate Lines (and an unbilled expense)

Request: POST https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates

{
  "estimate": {
    "email": "[email protected]",
    "customerid": 338441,
    "create_date": "2016-04-04",
    "lines": [
      {
        "type": 0,
        "description": "",
        "taxName1": "",
        "taxAmount1": 0,
        "name": "Paperwork",
        "qty": 1,
        "taxName2": "",
        "taxAmount2": 0,
        "unit_cost": {
            "amount": "5000.00",
            "code": "USD"
        }
      },
      {
        "type": 1,
        "description": "",
        "expenseid": 1918390,
        "taxName1": "",
        "taxAmount1": 0,
        "name": "TV Ads",
        "qty": 1,
        "taxName2": "",
        "taxAmount2": 0,
        "unit_cost": {
            "amount": "3000.00",
            "code": "USD"
        }
      }
    ]
  }
}

Response:

{
  "response": {
    "result": {
      "estimate": {
        "status": 1,
        "create_date": "2016-04-04",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "vat_name": "",
        "ui_status": "draft",
        "invoiced": false,
        "reply_status": null,
        "country": "Australia",
        "lname": "Gates",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "street2": "",
        "estimateid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000007",
        "customerid": 338441,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "amount": {
          "amount": "8000.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "accountid": "zDmNq"
      }
    }
  }
}

Update Single Estimate

Request: PUT api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<id>

{
  "estimate": {
     "customerid": 1831231,
     "create_date": "2016-04-04"
  }
}

Response:

{
  "response": {
    "result": {
      "estimate": {
        "status": 1,
        "create_date": "2016-04-04",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "vat_name": "",
        "ui_status": "draft",
        "invoiced": false,
        "reply_status": null,
        "country": "Australia",
        "lname": "Gates",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "street2": "",
        "estimateid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000007",
        "customerid": 1831231,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "amount": {
          "amount": "8000.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "accountid": "zDmNq"
      }
    }
  }
}

Delete Single Estimate

Request: PUT api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<id>

{
  "estimate": {
    "vis_state": 1
  }
}

Response:

{
  "response": {}
}

List Estimates

Request: GET api.freshbooks.com/accounting/account/<accountid>/estimates/estimates

Response:

{
  "response": {
    "result": {
      "estimates": [
          {
            // same format as single estimate
          },
          {
            // same format as single estimate
          },
          {
            // same format as single estimate
          }
        }
      ],
      "per_page": 15,
      "total": 2,
      "page": 1,
      "pages": 1
    }
  }
}

Get Single Invoice

Request: GET

https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<estimateid>


url = "https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<estimateid>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
jsonData = res.json()

Response


{
  "response": {
    "result": {
      "estimate": {
        "status": 2,
        "create_date": "2016-09-09",
        "code": "",
        "ownerid": 1,
        "vat_number": "",
        "id": 2201278,
        "vat_name": "",
        "ui_status": "sent",
        "invoiced": false,
        "reply_status": null,
        "country": "United States",
        "lname": "Client",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Test Client",
        "province": "",
        "updated": "2016-09-09 16:04:42",
        "terms": null,
        "description": "",
        "street2": "",
        "estimateid": 2201278,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000003",
        "customerid": 2185379,
        "discount_value": "0",
        "accounting_systemid": "KAG77",
        "organization": "Test Client",
        "language": "en",
        "po_number": null,
        "display_status": "sent",
        "notes": "",
        "amount": {
          "amount": "800.00",
          "code": "USD"
        },
        "street": "",
        "city": "",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Test",
        "created_at": "2016-09-09 14:37:59",
        "accountid": "KAG77"
      }
    }
  }
}

Create Single Estimate

Request: POST

https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates


url = "https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
paylaod = {'estimate': {
    'email': "[email protected]",
    'customerid': 1831231,
    'create_date': "2016-04-04"
  }
}
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response


{
  "response": {
    "result": {
      "estimate": {
        "status": 1,
        "create_date": "2016-04-04",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "vat_name": "",
        "ui_status": "draft",
        "invoiced": false,
        "reply_status": null,
        "country": "Australia",
        "lname": "Gates",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "street2": "",
        "estimateid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000007",
        "customerid": 1831231,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "amount": {
          "amount": "0.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "accountid": "zDmNq"
      }
    }
  }
}

Create Single Estimate With Estimate Lines (and an unbilled expense)

Request: POST

https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates


url = "https://api.freshbooks.com/accounting/account/<accountid>/estimates/estimates"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'estimate': {
    'email': "[email protected]",
    'customerid': 338441,
    'create_date': '2016-04-04',
    'lines': [
    {
      'type': 0,
      'description': "",
      'taxName1': "",
      'taxAmount1': 0,
      'name': 'paperwork',
      'qty': 1,
      'taxName2': '',
      'taxAmount2': 0,
      'unit_cost': {
        'amount': "5000.00",
        'code': 'USD'
      }

    },
    {
      "type": 1,
      "description": "",
      "expenseid": 1918390,
      "taxName1": "",
      "taxAmount1": 0,
      "name": "TV Ads",
      "qty": 1,
      "taxName2": "",
      "taxAmount2": 0,
      "unit_cost": {
          "amount": "3000.00",
          "code": "USD"
        }
      }
    }
  }
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response


{
  "response": {
    "result": {
      "estimate": {
        "status": 1,
        "create_date": "2016-04-04",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "vat_name": "",
        "ui_status": "draft",
        "invoiced": false,
        "reply_status": null,
        "country": "Australia",
        "lname": "Gates",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "street2": "",
        "estimateid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000007",
        "customerid": 338441,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "amount": {
          "amount": "8000.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "accountid": "zDmNq"
      }
    }
  }
}

Update Single Estimate

Request: PUT

api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<id>


url = "api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'estimate': {
    'customerid': 1831231
    'create_date': "2016-04-04"
  }
}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Response


{
  "response": {
    "result": {
      "estimate": {
        "status": 1,
        "create_date": "2016-04-04",
        "code": "2011",
        "ownerid": 1,
        "vat_number": "",
        "id": 2168250,
        "vat_name": "",
        "ui_status": "draft",
        "invoiced": false,
        "reply_status": null,
        "country": "Australia",
        "lname": "Gates",
        "estimateid": 0,
        "ext_archive": 0,
        "template": "clean-grouped",
        "vis_state": 0,
        "current_organization": "Microsoft",
        "province": "NSW",
        "updated": "2016-09-01 16:16:15",
        "terms": "",
        "description": "",
        "street2": "",
        "estimateid": 2168250,
        "discount_total": {
          "amount": "0.00",
          "code": "USD"
        },
        "address": "",
        "estimate_number": "0000007",
        "customerid": 1831231,
        "discount_value": "0",
        "accounting_systemid": "zDmNq",
        "organization": "Microsoft",
        "language": "en",
        "po_number": null,
        "display_status": "draft",
        "notes": "",
        "amount": {
          "amount": "8000.00",
          "code": "USD"
        },
        "street": "12 Pacific Highway",
        "city": "North Sydney",
        "currency_code": "USD",
        "sentid": 1,
        "fname": "Wyatt",
        "created_at": "2016-09-01 16:16:14",
        "accountid": "zDmNq"
      }
    }
  }
}

Delete Single Estimate

Request: PUT

api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<id>


url = "api.freshbooks.com/accounting/account/<accountid>/estimates/estimates/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'estimate': {
     'vis_state': 1
   }
}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Response


{
"response": {}
}

List Estimates

Request: GET

api.freshbooks.com/accounting/account/<accountid>/estimates/estimates


url = "api.freshbooks.com/accounting/account/<accountid>/estimates/estimates"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = request.get(url, data=None, headers=headers)
jsonData = res.json()

Response:


{
  "response": {
    "result": {
      "estimates": [
          {
            // same format as single estimate
          },
          {
            // same format as single estimate
          },
          {
            // same format as single estimate
          }
        }
      ],
      "per_page": 15,
      "total": 2,
      "page": 1,
      "pages": 1
    }
  }
}