Log In 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.
In our documentation, the column on the right-hand side will have cURL calls that demonstrate the required Headers and general format of requests to the FreshBooks API.
Requests are authenticated using OAuth2 access 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. See our Authentication documentation or the Get Authenticated On The FreshBooks API tutorial for more information.
Check out our Scenarios and API Reference sections to see what to expect.
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.
Make a Test Call
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.
Test Call
Copy, paste, and run the command from the code pane on any Mac or Linux computer, or a Windows computer with cURL installed.
Getting Help
Our API Support Team is happy to assist if you’re stuck and need help. We can help with any API calls that involve FreshBooks endpoints as well as:
- Thinking through workflows
- Identifying errors that you might be receiving
- Understanding responses
Most of the examples in the API documentation use cURL, but if needed, you can use FreshBooks’ Postman Documentation to view all the documented calls in many different languages/formats.
You can reach the API Support Team at api@freshbooks.com. When reaching out to our team, please include the following information with your request:
- What went wrong, including any error codes or responses you’ve received
- What you’re aiming to accomplish
- What work you’ve done so far, including the API call (with headers), and the
account_idorbusiness_idyou’re working with
Join the FreshBooks Developer Community!
Stay connected to the latest with the FreshBooks API by joining our mailing list
Follow us on Twitter @ freshbooksdevs
Test Call
curl -X GET
-H 'Authorization: Bearer <insert-bearer-token>' \
-H "Api-Version: test-version" \
"https://api.freshbooks.com/test"
// to the line above this. You should get a response like below:
{
"version": "test-version",
"user": {
"first_name": "Bruce",
"last_name": "Wayne",
"email": "b@example.com"
}
}
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": "email1@freshbooks.com",
"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+2@freshbooks.com",
"fname": "first2",
"lname": "last2",
"phone1": null,
"userid": null,
"face": null
},
{
"email": "email+3@freshbooks.com",
"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": "email1@freshbooks.com",
"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": "lygel.dmello+Client@freshbooks.com",
"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
}
}
}