×
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

Estimate Statuses

CodeStatusDescription
1DraftAn Estimate that has been created, but not yet sent
2SentAn Estimate that has been sent to a Client or marked as sent by the Admin
3ViewedAn Estimate that has been viewed by a Client
4RepliedAn Estimate that has a comment by the Client. This is a feature of FreshBooks Classic only
5AcceptedAn Estimate that has been accepted by either the Admin or Client
6InvoicedAn 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

ValueDescription
createdEstimate is created and in no other state
draftEstimate is saved in draft status
sentEstimate has been sent
viewedEstimate has been viewed by recipient
repliedA comment related to the Estimate has been added by the recipient
acceptedEstimate has been accepted
invoicedAn Invoice related to the Estimate has been sent

Includes

Include NameDescription
audit_logsShow estimate view/send history
commentsComments made on estimate
contactsList of client contacts
direct_linksDirect link to estimate
linesEstimate lines
ownerOwner info
presentationPresentation type
projectProjects
invoicesInvoices
systemEstimate-owner's system

Filters

Filter TypeNameFieldDescription
EqualsestimateidestimateidMatches exact estimateid
InestimateidsestimateidMatches list of estimateids, one per query argument specified
Likeestimate _number _likeestimate_numberEstimate number containing parameter
Equalsestimate _numberestimate_numberMatches exact estimate number
LikenotesnotesNotes containing parameter
StatusEq FilterstatusidspecialMatches exact estimate status
StatusIn FilterstatusidsspecialMatches list of estimate statuses, one per query argument specified
Equalscurrency _codecurrency _codeMatches exact currency code
Equalscurrencycurrency _codeAlternative to currency_code filter
Betweendate_mincreate_dateDate greater than or equal to parameter, YYYY-MM-DD format
Betweendate_maxcreate_dateDate less than parameter, YYYY-MM-DD format
Betweenamount_minamountAmount greater than or equal to parameter
Betweenamount_maxamountAmount less than parameter
Likepo_numberpo_numberpo_number containing parameter
EqualsclientidclientidMatches exact clientid
InclientidsclientidsMatches list of clientids, one per query argument specified
Betweendate_mindateDate date greater than or equal to parameter, YYYY-MM-DD format
Betweendate_maxdateDate date less than parameter, YYYY-MM-DD format
ItemName Filteritem_namenameItem name containing the parameter
ItemDescriptionFilteritem _descriptiondescriptionItem description containing the parameter

Field Descriptions

Computed Fields (read only)
FieldTypeDescription
estimateidstringUnique-to-this-system estimate id
idintUnique-to-this-system estimate id, duplicate of estimateid
accounting _systemidstringUnique id for system
ui_statusstringSee Estimate UI Status table
statusstringSee Estimate Status table
amountstringTotal amount of estimate, to two decimal places
amountstringAmount paid on estimate, to two decimal places
codestringThree-letter currency code
discount_totalobjectsubfields: Amount and code
amountstringAmount of discount, to two decimal places
codestringThree-letter currency code
descriptionstringDescription of first line of estimate
current _organizationstringName of organization being estimated -- denormalized from client
invoicedbooleanIndicator of whether this estimate has been converted to an invoice that was sent
Writable on Create
FieldTypeDescription
owneridintId of creator of estimate. 1 if business admin, other if created by e.g. a contractor
estimateidintId of associated estimate, 0 if none
sentidintUserid of user who sent the estimate, typically 1 for admin
created_atdatetimeTime the estimate was created, YYYY-MM-DD HH:MM:SS format
updateddatetimeTime estimate last updated at, YYYY-MM-DD HH:MM:SS format
display_statusstringDescription of status shown in FreshBooks UI, one of 'draft', 'sent', or 'viewed'
reply_statusstring(Deprecated) Description of status shown in Classic FreshBooks' UI, one of 'replied' or 'resolved'
Data Fields (writable)
FieldTypeDescription
estimate_numberstringUser-specified and visible estimate id
customeridintUnique-to-this-system client-id
create_datedateDate estimate was created, YYYY-MM-DD format
discount_valuestringDecimal-string amount
po_numberstringPost Office box number for address on estimate
templatestring(Internal, deprecated) choice of rendering style
currency_codestringThree-letter currency code for estimate
languagestringTwo-letter language code, e.g. "en"
termsstringTerms listed on estimate
notesstringNotes listed on estimate
addressstringFirst line of address on estimate
ext_archiveint(deprecated) 0 or 1 indicating archived or not
vis_stateint0 for active, 1 for deleted
streetstringStreet for address on estimate
street2stringSecond line of street for address on estimate
citystringCity for address on estimate
provincestringProvince for address on estimate
codestringZip code for address on estimate
countrystringCountry for address on estimate
organizationstringName of organization being estimated
fnamestringFirst name of Client on estimate
lnamestringLast name of client being estimated
vat_namestringValue Added Tax name if provided
vat_numberstringValue Added Tax number if provided
linesarrayLines of the estimate

Estimate Lines

Estimate lines are used to determine the amount of an estimate

Computed Fields (read only)
FieldTypeDescription
lineidintUnique-to-this-estimate line id
amountobjectAmount total of an estimate line, calculated with unit cost, quantity and tax. subfields: amount and code
amountstringAmount of estimate line item account, to two decimal places
codestringThree-letter currency code
updateddatetimeTime estimate line last updated at, YYYY-MM-DD HH:MM:SS format
Data Fields (writable)
FieldTypeDescription
typeintEstimate line type, 0 for normal estimate line
qtyintQuantity of the estimate line unit, multiplied against unit_cost
unit_costobjectUnit cost of the line item. subfields: amount and code
amountstringUnit cost amount, to two decimal places
codestringThree-letter currency code
descriptionstringDescription for the estimate line item
namestringName for the estimate line item
taxName1stringName for the first tax on the estimate line
taxAmount1stringFirst tax amount, in percentage, up to 3 decimal places
taxName2stringName for the second tax on the estimate line
taxAmount2stringSecond 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
    }
  }
}