Client API - API | FreshBooks

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

Access	Requires Authorization
Scopes	`user:clients:read` `user:clients:write`

Includes

Include	Description
outstanding_balance	include client’s outstanding balance
credit_balance	include client’s current balance of credit
draft_balance	include balance of draft invoices for client
overdue_balance	include overdue balance for the Client
grand_total_balance	include grand total for client
last_activity	include last activity
late_reminders	include information about late reminders
late_fee	include information about late fees

Searches / Filters

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

Name	Field	Filter Type	Description
address_like	address	Like	matches address fields containing the parameter
email	email	Equals	matches exact email
has_credit	special	Equals	no input, filters to clients with credit to apply
has_draft	special	Equals	no input, filters to clients with draft invoices
has_outstanding	special	Equals	no input, filters to clients with outstanding invoices
has_overdue	special	Equals	no input, filters to clients with overdue invoices
fname_like	fname	Like	matches first names containing the parameter
lname_like	lname	Like	matches last names containing the parameter
note_like	note	Like	matches notes containing the parameter
organization _like	organization	Like	matches organizations containing the parameter
phone_like	special	Like	matches mobile phone, home phone, business, phone, or fax containing the parameter
updated_min	updated	Between	updated date greater than or equal to parameter, YYYY-MM-DD format
updated_max	updated	Between	updated date less than parameter, YYYY-MM-DD format
user_like	special	Like	matches fname, lname, or organization containing the parameter
userid	userid	Equals	matches exact userid
userids	userid	In	matches list of userids, one specified per query arginput several userids to be matched
username	username	Equals	matches username exactly
vis_state	vis_state	Equals	matches vis_state exactly
email_like	email	Like	matches client’s email addresses containing the parameter

Sort Fields

Sort Field	Description
client_id	Sort by the id of the clients
organization_name	Sort by the name of the client organizations alphabetically
email	Sort by the email of the clients
bus_phone	Sort by the business phone number of the clients
updated	Sort by the time the clients were last updated at
fullname	Sort by the last name followed by the first name of the clients (eg. Jim Ayers, Alex Cass, Ben Cass)
primarycontact	Sort by the first name followed by the last name of the clients (eg. Alex Ayers, Alex Cass, Justin Lee)
outstanding	Sort by the outstanding invoice amounts of the clients
overdue	Sort by the overdue invoice amounts of the clients
credit	Sort by the total credit amounts of the clients

Field Descriptions

field	type	description
accounting _systemid	string	unique identifier of business client exists on
allow_late_fees	bool	deprecated
allow_late _notifications	bool	deprecated
bus_phone	string	business phone number
company_industry	string	description of industry client is in
company_size	string	size of client’s company
currency_code	string	3-letter shortcode for preferred currency
direct_link_token	string	deprecated
email	string	email
fax	string	fax number
fname	string	first name
home_phone	string	home phone number
id	int	unique to this business id for client
language	string	shortcode indicating user language e.g. “en”
last_activity	string	last client activity action
last_login	datetime	last login time
level	int	deprecated: indication of access level on system
lname	string	last name
mob_phone	string	mobile phone number
note	string	notes kept by admin about client
notified	bool	deprecated
num_logins	int	number of logins
organization	string	name for client’s business
p_city	string	billing city
p_code	string	billing postal code
p_country	string	billing country
p_province	string	billing province
p_street	string	billing street address
p_street2	string	billing street address second part
pref_email	bool	prefers email over ground mail
pref_gmail	bool	prefers ground mail over email
s_city	string	shipping address city
s_code	string	shipping postal code
s_country	string	shipping country
s_province	string	short form for province
s_street	string	shipping street address
s_street2	string	shipping address second street info
signup_date	datetime	time of user signup
statement_token	string	deprecated
subdomain	string	unused in the new FreshBooks
updated	datetime	time of last modification to resource
userid	int	duplicate of id
username	string	deprecated: username used by the client to log into FreshBooks Classic
vat_name	string	Value Added Tax name
vat_number	string	Value Added Tax number
vis_state	int	“visibility state”, active, deleted, or archived

Get Single Client

curl -L -X GET 'https://api.freshbooks.com/accounting/account//users/clients/' \
-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//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//users/clients/' \
-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//users/clients/' \
-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//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//users/clients/


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/clients/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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//users/clients


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/clients"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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//users/clients/


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/clients/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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//users/clients/


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/clients/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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//users/client


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/clients"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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
    }
  }
}