× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:
Buy Now & Save Login
Buy Now & Save Try It Free Login
Login Buy Now & Save Try It Free Login
Introduction Postman Collection Tools and Libraries Social Login
Authentication Scopes Identity Model
Search, Paging and Includes Active, Archived, and Deleted Errors Request Limits How to create your FreshBooks app listing
Get Authenticated On The FreshBooks API How To Find The Right Scopes For Your App Getting Started with FreshBooks NodeJS SDK Receive Online Payments with Checkout API Enabling Online Payments On An Invoice
Bearer tokens replaced with JWT tokens
Clients Path 413 Created with Sketch.
Clients Update Secondary Contacts Credits
Invoices Invoice Profiles Invoice Presentation and Attachments Payments Online Payments Other Income Taxes
Expenses Expense Categories Expense Attachments Bill Vendors (beta) Bills (beta) Bill Payments (beta)
Estimates
Time Entries
Services Projects
Team Members Staff
Reports
Journal Entries
Webhook Callbacks
Gateways Items Systems Tasks

Introduction to the Clients API

A client in the new FreshBooks is a resource representing an entity you send invoices to

The primary identifier of a client is an automatically assigned positive integer id (not the email address)

Access Requirements

AccessRequires Authorization
Scopesuser:clients:read
user:clients:write

Includes

IncludeDescription
outstanding_balanceinclude client’s outstanding balance
credit_balanceinclude client’s current balance of credit
draft_balanceinclude balance of draft invoices for client
overdue_balanceinclude overdue balance for the Client
grand_total_balanceinclude grand total for client
last_activityinclude last activity
late_remindersinclude information about late reminders
late_feeinclude information about late fees

Searches / Filters

/accounting/account/<ACCOUNT_ID>/users/clients?search[%Name%]=<SEARCH_TERM> will search %Field% with the %Filter Type%

NameFieldFilter TypeDescription
address_likeaddressLikematches address fields containing the parameter
emailemailEqualsmatches exact email
has_creditspecialEqualsno input, filters to clients with credit to apply
has_draftspecialEqualsno input, filters to clients with draft invoices
has_outstandingspecialEqualsno input, filters to clients with outstanding invoices
has_overduespecialEqualsno input, filters to clients with overdue invoices
fname_likefnameLikematches first names containing the parameter
lname_likelnameLikematches last names containing the parameter
note_likenoteLikematches notes containing the parameter
organization _likeorganizationLikematches organizations containing the parameter
phone_likespecialLikematches mobile phone, home phone, business, phone, or fax containing the parameter
updated_minupdatedBetweenupdated date greater than or equal to parameter, YYYY-MM-DD format
updated_maxupdatedBetweenupdated date less than parameter, YYYY-MM-DD format
user_likespecialLikematches fname, lname, or organization containing the parameter
useriduseridEqualsmatches exact userid
useridsuseridInmatches list of userids, one specified per query arginput several userids to be matched
usernameusernameEqualsmatches username exactly
vis_statevis_stateEqualsmatches vis_state exactly
email_likeemailLikematches client’s email addresses containing the parameter

Sort Fields

Sort FieldDescription
client_idSort by the id of the clients
organization_nameSort by the name of the client organizations alphabetically
emailSort by the email of the clients
bus_phoneSort by the business phone number of the clients
updatedSort by the time the clients were last updated at
fullnameSort by the last name followed by the first name of the clients (eg. Jim Ayers, Alex Cass, Ben Cass)
primarycontactSort by the first name followed by the last name of the clients (eg. Alex Ayers, Alex Cass, Justin Lee)
outstandingSort by the outstanding invoice amounts of the clients
overdueSort by the overdue invoice amounts of the clients
creditSort by the total credit amounts of the clients

Field Descriptions

fieldtypedescription
accounting _systemidstringunique identifier of business client exists on
allow_late_feesbooldeprecated
allow_late _notificationsbooldeprecated
bus_phonestringbusiness phone number
company_industrystringdescription of industry client is in
company_sizestringsize of client’s company
currency_codestring3-letter shortcode for preferred currency
direct_link_tokenstringdeprecated
emailstringemail
faxstringfax number
fnamestringfirst name
home_phonestringhome phone number
idintunique to this business id for client
languagestringshortcode indicating user language e.g. “en”
last_activitystringlast client activity action
last_logindatetimelast login time
levelintdeprecated: indication of access level on system
lnamestringlast name
mob_phonestringmobile phone number
notestringnotes kept by admin about client
notifiedbooldeprecated
num_loginsintnumber of logins
organizationstringname for client’s business
p_citystringbilling city
p_codestringbilling postal code
p_countrystringbilling country
p_provincestringbilling province
p_streetstringbilling street address
p_street2stringbilling street address second part
pref_emailboolprefers email over ground mail
pref_gmailboolprefers ground mail over email
s_citystringshipping address city
s_codestringshipping postal code
s_countrystringshipping country
s_provincestringshort form for province
s_streetstringshipping street address
s_street2stringshipping address second street info
signup_datedatetimetime of user signup
statement_tokenstringdeprecated
subdomainstringunused in the new FreshBooks
updateddatetimetime of last modification to resource
useridintduplicate of id
usernamestringdeprecated: username used by the client to log into FreshBooks Classic
vat_namestringValue Added Tax name
vat_numberstringValue Added Tax number
vis_stateint“visibility state”, active, deleted, or archived
curl Python

Get Single Client

curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<customerId>' \
-H 'Authorization: Bearer <insert-bearer-token>' 


#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": 238951,
                "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:17:11",
                "statement_token": null,
                "subdomain": null,
                "updated": "2022-01-05 07:17:12",
                "userid": 238951,
                "username": "first1last13",
                "uuid": "366f3657-38ed-4cc1-832b-c3a8de9c8c16",
                "vat_name": null,
                "vat_number": "",
                "vis_state": 0
            }
        }
    }
}

Create 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
            }
        }
    }
}

Update Single Client

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<customerId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "client": {
        "fname": "Nicolas"
    }
}'

#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": "Nicolas",
                "has_retainer": null,
                "home_phone": null,
                "id": 238952,
                "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:17:17",
                "statement_token": null,
                "subdomain": null,
                "updated": "2022-01-07 07:38:56",
                "userid": 238952,
                "username": "first1last14",
                "uuid": "4d377c09-9dd9-4499-ade1-2895c1d9da86",
                "vat_name": null,
                "vat_number": "",
                "vis_state": 0
            }
        }
    }
}

Delete Single Client

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<customerId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "client": {
        "vis_state": 1
    }
}'


#Response:

{
  "response": {}
}

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 Client

Request: GET
"https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<customerId>"


url = "https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)


Response:


{
  "response": {
    "result": {
      "client": {
        "allow_late_notifications": true,
        "s_code": "2011",
        "fax": "",
        "last_activity": null,
        "num_logins": 0,
        "vat_number": null,
        "pref_email": true,
        "id": 1831231,
        "direct_link_token": null,
        "s_province": "NSW",
        "vat_name": null,
        "lname": "Gates",
        "s_city": "North Sydney",
        "s_street2": "",
        "statement_token": null,
        "note": null,
        "mob_phone": "",
        "last_login": null,
        "home_phone": null,
        "company_industry": null,
        "subdomain": null,
        "email": "will@microsoft.com",
        "username": "aclient",
        "updated": "2016-08-12 14:54:15",
        "p_province": "NSW",
        "p_city": "North Sydney",
        "bus_phone": "0401225226",
        "allow_late_fees": true,
        "p_street": "12 Pacific Highway",
        "company_size": null,
        "accounting_systemid": "zDmNq",
        "p_code": "2011",
        "signup_date": "2016-03-09 17:42:11",
        "language": "en",
        "level": 0,
        "notified": false,
        "userid": 1831231,
        "p_street2": "",
        "pref_gmail": false,
        "vis_state": 0,
        "s_country": "Australia",
        "s_street": "12 Pacific Highway",
        "fname": "Wyatt",
        "organization": "Microsoft",
        "p_country": "Australia",
        "currency_code": "AUD"
      }
    }
  }
}

Create Single Client

Request: POST
"https://api.freshbooks.com/accounting/account/<accountId>/users/clients"


url = "https://api.freshbooks.com/accounting/account/<accountId>/users/clients"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'client': {
              'email': "john.doe@abcorp.com"
            }
          }
res = requests.post(url, data=json.dumps(payload), headers=headers)


Response:


{
  "response": {
    "result": {
      "client": {
        "allow_late_notifications": true,
        "s_code": "",
        "fax": "",
        "last_activity": null,
        "num_logins": 0,
        "vat_number": null,
        "pref_email": true,
        "id": 1831231,
        "direct_link_token": null,
        "s_province": "",
        "vat_name": null,
        "lname": "",
        "s_city": "",
        "s_street2": "",
        "statement_token": null,
        "note": null,
        "mob_phone": "",
        "last_login": null,
        "home_phone": null,
        "company_industry": null,
        "subdomain": null,
        "email": "john.doe@abcorp.com",
        "username": "aclient",
        "updated": "2016-08-12 14:54:15",
        "p_province": "",
        "p_city": "",
        "bus_phone": "",
        "allow_late_fees": true,
        "p_street": "",
        "company_size": null,
        "accounting_systemid": "zDmNq",
        "p_code": "2011",
        "signup_date": "2016-03-09 17:42:11",
        "language": "en",
        "level": 0,
        "notified": false,
        "userid": 1831231,
        "p_street2": "",
        "pref_gmail": false,
        "vis_state": 0,
        "s_country": "",
        "s_street": "",
        "fname": "",
        "organization": "",
        "p_country": "",
        "currency_code": "USD"
      }
    }
  }
}

Update Single Client

Request: PUT
"https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<customerId>"


url = "https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'client': {
              'email': "john.doe@abcorp.com"
            }
          }
res = requests.put(url, data=json.dumps(payload), headers=headers)


Response:


{
  "response": {
    "result": {
      "client": {
        "allow_late_notifications": true,
        "s_code": "",
        "fax": "",
        "last_activity": null,
        "num_logins": 0,
        "vat_number": null,
        "pref_email": true,
        "id": 1831231,
        "direct_link_token": null,
        "s_province": "",
        "vat_name": null,
        "lname": "",
        "s_city": "",
        "s_street2": "",
        "statement_token": null,
        "note": null,
        "mob_phone": "",
        "last_login": null,
        "home_phone": null,
        "company_industry": null,
        "subdomain": null,
        "email": "john.doe@abcorp.com",
        "username": "aclient",
        "updated": "2016-08-12 14:54:15",
        "p_province": "",
        "p_city": "",
        "bus_phone": "",
        "allow_late_fees": true,
        "p_street": "",
        "company_size": null,
        "accounting_systemid": "zDmNq",
        "p_code": "2011",
        "signup_date": "2016-03-09 17:42:11",
        "language": "en",
        "level": 0,
        "notified": false,
        "userid": 1831231,
        "p_street2": "",
        "pref_gmail": false,
        "vis_state": 0,
        "s_country": "",
        "s_street": "",
        "fname": "",
        "organization": "",
        "p_country": "",
        "currency_code": "USD"
      }
    }
  }
}

Delete Single Client

Request: PUT
"https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<customerId>"


url = "https://api.freshbooks.com/accounting/account/<accountId>/users/clients/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'client': {
              'vis_state': 1
            }
          }
res = requests.put(url, data=json.dumps(payload), headers=headers)


Response:


{
  "response": {}
}

List Clients

Request: GET
https://api.freshbooks.com/accounting/account/<accountId>/users/client


url = "https://api.freshbooks.com/accounting/account/<accountId>/users/clients"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)


Response:


{
  "response": {
    "result": {
      "per_page": 15,
      "total": 3,
      "page": 1,
      "clients": [
        {
          // same format as single client
        },
        {
          // same format as single client
        },
        {
          // same format as single client
        }
      ],
      "pages": 1
    }
  }
}