Log In 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:readuser: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": "test@example.com",
"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": "test@example.com",
"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": {
"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"
}
}
}
}
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': "test@example.com",
'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': "test@example.com",
'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
}
}
}