FreshBooks

App · 27 actions

Invoicing and accounting for small businesses. Manage clients, create, send and track invoices and estimates, record payments and expenses, and log time on projects.

Actions

ActionWhat it does
Create clientAdd a client: a company or person you bill.
Create estimateCreate a draft estimate (a quote) for a client, with one line or several.
Create expenseRecord money your business spent, optionally to bill on to a client or project.
Create invoiceCreate a draft invoice for a client, with one line or several.
Create projectCreate a project to track time and expenses against, billed by the hour or at a fixed price.
Delete clientDelete a client.
Delete estimateDelete an estimate.
Delete expenseDelete an expense.
Delete invoiceDelete an invoice.
Delete paymentDelete a payment recorded by mistake.
Delete projectDelete a project for good.
Delete time entryDelete logged time for good.
Find clientFind a client by email address, or by part of their name or company.
Get clientGet a client's details by ID.
Get invoiceGet an invoice with its lines, totals and status.
List clientsList clients, optionally only those whose name matches.
List expensesList expenses, optionally by category, client, project or date.
List invoicesList invoices, optionally by client, status or date, or only those overdue by a number of days.
List paymentsList payments received, optionally by invoice, client or date.
List projectsList projects, open, completed or both.
List time entriesList logged time, optionally by client or when it started.
Log timeLog time you worked, as yourself, optionally on a project or for a client.
Mark invoice as sentMark a draft invoice as sent without emailing it, for one you deliver yourself.
Record paymentRecord a payment you received against an invoice.
Send invoiceEmail an invoice from FreshBooks, with a link to view and pay it.
Update clientChange a client's details.
Update invoiceChange an invoice's dates, number, reference, discount, notes, terms or lines.

Create client

Add a client: a company or person you bill. Give at least a company, a name or an email address.

Inputs

First namefirst_nametext
The contact's first name.
Last namelast_nametext
The contact's last name.
Companyorganizationtext
The client's company or organization name.
Emailemailtext
Where invoices and estimates are sent.
Phonephonetext
The business phone number.
Mobile phonemobile_phonetext
The mobile phone number.
Currencycurrencytext
The currency the client is billed in.
Streetstreettext
Billing address: street.
Street line 2street2text
Billing address: second line.
Citycitytext
Billing address: city.
State or provinceprovincetext
Billing address: state or province.
Postal codepostal_codetext
Billing address: ZIP or postal code.
Countrycountrytext
Billing address: country, such as United States.
Notesnotestext
Your own notes about the client. Clients don't see them.

Outputs

A client

bus_phonetext
Business phone
currency_codetext
The currency the client is billed in
emailtext
Email address
fnametext
First name
idnumber
The client's ID
languagetext
Language code for what they are sent, such as en
lnametext
Last name
mob_phonetext
Mobile phone
notetext
Your notes about the client
organizationtext
Company name
p_citytext
Billing city
p_codetext
Billing postal code
p_countrytext
Billing country
p_provincetext
Billing state or province
p_streettext
Billing street
p_street2text
Billing street, second line
signup_datetext
When the client was added (UTC)
updatedtext
When the client was last changed
useridnumber
The client's ID again, as older endpoints name it
vat_nametext
Tax number label, such as VAT
vat_numbertext
Tax number
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "bus_phone": "",
  "currency_code": "USD",
  "email": "email1@freshbooks.com",
  "fname": "first1",
  "id": 238951,
  "language": "en",
  "lname": "last1",
  "mob_phone": "",
  "note": null,
  "organization": "company1",
  "p_city": "Toronto",
  "p_code": "M6P 3T1",
  "p_country": "Canada",
  "p_province": "Ontario",
  "p_street": "1655 Dupont St. W.",
  "p_street2": "",
  "signup_date": "2022-01-05 12:17:11",
  "updated": "2022-01-05 07:17:12",
  "userid": 238951,
  "vat_name": null,
  "vat_number": "",
  "vis_state": 0
}

Create estimate

Create a draft estimate (a quote) for a client, with one line or several.

Inputs

Clientclient_idtextRequired
The client. Pick one, or give its ID from an earlier step.
Estimate dateestimate_datedate
The date on the estimate. Leave empty for today.
Currencycurrencytext
Leave empty for the client's own currency.
Item or serviceitemtext
Pick a saved item to fill in its name, description, price and taxes, or type what the line is for.
Quantityquantitynumber
How many. Leave empty for 1.At least 0.
Unit costunit_costnumber
The price of one. Leave empty to use the saved item's price.At least 0.
Line descriptionline_descriptiontext
More detail shown on the line.
Taxtaxtext
A tax to add to the line. Leave empty for the item's own taxes.
Line itemslineslist
For several lines, a list such as [{"name": "Design", "quantity": 2, "unit_cost": 150, "tax_name": "GST", "tax_percent": 5}]. Each line takes name, description, quantity, unit_cost, tax_name, tax_percent, second_tax_name and second_tax_percent. Use it instead of the single line's fields.
Estimate numberestimate_numbertext
Leave empty for FreshBooks' next number.
Referencepo_numbertext
Your reference, such as the client's purchase order number.
Discount (%)discount_percentnumber
A discount on the whole total, in percent.From 0 to 100.
Notesnotestext
Notes printed for the client, such as thanks or bank details.
Termstermstext
Terms printed for the client, such as when to pay.

Outputs

An estimate

amountobject
The total
create_datetext
The estimate date (YYYY-MM-DD)
created_attext
When it was created
currency_codetext
The estimate's currency
current_organizationtext
The client's name as it is now
customeridnumber
The client's ID
discount_valuetext
Discount, in percent
display_statustext
Status as FreshBooks shows it
estimate_numbertext
The estimate number shown on it
idnumber
The estimate's ID
invoicedtrue/false
Whether it has been turned into an invoice
lineslist
The estimate's lines
notestext
Notes printed on the estimate
organizationtext
The client's name as printed on the estimate
po_numbertext
Your reference, such as a PO number
termstext
Terms printed on the estimate
ui_statustext
Status: draft, sent, viewed, accepted, invoiced
updatedtext
When it was last changed
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "amount": {
    "amount": "5000.00",
    "code": "USD"
  },
  "create_date": "2016-04-04",
  "created_at": "2016-09-01 16:16:14",
  "currency_code": "USD",
  "current_organization": "Microsoft",
  "customerid": 338441,
  "discount_value": "0",
  "display_status": "draft",
  "estimate_number": "0000007",
  "id": 2168250,
  "invoiced": false,
  "lines": [
    {
      "amount": {
        "amount": "5000.00",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Paperwork",
      "qty": "1",
      "taxAmount1": "0",
      "taxAmount2": "0",
      "taxName1": "",
      "taxName2": "",
      "unit_cost": {
        "amount": "5000.00",
        "code": "USD"
      }
    }
  ],
  "notes": "",
  "organization": "Microsoft",
  "po_number": null,
  "terms": "",
  "ui_status": "draft",
  "updated": "2016-09-01 16:16:15",
  "vis_state": 0
}

Create expense

Record money your business spent, optionally to bill on to a client or project.

Inputs

CategorycategorytextRequired
The expense category. Pick one, or type its name.
AmountamountnumberRequired
How much was spent.At least 0.
Dateexpense_datedate
When it was spent. Leave empty for today.
Vendorvendortext
Who was paid, such as a shop or supplier.
Notesnotestext
What it was for.
Currencycurrencytext
Leave empty for your business's currency.
Clientclient_idtext
A client to bill the expense to. Leave empty for none.
Projectproject_idtext
The project it belongs to. Leave empty for none.

Outputs

An expense

amountobject
How much was spent
categoryidnumber
The expense category's ID
clientidnumber
The client to bill it to; 0 for none
datetext
When it was spent (YYYY-MM-DD)
expenseidnumber
The expense's ID again
has_receipttrue/false
Whether a receipt is attached
idnumber
The expense's ID
invoiceidnumber
The invoice it was billed on
notestext
Your notes
projectidnumber
The project it belongs to; 0 for none
staffidnumber
Who spent it
statusnumber
0 internal, 1 to bill, 2 billed, 4 billed and paid
updatedtext
When it was last changed
vendortext
Who was paid
vis_statenumber
0 active, 1 deleted
Example output
{
  "amount": {
    "amount": "10.00",
    "code": "CAD"
  },
  "categoryid": 121374834,
  "clientid": 0,
  "date": "2016-09-19",
  "expenseid": 1569533,
  "has_receipt": false,
  "id": 1569533,
  "invoiceid": null,
  "notes": "Rocky Road",
  "projectid": 0,
  "staffid": 1,
  "status": 0,
  "updated": "2016-09-27 21:09:13",
  "vendor": "Ice Cream",
  "vis_state": 0
}

Create invoice

Create a draft invoice for a client, with one line or several. Send it with 'Send invoice' or 'Mark invoice as sent'.

Inputs

Clientclient_idtextRequired
The client. Pick one, or give its ID from an earlier step.
Invoice dateinvoice_datedate
The date on the invoice. Leave empty for today.
Due datedue_datedate
When it must be paid. Leave empty for FreshBooks' usual terms.
Currencycurrencytext
Leave empty for the client's own currency.
Item or serviceitemtext
Pick a saved item to fill in its name, description, price and taxes, or type what the line is for.
Quantityquantitynumber
How many. Leave empty for 1.At least 0.
Unit costunit_costnumber
The price of one. Leave empty to use the saved item's price.At least 0.
Line descriptionline_descriptiontext
More detail shown on the line.
Taxtaxtext
A tax to add to the line. Leave empty for the item's own taxes.
Line itemslineslist
For several lines, a list such as [{"name": "Design", "quantity": 2, "unit_cost": 150, "tax_name": "GST", "tax_percent": 5}]. Each line takes name, description, quantity, unit_cost, tax_name, tax_percent, second_tax_name and second_tax_percent. Use it instead of the single line's fields.
Invoice numberinvoice_numbertext
Leave empty for FreshBooks' next number.
Referencepo_numbertext
Your reference, such as the client's purchase order number.
Discount (%)discount_percentnumber
A discount on the whole total, in percent.From 0 to 100.
Notesnotestext
Notes printed for the client, such as thanks or bank details.
Termstermstext
Terms printed for the client, such as when to pay.

Outputs

An invoice

amountobject
The total
create_datetext
The invoice date (YYYY-MM-DD)
created_attext
When it was created
currency_codetext
The invoice's currency
current_organizationtext
The client's name as it is now
customeridnumber
The client's ID
date_paidtext
When it was fully paid
discount_valuetext
Discount, in percent
display_statustext
Status as FreshBooks shows it
due_datetext
The due date (YYYY-MM-DD)
due_offset_daysnumber
Days from the invoice date to the due date
fnametext
The client contact's first name
idnumber
The invoice's ID
invoice_numbertext
The invoice number shown on it, such as 0000007
invoiceidnumber
The invoice's ID again
lineslist
The invoice's lines
lnametext
The client contact's last name
notestext
Notes printed on the invoice
organizationtext
The client's name as printed on the invoice
outstandingobject
What is still owed after any payments. This is the figure a payment reminder should quote, not amount
paidobject
What has been paid
payment_statustext
unpaid, partial or paid
po_numbertext
Your reference, such as a PO number
termstext
Terms printed on the invoice
updatedtext
When it was last changed
v3_statustext
Status: draft, sent, viewed, partial, paid, overdue and so on
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}

Create project

Create a project to track time and expenses against, billed by the hour or at a fixed price.

Inputs

TitletitletextRequired
The project's name.
Clientclient_idtext
The client it is for. Leave empty for none.
Billingproject_typetext
Bill by the hour or at a fixed price.One of: hourly_rate (Hourly rate), fixed_price (Fixed price). Default: hourly_rate.
Hourly rateratenumber
For hourly projects, the rate per hour.Only when Billing is Hourly rate. At least 0.
Fixed pricefixed_pricenumber
For fixed-price projects, the price.Only when Billing is Fixed price. At least 0.
Due datedue_datedate
When the project should be finished.
Descriptiondescriptiontext
What the project is about.

Outputs

A project

activetrue/false
False once the project is deleted
billing_methodtext
How time is billed
client_idnumber
The client billed for it
completetrue/false
Whether it is marked completed
created_attext
When it was created (UTC)
descriptiontext
What the project is about
due_datetext
When it is due (YYYY-MM-DD)
fixed_pricetext
The price, for fixed-price projects
idnumber
The project's ID
internaltrue/false
Whether it is internal work, with no client
project_typetext
hourly_rate or fixed_price
ratetext
The hourly rate, for hourly projects
titletext
The project's title
updated_attext
When it was last changed (UTC)
Example output
{
  "active": true,
  "billing_method": null,
  "client_id": 97499,
  "complete": false,
  "created_at": "2017-07-12T17:22:25",
  "description": null,
  "due_date": null,
  "fixed_price": "500",
  "id": 779803,
  "internal": false,
  "project_type": "fixed_price",
  "rate": null,
  "title": "My Cool Project",
  "updated_at": "2017-07-12T17:22:25"
}

Delete client

Delete a client. FreshBooks keeps it in its deleted list, where it can be restored.

Inputs

Clientclient_idtextRequired
The client. Pick one, or give its ID from an earlier step.

Outputs

The client deleted

client_idnumber
The client's ID
deletedtrue/false
Always true once deleted
Example output
{
  "client_id": 238951,
  "deleted": true
}

Delete estimate

Delete an estimate. FreshBooks keeps it in its deleted list, where it can be restored.

Inputs

Estimate IDestimate_idtextRequired
The estimate's ID, from 'Create estimate'.

Outputs

The estimate deleted

deletedtrue/false
Always true once deleted
estimate_idnumber
The estimate's ID
Example output
{
  "deleted": true,
  "estimate_id": 2168250
}

Delete expense

Delete an expense. FreshBooks keeps it in its deleted list, where it can be restored.

Inputs

Expense IDexpense_idtextRequired
The expense's ID, from 'Create expense' or 'List expenses'.

Outputs

The expense deleted

deletedtrue/false
Always true once deleted
expense_idnumber
The expense's ID
Example output
{
  "deleted": true,
  "expense_id": 1569533
}

Delete invoice

Delete an invoice. FreshBooks keeps it in its deleted list, where it can be restored.

Inputs

Invoice IDinvoice_idtextRequired
The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.

Outputs

The invoice deleted

deletedtrue/false
Always true once deleted
invoice_idnumber
The invoice's ID
Example output
{
  "deleted": true,
  "invoice_id": 1627
}

Delete payment

Delete a payment recorded by mistake. The invoice is owed again.

Inputs

Payment IDpayment_idtextRequired
The payment's ID, from 'Record payment' or 'List payments'.

Outputs

The payment deleted

deletedtrue/false
Always true once deleted
payment_idnumber
The payment's ID
Example output
{
  "deleted": true,
  "payment_id": 10865341
}

Delete project

Delete a project for good.

Inputs

Projectproject_idtextRequired
The project. Pick one, or give its ID from an earlier step.

Outputs

The project deleted

deletedtrue/false
Always true once deleted
project_idnumber
The project's ID
Example output
{
  "deleted": true,
  "project_id": 779803
}

Delete time entry

Delete logged time for good.

Inputs

Time entry IDtime_entry_idtextRequired
The time entry's ID, from 'Log time' or 'List time entries'.

Outputs

The time entry deleted

deletedtrue/false
Always true once deleted
time_entry_idnumber
The time entry's ID
Example output
{
  "deleted": true,
  "time_entry_id": 5100
}

Find client

Find a client by email address, or by part of their name or company. Says whether one was found, so a workflow can create the client when not.

Inputs

Emailemailtext
The client's exact email address.
Name or companynametext
Part of the client's name or company.

Outputs

The client found

clientobject
The first client found; empty when none
countnumber
How many clients matched
foundtrue/false
Whether any client matched
Example output
{
  "client": {
    "bus_phone": "",
    "currency_code": "USD",
    "email": "email1@freshbooks.com",
    "fname": "first1",
    "id": 238951,
    "language": "en",
    "lname": "last1",
    "mob_phone": "",
    "note": null,
    "organization": "company1",
    "p_city": "Toronto",
    "p_code": "M6P 3T1",
    "p_country": "Canada",
    "p_province": "Ontario",
    "p_street": "1655 Dupont St. W.",
    "p_street2": "",
    "signup_date": "2022-01-05 12:17:11",
    "updated": "2022-01-05 07:17:12",
    "userid": 238951,
    "vat_name": null,
    "vat_number": "",
    "vis_state": 0
  },
  "count": 1,
  "found": true
}

Get client

Get a client's details by ID.

Inputs

Clientclient_idtextRequired
The client. Pick one, or give its ID from an earlier step.

Outputs

A client

bus_phonetext
Business phone
currency_codetext
The currency the client is billed in
emailtext
Email address
fnametext
First name
idnumber
The client's ID
languagetext
Language code for what they are sent, such as en
lnametext
Last name
mob_phonetext
Mobile phone
notetext
Your notes about the client
organizationtext
Company name
p_citytext
Billing city
p_codetext
Billing postal code
p_countrytext
Billing country
p_provincetext
Billing state or province
p_streettext
Billing street
p_street2text
Billing street, second line
signup_datetext
When the client was added (UTC)
updatedtext
When the client was last changed
useridnumber
The client's ID again, as older endpoints name it
vat_nametext
Tax number label, such as VAT
vat_numbertext
Tax number
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "bus_phone": "",
  "currency_code": "USD",
  "email": "email1@freshbooks.com",
  "fname": "first1",
  "id": 238951,
  "language": "en",
  "lname": "last1",
  "mob_phone": "",
  "note": null,
  "organization": "company1",
  "p_city": "Toronto",
  "p_code": "M6P 3T1",
  "p_country": "Canada",
  "p_province": "Ontario",
  "p_street": "1655 Dupont St. W.",
  "p_street2": "",
  "signup_date": "2022-01-05 12:17:11",
  "updated": "2022-01-05 07:17:12",
  "userid": 238951,
  "vat_name": null,
  "vat_number": "",
  "vis_state": 0
}

Get invoice

Get an invoice with its lines, totals and status.

Inputs

Invoice IDinvoice_idtextRequired
The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.

Outputs

An invoice

amountobject
The total
create_datetext
The invoice date (YYYY-MM-DD)
created_attext
When it was created
currency_codetext
The invoice's currency
current_organizationtext
The client's name as it is now
customeridnumber
The client's ID
date_paidtext
When it was fully paid
discount_valuetext
Discount, in percent
display_statustext
Status as FreshBooks shows it
due_datetext
The due date (YYYY-MM-DD)
due_offset_daysnumber
Days from the invoice date to the due date
fnametext
The client contact's first name
idnumber
The invoice's ID
invoice_numbertext
The invoice number shown on it, such as 0000007
invoiceidnumber
The invoice's ID again
lineslist
The invoice's lines
lnametext
The client contact's last name
notestext
Notes printed on the invoice
organizationtext
The client's name as printed on the invoice
outstandingobject
What is still owed after any payments. This is the figure a payment reminder should quote, not amount
paidobject
What has been paid
payment_statustext
unpaid, partial or paid
po_numbertext
Your reference, such as a PO number
termstext
Terms printed on the invoice
updatedtext
When it was last changed
v3_statustext
Status: draft, sent, viewed, partial, paid, overdue and so on
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}

List clients

List clients, optionally only those whose name matches.

Inputs

Name or company containssearchtext
Only clients whose name or company contains this.
Pagepagenumber
Which page of results, starting at 1. Leave empty for the first.At least 1.
Per pageper_pagenumber
How many per page, 1 to 100. Leave empty for 100.From 1 to 100.

Outputs

One page of clients

clientslist
The clients on this page
countnumber
How many clients are on this page
pagenumber
This page's number, starting at 1
pagesnumber
How many pages there are
totalnumber
How many clients match, on every page
Example output
{
  "clients": [
    {
      "bus_phone": "",
      "currency_code": "USD",
      "email": "email1@freshbooks.com",
      "fname": "first1",
      "id": 238951,
      "language": "en",
      "lname": "last1",
      "mob_phone": "",
      "note": null,
      "organization": "company1",
      "p_city": "Toronto",
      "p_code": "M6P 3T1",
      "p_country": "Canada",
      "p_province": "Ontario",
      "p_street": "1655 Dupont St. W.",
      "p_street2": "",
      "signup_date": "2022-01-05 12:17:11",
      "updated": "2022-01-05 07:17:12",
      "userid": 238951,
      "vat_name": null,
      "vat_number": "",
      "vis_state": 0
    }
  ],
  "count": 1,
  "page": 1,
  "pages": 1,
  "total": 1
}

List expenses

List expenses, optionally by category, client, project or date.

Inputs

Categorycategorytext
Only expenses in this category.
Clientclient_idtext
Only this client's. Leave empty for every client.
Projectproject_idtext
Only expenses for this project.
Spent on or afterfrom_datedate
Only expenses dated on or after this day.
Spent on or beforeto_datedate
Only expenses dated on or before this day.
Pagepagenumber
Which page of results, starting at 1. Leave empty for the first.At least 1.
Per pageper_pagenumber
How many per page, 1 to 100. Leave empty for 100.From 1 to 100.

Outputs

One page of expenses

countnumber
How many expenses are on this page
expenseslist
The expenses on this page
pagenumber
This page's number, starting at 1
pagesnumber
How many pages there are
totalnumber
How many expenses match, on every page
Example output
{
  "count": 1,
  "expenses": [
    {
      "amount": {
        "amount": "10.00",
        "code": "CAD"
      },
      "categoryid": 121374834,
      "clientid": 0,
      "date": "2016-09-19",
      "expenseid": 1569533,
      "has_receipt": false,
      "id": 1569533,
      "invoiceid": null,
      "notes": "Rocky Road",
      "projectid": 0,
      "staffid": 1,
      "status": 0,
      "updated": "2016-09-27 21:09:13",
      "vendor": "Ice Cream",
      "vis_state": 0
    }
  ],
  "page": 1,
  "pages": 1,
  "total": 1
}

List invoices

List invoices, optionally by client, status or date, or only those overdue by a number of days. Each comes with the client's email and its amounts and due date ready to put in a message.

Inputs

Clientclient_idtext
Only this client's. Leave empty for every client.
Statusstatustext
Only invoices in this status.One of: draft, sent, viewed, partial (Partly paid), paid, overdue, disputed.
Dated on or afterfrom_datedate
Only invoices dated on or after this day.
Dated on or beforeto_datedate
Only invoices dated on or before this day.
Overdue by at least (days)overdue_by_daysnumber
Beta. Only sent invoices that still owe money and whose due date was at least this many days ago, oldest first: 1 gives everything overdue, 31 gives invoices more than 30 days overdue. Every matching invoice is returned in one list, so no paging or date check is needed; leave Status, Page and Per page empty. Leave empty to list invoices whether overdue or not.At least 1.
Pagepagenumber
Which page of results, starting at 1. Leave empty for the first.At least 1.
Per pageper_pagenumber
How many per page, 1 to 100. Leave empty for 100.From 1 to 100.

Outputs

One page of invoices

countnumber
How many invoices are on this page
incompletetrue/false
Beta. True only when Overdue by at least (days) had more than 5,000 unpaid invoices to look through and stopped there, so some may be missing
invoiceslist
The invoices on this page
pagenumber
This page's number, starting at 1
pagesnumber
How many pages there are
totalnumber
How many invoices match, on every page
total_outstanding_displaytext
Beta. What the invoices returned still owe, added up and written for a message, such as $4,200.50 (one total per currency)
Example output
{
  "count": 1,
  "incomplete": false,
  "invoices": [
    {
      "amount": {
        "amount": "264.00",
        "code": "USD"
      },
      "amount_display": "$264.00",
      "client_email": "email1@freshbooks.com",
      "client_first_name": "F_Name",
      "client_name": "Test Client company",
      "create_date": "2021-08-17",
      "created_at": "2021-08-17 08:20:11",
      "currency_code": "USD",
      "current_organization": "Test Client company",
      "customerid": 2280,
      "date_paid": null,
      "days_overdue": 32,
      "discount_value": "0",
      "display_status": "sent",
      "due_date": "2021-09-16",
      "due_date_display": "Sep 16, 2021",
      "due_offset_days": 30,
      "fname": "F_Name",
      "id": 1627,
      "invoice_number": "0000003",
      "invoiceid": 1627,
      "lines": [
        {
          "amount": {
            "amount": "240",
            "code": "USD"
          },
          "description": "",
          "lineid": 1,
          "name": "Photography Services",
          "qty": "1",
          "taxAmount1": "10",
          "taxAmount2": "0",
          "taxName1": "GST",
          "taxName2": "",
          "unit_cost": {
            "amount": "240",
            "code": "USD"
          }
        }
      ],
      "lname": "L_Name",
      "notes": "Enter notes or Bank transfer details",
      "organization": "Test Client company",
      "outstanding": {
        "amount": "264.00",
        "code": "USD"
      },
      "outstanding_display": "$264.00",
      "paid": {
        "amount": "0.00",
        "code": "USD"
      },
      "payment_status": "unpaid",
      "po_number": null,
      "terms": "Pay within 30 days.",
      "updated": "2021-08-17 08:20:12",
      "v3_status": "sent",
      "vis_state": 0
    }
  ],
  "page": 1,
  "pages": 1,
  "total": 1,
  "total_outstanding_display": "$264.00"
}

List payments

List payments received, optionally by invoice, client or date.

Inputs

Invoice IDinvoice_idtext
Only payments on this invoice.
Clientclient_idtext
Only this client's. Leave empty for every client.
Paid on or afterfrom_datedate
Only payments made on or after this day.
Paid on or beforeto_datedate
Only payments made on or before this day.
Pagepagenumber
Which page of results, starting at 1. Leave empty for the first.At least 1.
Per pageper_pagenumber
How many per page, 1 to 100. Leave empty for 100.From 1 to 100.

Outputs

One page of payments

countnumber
How many payments are on this page
pagenumber
This page's number, starting at 1
pagesnumber
How many pages there are
paymentslist
The payments on this page
totalnumber
How many payments match, on every page
Example output
{
  "count": 1,
  "page": 1,
  "pages": 1,
  "payments": [
    {
      "amount": {
        "amount": "10.00",
        "code": "USD"
      },
      "clientid": 1831231,
      "date": "2013-12-10",
      "from_credit": false,
      "gateway": null,
      "id": 10865341,
      "invoiceid": 2214249,
      "note": "",
      "type": "Check",
      "updated": "2016-09-29 19:09:17",
      "vis_state": 0
    }
  ],
  "total": 1
}

List projects

List projects, open, completed or both.

Inputs

Statusstatustext
Only open or only completed projects. Leave empty for both.One of: open, completed.
Pagepagenumber
Which page of results, starting at 1. Leave empty for the first.At least 1.
Per pageper_pagenumber
How many per page, 1 to 100. Leave empty for 100.From 1 to 100.

Outputs

One page of projects

countnumber
How many projects are on this page
pagenumber
This page's number, starting at 1
pagesnumber
How many pages there are
projectslist
The projects on this page
totalnumber
How many projects match, on every page
Example output
{
  "count": 1,
  "page": 1,
  "pages": 1,
  "projects": [
    {
      "active": true,
      "billing_method": null,
      "client_id": 97499,
      "complete": false,
      "created_at": "2017-07-12T17:22:25",
      "description": null,
      "due_date": null,
      "fixed_price": "500",
      "id": 779803,
      "internal": false,
      "project_type": "fixed_price",
      "rate": null,
      "title": "My Cool Project",
      "updated_at": "2017-07-12T17:22:25"
    }
  ],
  "total": 1
}

List time entries

List logged time, optionally by client or when it started.

Inputs

Clientclient_idtext
Only this client's. Leave empty for every client.
Started fromstarted_fromdate and time
Only time that started at or after this moment.
Started untilstarted_todate and time
Only time that started at or before this moment.
Pagepagenumber
Which page of results, starting at 1. Leave empty for the first.At least 1.
Per pageper_pagenumber
How many per page, 1 to 100. Leave empty for 100.From 1 to 100.

Outputs

One page of time entries

countnumber
How many time entries are on this page
pagenumber
This page's number, starting at 1
pagesnumber
How many pages there are
time_entrieslist
The time entries on this page
totalnumber
How many time entries match, on every page
Example output
{
  "count": 1,
  "page": 1,
  "pages": 1,
  "time_entries": [
    {
      "active": true,
      "client_id": 2149780,
      "duration": 7200,
      "id": 5100,
      "is_logged": true,
      "note": "Stuff",
      "project_id": 153125,
      "started_at": "2016-08-16T20:00:00Z"
    }
  ],
  "total": 1
}

Log time

Log time you worked, as yourself, optionally on a project or for a client.

Inputs

HourshoursnumberRequired
How long, in hours, such as 1.5 for an hour and a half.At least 0.
Startedstarted_atdate and time
When the work started. Leave empty for work ending now.
Notenotetext
What you worked on.
Projectproject_idtext
The project it belongs to. Leave empty for none.
Clientclient_idtext
The client the time is for. Leave empty for none.

Outputs

A time entry

activetrue/false
False once deleted
client_idnumber
The client the time is for
durationnumber
How long, in seconds
idnumber
The time entry's ID
is_loggedtrue/false
False while a timer is still running
notetext
What was done
project_idnumber
The project worked on
started_attext
When the work started (UTC)
Example output
{
  "active": true,
  "client_id": 2149780,
  "duration": 7200,
  "id": 5100,
  "is_logged": true,
  "note": "Stuff",
  "project_id": 153125,
  "started_at": "2016-08-16T20:00:00Z"
}

Mark invoice as sent

Mark a draft invoice as sent without emailing it, for one you deliver yourself. FreshBooks then counts it in its reports.

Inputs

Invoice IDinvoice_idtextRequired
The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.

Outputs

An invoice

amountobject
The total
create_datetext
The invoice date (YYYY-MM-DD)
created_attext
When it was created
currency_codetext
The invoice's currency
current_organizationtext
The client's name as it is now
customeridnumber
The client's ID
date_paidtext
When it was fully paid
discount_valuetext
Discount, in percent
display_statustext
Status as FreshBooks shows it
due_datetext
The due date (YYYY-MM-DD)
due_offset_daysnumber
Days from the invoice date to the due date
fnametext
The client contact's first name
idnumber
The invoice's ID
invoice_numbertext
The invoice number shown on it, such as 0000007
invoiceidnumber
The invoice's ID again
lineslist
The invoice's lines
lnametext
The client contact's last name
notestext
Notes printed on the invoice
organizationtext
The client's name as printed on the invoice
outstandingobject
What is still owed after any payments. This is the figure a payment reminder should quote, not amount
paidobject
What has been paid
payment_statustext
unpaid, partial or paid
po_numbertext
Your reference, such as a PO number
termstext
Terms printed on the invoice
updatedtext
When it was last changed
v3_statustext
Status: draft, sent, viewed, partial, paid, overdue and so on
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}

Record payment

Record a payment you received against an invoice. With no amount, it pays what is still owed.

Inputs

Invoice IDinvoice_idtextRequired
The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
Amountamountnumber
How much was paid. Leave empty for what is still owed.At least 0.
Payment datepayment_datedate
When it was paid. Leave empty for today.
Payment methodpayment_typetext
How it was paid.One of: Cash, Check, Bank Transfer, Credit Card, Debit (Debit card), ACH, PayPal, VISA, MASTERCARD, AMEX (American Express), and 6 more.
Notenotetext
A note, such as a check or reference number.

Outputs

A payment

amountobject
How much was paid
clientidnumber
The client who paid
datetext
When it was paid (YYYY-MM-DD)
from_credittrue/false
Whether it was paid from the client's credit
gatewaytext
The online payment service, if any
idnumber
The payment's ID
invoiceidnumber
The invoice it pays
notetext
Your note on the payment
typetext
How it was paid, such as Check or Cash
updatedtext
When it was last changed
vis_statenumber
0 active, 1 deleted
Example output
{
  "amount": {
    "amount": "10.00",
    "code": "USD"
  },
  "clientid": 1831231,
  "date": "2013-12-10",
  "from_credit": false,
  "gateway": null,
  "id": 10865341,
  "invoiceid": 2214249,
  "note": "",
  "type": "Check",
  "updated": "2016-09-29 19:09:17",
  "vis_state": 0
}

Send invoice

Email an invoice from FreshBooks, with a link to view and pay it. Marks it as sent.

Inputs

Invoice IDinvoice_idtextRequired
The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
Send torecipientstext
Email addresses, separated by commas. Leave empty for the client's email.
Subjectsubjecttext
Leave empty for FreshBooks' usual subject.
Messagemessagetext
Leave empty for FreshBooks' usual message.
Attach PDFattach_pdftrue/false
Attach the invoice as a PDF too.Default: false.

Outputs

The invoice sent

invoiceobject
An invoice
recipientslist
The email addresses it was sent to
Example output
{
  "invoice": {
    "amount": {
      "amount": "264.00",
      "code": "USD"
    },
    "create_date": "2021-08-17",
    "created_at": "2021-08-17 08:20:11",
    "currency_code": "USD",
    "current_organization": "Test Client company",
    "customerid": 2280,
    "date_paid": null,
    "discount_value": "0",
    "display_status": "sent",
    "due_date": "2021-09-16",
    "due_offset_days": 30,
    "fname": "F_Name",
    "id": 1627,
    "invoice_number": "0000003",
    "invoiceid": 1627,
    "lines": [
      {
        "amount": {
          "amount": "240",
          "code": "USD"
        },
        "description": "",
        "lineid": 1,
        "name": "Photography Services",
        "qty": "1",
        "taxAmount1": "10",
        "taxAmount2": "0",
        "taxName1": "GST",
        "taxName2": "",
        "unit_cost": {
          "amount": "240",
          "code": "USD"
        }
      }
    ],
    "lname": "L_Name",
    "notes": "Enter notes or Bank transfer details",
    "organization": "Test Client company",
    "outstanding": {
      "amount": "264.00",
      "code": "USD"
    },
    "paid": {
      "amount": "0.00",
      "code": "USD"
    },
    "payment_status": "unpaid",
    "po_number": null,
    "terms": "Pay within 30 days.",
    "updated": "2021-08-17 08:20:12",
    "v3_status": "sent",
    "vis_state": 0
  },
  "recipients": [
    "email1@freshbooks.com"
  ]
}

Update client

Change a client's details. Only the fields you fill in change.

Inputs

Clientclient_idtextRequired
The client. Pick one, or give its ID from an earlier step.
First namefirst_nametext
The contact's first name.
Last namelast_nametext
The contact's last name.
Companyorganizationtext
The client's company or organization name.
Emailemailtext
Where invoices and estimates are sent.
Phonephonetext
The business phone number.
Mobile phonemobile_phonetext
The mobile phone number.
Currencycurrencytext
The currency the client is billed in.
Streetstreettext
Billing address: street.
Street line 2street2text
Billing address: second line.
Citycitytext
Billing address: city.
State or provinceprovincetext
Billing address: state or province.
Postal codepostal_codetext
Billing address: ZIP or postal code.
Countrycountrytext
Billing address: country, such as United States.
Notesnotestext
Your own notes about the client. Clients don't see them.

Outputs

A client

bus_phonetext
Business phone
currency_codetext
The currency the client is billed in
emailtext
Email address
fnametext
First name
idnumber
The client's ID
languagetext
Language code for what they are sent, such as en
lnametext
Last name
mob_phonetext
Mobile phone
notetext
Your notes about the client
organizationtext
Company name
p_citytext
Billing city
p_codetext
Billing postal code
p_countrytext
Billing country
p_provincetext
Billing state or province
p_streettext
Billing street
p_street2text
Billing street, second line
signup_datetext
When the client was added (UTC)
updatedtext
When the client was last changed
useridnumber
The client's ID again, as older endpoints name it
vat_nametext
Tax number label, such as VAT
vat_numbertext
Tax number
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "bus_phone": "",
  "currency_code": "USD",
  "email": "email1@freshbooks.com",
  "fname": "first1",
  "id": 238951,
  "language": "en",
  "lname": "last1",
  "mob_phone": "",
  "note": null,
  "organization": "company1",
  "p_city": "Toronto",
  "p_code": "M6P 3T1",
  "p_country": "Canada",
  "p_province": "Ontario",
  "p_street": "1655 Dupont St. W.",
  "p_street2": "",
  "signup_date": "2022-01-05 12:17:11",
  "updated": "2022-01-05 07:17:12",
  "userid": 238951,
  "vat_name": null,
  "vat_number": "",
  "vis_state": 0
}

Update invoice

Change an invoice's dates, number, reference, discount, notes, terms or lines. Only the fields you fill in change.

Inputs

Invoice IDinvoice_idtextRequired
The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
Invoice dateinvoice_datedate
A new date for the invoice. Leave empty to keep it.
Due datedue_datedate
A new due date. Leave empty to keep it.
Invoice numberinvoice_numbertext
A new invoice number. Leave empty to keep it.
Referencepo_numbertext
A new reference. Leave empty to keep it.
Discount (%)discount_percentnumber
A new discount on the whole total. Leave empty to keep it.From 0 to 100.
Notesnotestext
New notes for the client. Leave empty to keep them.
Termstermstext
New terms. Leave empty to keep them.
Line itemslineslist
Replaces every line, as a list such as [{"name": "Design", "quantity": 2, "unit_cost": 150}]. Each line takes name, description, quantity, unit_cost, tax_name, tax_percent, second_tax_name and second_tax_percent. Leave empty to keep the lines.

Outputs

An invoice

amountobject
The total
create_datetext
The invoice date (YYYY-MM-DD)
created_attext
When it was created
currency_codetext
The invoice's currency
current_organizationtext
The client's name as it is now
customeridnumber
The client's ID
date_paidtext
When it was fully paid
discount_valuetext
Discount, in percent
display_statustext
Status as FreshBooks shows it
due_datetext
The due date (YYYY-MM-DD)
due_offset_daysnumber
Days from the invoice date to the due date
fnametext
The client contact's first name
idnumber
The invoice's ID
invoice_numbertext
The invoice number shown on it, such as 0000007
invoiceidnumber
The invoice's ID again
lineslist
The invoice's lines
lnametext
The client contact's last name
notestext
Notes printed on the invoice
organizationtext
The client's name as printed on the invoice
outstandingobject
What is still owed after any payments. This is the figure a payment reminder should quote, not amount
paidobject
What has been paid
payment_statustext
unpaid, partial or paid
po_numbertext
Your reference, such as a PO number
termstext
Terms printed on the invoice
updatedtext
When it was last changed
v3_statustext
Status: draft, sent, viewed, partial, paid, overdue and so on
vis_statenumber
0 active, 1 deleted, 2 archived
Example output
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}

On this page