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
| Action | What it does |
|---|---|
| Create client | Add a client: a company or person you bill. |
| Create estimate | Create a draft estimate (a quote) for a client, with one line or several. |
| Create expense | Record money your business spent, optionally to bill on to a client or project. |
| Create invoice | Create a draft invoice for a client, with one line or several. |
| Create project | Create a project to track time and expenses against, billed by the hour or at a fixed price. |
| Delete client | Delete a client. |
| Delete estimate | Delete an estimate. |
| Delete expense | Delete an expense. |
| Delete invoice | Delete an invoice. |
| Delete payment | Delete a payment recorded by mistake. |
| Delete project | Delete a project for good. |
| Delete time entry | Delete logged time for good. |
| Find client | Find a client by email address, or by part of their name or company. |
| Get client | Get a client's details by ID. |
| Get invoice | Get an invoice with its lines, totals and status. |
| List clients | List clients, optionally only those whose name matches. |
| List expenses | List expenses, optionally by category, client, project or date. |
| List invoices | List invoices, optionally by client, status or date, or only those overdue by a number of days. |
| List payments | List payments received, optionally by invoice, client or date. |
| List projects | List projects, open, completed or both. |
| List time entries | List logged time, optionally by client or when it started. |
| Log time | Log time you worked, as yourself, optionally on a project or for a client. |
| Mark invoice as sent | Mark a draft invoice as sent without emailing it, for one you deliver yourself. |
| Record payment | Record a payment you received against an invoice. |
| Send invoice | Email an invoice from FreshBooks, with a link to view and pay it. |
| Update client | Change a client's details. |
| Update invoice | Change 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 name
first_nametext - The contact's first name.
- Last name
last_nametext - The contact's last name.
- Company
organizationtext - The client's company or organization name.
- Email
emailtext - Where invoices and estimates are sent.
- Phone
phonetext - The business phone number.
- Mobile phone
mobile_phonetext - The mobile phone number.
- Currency
currencytext - The currency the client is billed in.
- Street
streettext - Billing address: street.
- Street line 2
street2text - Billing address: second line.
- City
citytext - Billing address: city.
- State or province
provincetext - Billing address: state or province.
- Postal code
postal_codetext - Billing address: ZIP or postal code.
- Country
countrytext - Billing address: country, such as United States.
- Notes
notestext - 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
- Client
client_idtextRequired - The client. Pick one, or give its ID from an earlier step.
- Estimate date
estimate_datedate - The date on the estimate. Leave empty for today.
- Currency
currencytext - Leave empty for the client's own currency.
- Item or service
itemtext - Pick a saved item to fill in its name, description, price and taxes, or type what the line is for.
- Quantity
quantitynumber - How many. Leave empty for 1.At least 0.
- Unit cost
unit_costnumber - The price of one. Leave empty to use the saved item's price.At least 0.
- Line description
line_descriptiontext - More detail shown on the line.
- Tax
taxtext - A tax to add to the line. Leave empty for the item's own taxes.
- Line items
lineslist - 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 number
estimate_numbertext - Leave empty for FreshBooks' next number.
- Reference
po_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.
- Notes
notestext - Notes printed for the client, such as thanks or bank details.
- Terms
termstext - 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
- Category
categorytextRequired - The expense category. Pick one, or type its name.
- Amount
amountnumberRequired - How much was spent.At least 0.
- Date
expense_datedate - When it was spent. Leave empty for today.
- Vendor
vendortext - Who was paid, such as a shop or supplier.
- Notes
notestext - What it was for.
- Currency
currencytext - Leave empty for your business's currency.
- Client
client_idtext - A client to bill the expense to. Leave empty for none.
- Project
project_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
- Client
client_idtextRequired - The client. Pick one, or give its ID from an earlier step.
- Invoice date
invoice_datedate - The date on the invoice. Leave empty for today.
- Due date
due_datedate - When it must be paid. Leave empty for FreshBooks' usual terms.
- Currency
currencytext - Leave empty for the client's own currency.
- Item or service
itemtext - Pick a saved item to fill in its name, description, price and taxes, or type what the line is for.
- Quantity
quantitynumber - How many. Leave empty for 1.At least 0.
- Unit cost
unit_costnumber - The price of one. Leave empty to use the saved item's price.At least 0.
- Line description
line_descriptiontext - More detail shown on the line.
- Tax
taxtext - A tax to add to the line. Leave empty for the item's own taxes.
- Line items
lineslist - 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 number
invoice_numbertext - Leave empty for FreshBooks' next number.
- Reference
po_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.
- Notes
notestext - Notes printed for the client, such as thanks or bank details.
- Terms
termstext - 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
- Title
titletextRequired - The project's name.
- Client
client_idtext - The client it is for. Leave empty for none.
- Billing
project_typetext - Bill by the hour or at a fixed price.One of:
hourly_rate(Hourly rate),fixed_price(Fixed price). Default:hourly_rate. - Hourly rate
ratenumber - For hourly projects, the rate per hour.Only when Billing is Hourly rate. At least 0.
- Fixed price
fixed_pricenumber - For fixed-price projects, the price.Only when Billing is Fixed price. At least 0.
- Due date
due_datedate - When the project should be finished.
- Description
descriptiontext - 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
- Client
client_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 ID
estimate_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 ID
expense_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 ID
invoice_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 ID
payment_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
- Project
project_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 ID
time_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
- Email
emailtext - The client's exact email address.
- Name or company
nametext - 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
- Client
client_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 ID
invoice_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 contains
searchtext - Only clients whose name or company contains this.
- Page
pagenumber - Which page of results, starting at 1. Leave empty for the first.At least 1.
- Per page
per_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
- Category
categorytext - Only expenses in this category.
- Client
client_idtext - Only this client's. Leave empty for every client.
- Project
project_idtext - Only expenses for this project.
- Spent on or after
from_datedate - Only expenses dated on or after this day.
- Spent on or before
to_datedate - Only expenses dated on or before this day.
- Page
pagenumber - Which page of results, starting at 1. Leave empty for the first.At least 1.
- Per page
per_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
- Client
client_idtext - Only this client's. Leave empty for every client.
- Status
statustext - Only invoices in this status.One of:
draft,sent,viewed,partial(Partly paid),paid,overdue,disputed. - Dated on or after
from_datedate - Only invoices dated on or after this day.
- Dated on or before
to_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.
- Page
pagenumber - Which page of results, starting at 1. Leave empty for the first.At least 1.
- Per page
per_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 ID
invoice_idtext - Only payments on this invoice.
- Client
client_idtext - Only this client's. Leave empty for every client.
- Paid on or after
from_datedate - Only payments made on or after this day.
- Paid on or before
to_datedate - Only payments made on or before this day.
- Page
pagenumber - Which page of results, starting at 1. Leave empty for the first.At least 1.
- Per page
per_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
- Status
statustext - Only open or only completed projects. Leave empty for both.One of:
open,completed. - Page
pagenumber - Which page of results, starting at 1. Leave empty for the first.At least 1.
- Per page
per_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
- Client
client_idtext - Only this client's. Leave empty for every client.
- Started from
started_fromdate and time - Only time that started at or after this moment.
- Started until
started_todate and time - Only time that started at or before this moment.
- Page
pagenumber - Which page of results, starting at 1. Leave empty for the first.At least 1.
- Per page
per_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
- Hours
hoursnumberRequired - How long, in hours, such as 1.5 for an hour and a half.At least 0.
- Started
started_atdate and time - When the work started. Leave empty for work ending now.
- Note
notetext - What you worked on.
- Project
project_idtext - The project it belongs to. Leave empty for none.
- Client
client_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 ID
invoice_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 ID
invoice_idtextRequired - The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
- Amount
amountnumber - How much was paid. Leave empty for what is still owed.At least 0.
- Payment date
payment_datedate - When it was paid. Leave empty for today.
- Payment method
payment_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. - Note
notetext - 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 ID
invoice_idtextRequired - The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
- Send to
recipientstext - Email addresses, separated by commas. Leave empty for the client's email.
- Subject
subjecttext - Leave empty for FreshBooks' usual subject.
- Message
messagetext - Leave empty for FreshBooks' usual message.
- Attach PDF
attach_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
- Client
client_idtextRequired - The client. Pick one, or give its ID from an earlier step.
- First name
first_nametext - The contact's first name.
- Last name
last_nametext - The contact's last name.
- Company
organizationtext - The client's company or organization name.
- Email
emailtext - Where invoices and estimates are sent.
- Phone
phonetext - The business phone number.
- Mobile phone
mobile_phonetext - The mobile phone number.
- Currency
currencytext - The currency the client is billed in.
- Street
streettext - Billing address: street.
- Street line 2
street2text - Billing address: second line.
- City
citytext - Billing address: city.
- State or province
provincetext - Billing address: state or province.
- Postal code
postal_codetext - Billing address: ZIP or postal code.
- Country
countrytext - Billing address: country, such as United States.
- Notes
notestext - 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 ID
invoice_idtextRequired - The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
- Invoice date
invoice_datedate - A new date for the invoice. Leave empty to keep it.
- Due date
due_datedate - A new due date. Leave empty to keep it.
- Invoice number
invoice_numbertext - A new invoice number. Leave empty to keep it.
- Reference
po_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.
- Notes
notestext - New notes for the client. Leave empty to keep them.
- Terms
termstext - New terms. Leave empty to keep them.
- Line items
lineslist - 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
}