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.
*Requires Authorization*
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
/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 |
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 | Like | 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 |
string | ||
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 | deprectated: username used by client to log into FreshBooks Classic |
vat_name | string | Value Added Tax name |
vat_number | int | Value Added Tax number |
vis_state | int | "visibility state", active, deleted, or archived |
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"
}
}
} }
Error Response When Exceeding Client Limit – 402 Payment Required:
{
"response": {
"errors": [
{
"errno": 7005,
"field": null,
"message": "Client limit of 2 reached",
"object": null,
"value": null
}
]
}
}
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
}
}
}