Clients

General Info

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, but email also uniquely identifies clients in each of your businesses.

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 client
grand_total_balance	include grand total for client
last_activity	include last activity time
late_reminders	include information about late reminders
late_fee	include information about late fees

Searches / Filters

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

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	datetime	time of last client activity
last_login	string	last login time
level	int	deprectated: 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	username used by client to log in
vat_name	string	Value Added Tax name
vat_number	int	Value Added Tax number
vis_state	int	"visibility state", active, deleted, or archived

curl Python

Get Single Client

Request: GET https://api.freshbooks.com/accounting/account/<accountid>/users/clients/<id>

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

{
    "client": {
        "email": "john.doe@abcorp.com"
    }
}

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/<id>

{
    "client": {
        "email": "john.doe@abcorp.com"
    }
}

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/<id>

{
    "client": {
        "vis_state": 1
    }
}

Response:

{
  "response": {}
}

List Clients

Request: GET https://api.freshbooks.com/accounting/account/<accountid>/users/clients

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

Get Single Client

Request: GET
https://api.freshbooks.com/accounting/account/<accountid>/users/clients/<id>


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/<id>


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/<id>


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/clients


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