× Freshbooks App Logo
FreshBooks
Official App
Free - Google Play
Get it

Estimates

General Info

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

*Requires Authorization*

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
direct_links Direct link to estimate
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
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
Writable on Create
Field Type Description
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'
Data Fields (writable)
Field Type Description
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": {
    "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': "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
    }
  }
}