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 |
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 |
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 |
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 |
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 | 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": "[email protected]", "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": "[email protected]", "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 protected]", "fname": "first2", "lname": "last2", "phone1": null, "userid": null, "face": null }, { "email": "[email protected]", "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": "[email protected]", "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": "[email protected]", "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": "[email protected]", "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/
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": "[email protected]",
"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/
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': "[email protected]"
}
}
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": "[email protected]",
"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/
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': "[email protected]"
}
}
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": "[email protected]",
"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/
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/
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
}
}
}