Skip to content
× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

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

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

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/&ltaccountid&gt/users/clients/&ltid&gt


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/&ltaccountid&gt/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/&ltaccountid&gt/users/clients/&ltid&gt


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/&ltaccountid&gt/users/clients/&ltid&gt


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/&ltaccountid&gt/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'}
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
    }
  }
}