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
If there’s no one around to help, we’ve got your back. Shoot us an email at api@freshbooks.com and tell us what you’re aiming to accomplish, what you’ve done so far, and what went wrong. Maybe we can find the missing piece of the puzzle together.
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
}
}
}