FreshBooks API Documentation
Introduction
The FreshBooks API is an interface for accessing your FreshBooks data using JSON. The API makes it easy to create web and desktop applications that integrate with your account. Possible uses for it include automatically creating and sending invoices when users sign up on your website, pulling lists of client information, copying data to 3rd party services, and more.
Check out our Scenarios and API Reference sections to see what to expect, and when you’re ready, sign up for a FreshBooks account if you don’t have one, and proceed to the developer page to create an application and start development.
Quick Start
Be sure to check our the Tools and Libraries page where we list our SDKs and some example code to help you get started.
The column on the right-hand side has a curl call that demonstrates the required Headers and general format of requests to the FreshBooks API.
Requests are authenticated using OAuth2 Bearer tokens which you receive in exchange for a code we issue after a logged-in user performs an authorization grant request. You can create an OAuth application and get a client id and secret in your FreshBooks developer page
Required Headers
There are two required headers for most calls:
- Content-Type: application/json
- Authorization: Bearer <TOKEN>
We need those two to understand and authenticate your call. The black code pane on this page shows an example of a call that sends these headers correctly.
Creating your application on FreshBooks
Create an account by visiting our sign up page. If you already have a FreshBooks account, log in by visiting our log in page. You can reach out to our support team to have your account put on our partner plan.
- Now visit the developer page and create a new app.
- Make sure to include the name of the application and redirect URI in the application form.
The name of the application has to be unique as it will be used to display on the FreshBooks app store and on a FreshBooks user’s integrations page once they have connected with your application. The redirect URI should be an endpoint in your application that will receive the authorization code and will use it to retrieve the bearer token and refresh token. These will be necessary to make authenticated calls to the FreshBooks API. To get more information on our authentication process visit our Oauth documentation. - Save your application.
Before you start
Here’s a quick checklist of some of the things we require to consider any integration an A+ integration:
- Create a dedicated page for the integration on your website
- Create a dedicated link/page that can be linked to in our Integrations page which allows for easy App Enablement
- An Application Logo that can be used for the integration, both in-app, and in the Integrations page
- Create a link back to FreshBooks on your website. This link should include a description of FreshBooks
- Provide a description of your support hours and policies to FreshBooks
- The application should have easy self-serve on-boarding – meaning that FreshBooks users should be able to turn the integration on without needing to email, or speak with someone
- FreshBooks has various account levels which include a limited number of clients for certain users. As such, when you build an integration, you should consider building the integration for supporting all FreshBooks customers, or you should explicitly communicate which customers your integration are built for
Join the FreshBooks Developer Community!
Stay connected to the latest with the FreshBooks API by joining our mailing list
If you would like to list your application on our App Store fill the request form
Follow us on Twitter @ freshbooksdevs
Create Single Client
curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/users/clients' \ -H 'Authorization: Bearer <insert-bearer-token>' \ -H 'Content-Type: application/json' \ --data-raw '{ "client": { "fname": "first1", "lname": "last1", "email": "[email protected]", "organization": "company1", "vat_name": null, "vat_number": "", "status": null, "note": null, "home_phone": null, "userid": null, "source": null, "highlight_string": null, "p_street": "1655 Dupont St. W.", "p_street2": null, "p_city": "Toronto", "p_country": "Canada", "p_province": "Ontario", "p_code": "M6P 3T1", "currency_code": "USD", "language": "en", "last_activity": null, "face": null, "late_fee": null, "late_reminders": [], "contacts": [ { "email": "[email protected]", "fname": "first2", "lname": "last2", "phone1": null, "userid": null, "face": null }, { "email": "[email protected]", "fname": "first3", "lname": "last3", "phone1": null, "userid": null, "face": null } ] } }' #Response:{ "response": { "result": { "client": { "accounting_systemid": "LJArJ4", "allow_email_include_pdf": false, "allow_late_fees": true, "allow_late_notifications": true, "bus_phone": "", "company_industry": null, "company_size": null, "currency_code": "USD", "direct_link_token": null, "email": "[email protected]", "exceeds_client_limit": 0, "fax": "", "fname": "first1", "has_retainer": null, "home_phone": null, "id": 238950, "language": "en", "last_activity": null, "last_login": null, "level": 0, "lname": "last1", "mob_phone": "", "note": null, "notified": false, "num_logins": 0, "organization": "company1", "p_city": "Toronto", "p_code": "M6P 3T1", "p_country": "Canada", "p_province": "Ontario", "p_street": "1655 Dupont St. W.", "p_street2": "", "pref_email": true, "pref_gmail": false, "retainer_id": null, "role": "client", "s_city": "", "s_code": "", "s_country": "", "s_province": "", "s_street": "", "s_street2": "", "signup_date": "2022-01-05 12:15:25", "statement_token": null, "subdomain": null, "updated": "2022-01-05 07:15:25", "userid": 238950, "username": "first1last12", "uuid": "ff7b6d5a-218e-4ac8-9114-845d4d67afe1", "vat_name": null, "vat_number": "", "vis_state": 0 } } } }
List Clients
curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/users/clients' \ -H 'Authorization: Bearer <insert-bearer-token>' #Response:{ "response": { "result": { "clients": [ { "accounting_systemid": "LJArJ4", "allow_email_include_pdf": false, "allow_late_fees": true, "allow_late_notifications": true, "bus_phone": "+31683138539", "company_industry": null, "company_size": null, "currency_code": "EUR", "direct_link_token": null, "email": "[email protected]", "exceeds_client_limit": 0, "fax": "", "fname": "Melville", "has_retainer": null, "home_phone": "", "id": 220399, "language": "en", "last_activity": null, "last_login": null, "level": 0, "lname": "DMello", "mob_phone": "+31683138539", "note": null, "notified": false, "num_logins": 0, "organization": "Your Client B.V", "p_city": "", "p_code": "", "p_country": "Netherlands", "p_province": "", "p_street": "", "p_street2": "", "pref_email": true, "pref_gmail": false, "retainer_id": null, "role": "client", "s_city": "", "s_code": "", "s_country": "", "s_province": "", "s_street": "", "s_street2": "", "signup_date": "2021-10-18 09:19:05", "statement_token": null, "subdomain": null, "updated": "2021-11-05 13:56:17", "userid": 220399, "username": "melvilledmello", "uuid": "54cc2cb7-deed-4b05-8ef6-fe672efd2cb7", "vat_name": "VAT Number", "vat_number": "", "vis_state": 0 }, { "accounting_systemid": "LJArJ4", "allow_email_include_pdf": false, "allow_late_fees": true, "allow_late_notifications": true, "bus_phone": "", "company_industry": null, "company_size": null, "currency_code": "USD", "direct_link_token": null, "email": "", "exceeds_client_limit": 0, "fax": "", "fname": "Clay", "has_retainer": null, "home_phone": "1-311-784-0855 x4809", "id": 215927, "language": "en", "last_activity": null, "last_login": null, "level": 0, "lname": "Schmidt", "mob_phone": "", "note": "analyzing", "notified": false, "num_logins": 0, "organization": "Lehner - Lubowitz", "p_city": "", "p_code": "", "p_country": "", "p_province": "", "p_street": "Koch Isle", "p_street2": "", "pref_email": true, "pref_gmail": false, "retainer_id": null, "role": "client", "s_city": "", "s_code": "", "s_country": "", "s_province": "", "s_street": "", "s_street2": "", "signup_date": "2021-09-28 15:16:00", "statement_token": null, "subdomain": null, "updated": "2021-09-28 11:16:33", "userid": 215927, "username": "clayschmidt", "uuid": "f0495e6b-6a8b-4ce2-b136-c896d1566839", "vat_name": null, "vat_number": null, "vis_state": 0 } ], "page": 1, "pages": 1, "per_page": 15, "total": 2 } } }
Get Single Invoice
curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/invoices/invoices/<invoiceId>' \ -H 'Authorization: Bearer <insert-bearer-token>' #Response:{ "response": { "result": { "invoices": [ { "accountid": "LJArJ4", "accounting_systemid": "LJArJ4", "address": "", "amount": { "amount": "110.00", "code": "CAD" }, "auto_bill": false, "autobill_status": null, "basecampid": 0, "city": "", "code": "", "country": "Canada", "create_date": "2021-12-12", "created_at": "2021-12-12 02:10:41", "currency_code": "CAD", "current_organization": "First1 Last1", "customerid": 806, "date_paid": null, "deposit_amount": null, "deposit_percentage": null, "deposit_status": "none", "description": "", "discount_description": null, "discount_total": { "amount": "0.00", "code": "CAD" }, "discount_value": "0", "display_status": "sent", "dispute_status": null, "due_date": "2022-01-11", "due_offset_days": 30, "estimateid": 0, "ext_archive": 0, "fname": "First1", "fulfillment_date": "2021-12-12", "generation_date": "2021-12-12", "gmail": false, "id": 164410, "invoice_number": "0000052", "invoiceid": 164410, "language": "en", "last_order_status": null, "lname": "Last1", "net_paid_amount": { "amount": "0.00", "code": "CAD" }, "notes": "Recurring invoice", "organization": "First1 Last1", "outstanding": { "amount": "110.00", "code": "CAD" }, "ownerid": 1, "paid": { "amount": "0.00", "code": "CAD" }, "parent": 129, "payment_details": "", "payment_status": "unpaid", "po_number": null, "province": "", "return_uri": null, "sentid": 1, "show_attachments": true, "status": 2, "street": "", "street2": "", "template": "clean-grouped", "terms": "Please pay the invoice within 30 days", "updated": "2021-12-12 02:10:42", "uuid": "6c8c1a5d-374e-46ba-9606-2d7f01d3245b", "v3_status": "sent", "vat_name": null, "vat_number": "", "version": "2021-12-12 02:10:42.172917", "vis_state": 0 }, { "accountid": "LJArJ4", "accounting_systemid": "LJArJ4", "address": "", "amount": { "amount": "990.00", "code": "CAD" }, "auto_bill": false, "autobill_status": null, "basecampid": 0, "city": "", "code": "", "country": "Canada", "create_date": "2021-12-12", "created_at": "2021-12-12 02:10:41", "currency_code": "CAD", "current_organization": "First1 Last1", "customerid": 806, "date_paid": null, "deposit_amount": null, "deposit_percentage": null, "deposit_status": "none", "description": "", "discount_description": null, "discount_total": { "amount": "0.00", "code": "CAD" }, "discount_value": "0", "display_status": "sent", "dispute_status": null, "due_date": "2022-01-01", "due_offset_days": 20, "estimateid": 0, "ext_archive": 0, "fname": "First1", "fulfillment_date": "2021-12-12", "generation_date": "2021-12-12", "gmail": false, "id": 164409, "invoice_number": "0000051", "invoiceid": 164409, "language": "en", "last_order_status": null, "lname": "Last1", "net_paid_amount": { "amount": "0.00", "code": "CAD" }, "notes": "", "organization": "First1 Last1", "outstanding": { "amount": "990.00", "code": "CAD" }, "ownerid": 1, "paid": { "amount": "0.00", "code": "CAD" }, "parent": 130, "payment_details": "", "payment_status": "unpaid", "po_number": null, "province": "", "return_uri": null, "sentid": 1, "show_attachments": true, "status": 2, "street": "", "street2": "", "template": "clean-grouped", "terms": "Please pay the invoice within 20 days", "updated": "2021-12-12 02:10:41", "uuid": "efa7fc60-edee-4e8c-ba99-eee8d6a59a94", "v3_status": "overdue", "vat_name": null, "vat_number": "", "version": "2022-01-01 19:04:25.476748", "vis_state": 0 } ], "page": 1, "pages": 26, "per_page": 2, "total": 51 } } }
List Expenses
curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/expenses/expenses' \ -H 'Authorization: Bearer <insert-bearer-token>' #Response:{ "response": { "result": { "expenses": [ { "account_name": "", "accountid": null, "accounting_systemid": "LJArJ4", "amount": { "amount": "762.68", "code": "USD" }, "background_jobid": null, "bank_name": "", "bill_matches": [], "billable": false, "categoryid": 72311, "clientid": 0, "compounded_tax": false, "converse_projectid": null, "date": "2022-01-04", "expenseid": 7934236, "ext_accountid": null, "ext_invoiceid": 0, "ext_systemid": 0, "from_bulk_import": false, "has_receipt": false, "id": 7934236, "include_receipt": false, "invoiceid": null, "is_cogs": true, "isduplicate": false, "markup_percent": "0", "modern_projectid": null, "notes": "", "potential_bill_payment": false, "profileid": 1155, "projectid": 0, "staffid": 1, "status": 0, "taxAmount1": null, "taxAmount2": null, "taxName1": null, "taxName2": null, "taxPercent1": null, "taxPercent2": null, "transactionid": null, "updated": "2022-01-04 06:16:24", "vendor": null, "vis_state": 0 }, { "account_name": "", "accountid": null, "accounting_systemid": "LJArJ4", "amount": { "amount": "60.56", "code": "USD" }, "background_jobid": null, "bank_name": "", "bill_matches": [], "billable": false, "categoryid": 72293, "clientid": 0, "compounded_tax": false, "converse_projectid": null, "date": "2022-01-04", "expenseid": 7934237, "ext_accountid": null, "ext_invoiceid": 0, "ext_systemid": 0, "from_bulk_import": false, "has_receipt": false, "id": 7934237, "include_receipt": false, "invoiceid": null, "is_cogs": true, "isduplicate": false, "markup_percent": "0", "modern_projectid": null, "notes": "", "potential_bill_payment": false, "profileid": 1150, "projectid": 0, "staffid": 1, "status": 0, "taxAmount1": null, "taxAmount2": null, "taxName1": null, "taxName2": null, "taxPercent1": null, "taxPercent2": null, "transactionid": null, "updated": "2022-01-04 06:16:25", "vendor": null, "vis_state": 0 } ], "page": 1, "pages": 182, "per_page": 2, "total": 364 } } }
Sending Invoice
curl -X PUT 'https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<invoiceid>' \
-H 'Authorization: Bearer <bearer>' \
-H 'Content-Type: application/json' \
-d `{
"invoice": {
"email_subject": "Some Subject",
"email_body": "sample email body",
"action_email": true
}
}`