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
Writable on Create
Field
Data Fields (writable)
Field
estimateid
id
accounting _systemid
ui_status
status
amount
amount
code
discount_total
amount
code
description
current _organization
invoiced
ownerid
estimateid
sentid
created_at
updated
display_status
reply_status
estimate_number
customerid
create_date
discount_value
po_number
template
currency_code
language
terms
notes
address
ext_archive
vis_state
street
street2
city
province
code
country
organization
fname
lname
vat_name
vat_number
lines

Estimate Lines

Estimate lines are used to determine the amount of an estimate

Computed Fields (read only)
Field
lineid
amount
amount
code
updated
Data Fields (writable)
Field
type
qty
unit_cost
amount
code
description
name
taxName1
taxAmount1
taxName2
taxAmount2

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
    }
  }
}