×
Freshbooks
Official App
Free – Google Play
Get it

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

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 client
grand_total_balanceinclude grand total for client
last_activityinclude last activity time
late_remindersinclude information about late reminders
late_feeinclude information about late fees

Searches / Filters

Filter TypeNameFieldDescription
Likeaddress_likeaddressmatches address fields containing the parameter
Equalsemailemailmatches exact email
Equalshas_creditspecialno input, filters to clients with credit to apply
Equalshas_draftspecialno input, filters to clients with draft invoices
Equalshas_outstandingspecialno input, filters to clients with outstanding invoices
Equalshas_overduespecialno input, filters to clients with overdue invoices
Likefname_likefnamematches first names containing the parameter
Likelname_likelnamematches last names containing the parameter
Likenote_likenotematches notes containing the parameter
Likeorganization _likeorganizationmatches organizations containing the parameter
Likephone_likespecialmatches mobile phone, home phone, business, phone, or fax containing the parameter
Betweenupdated_minupdatedupdated date greater than or equal to parameter, YYYY-MM-DD format
Betweenupdated_maxupdatedupdated date less than parameter, YYYY-MM-DD format
Likeuser_likespecialmatches fname, lname, or organization containing the parameter
Equalsuseriduseridmatches exact userid
Inuseridsuseridmatches list of userids, one specified per query arginput several userids to be matched
Equalsusernameusernamematches username exactly
Equalsvis_statevis_statematches vis_state exactly
Likeemail_likeemailmatches 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_activitydatetimetime of last client activity
last_loginstringlast login time
levelintdeprectated: 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
usernamestringusername used by client to log in
vat_namestringValue Added Tax name
vat_numberintValue 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": {}
}

Update Single Client

Request: PUT https://api.freshbooks.com/accounting/account/<accountid>/users/clients/<id>
{
    "client": {
        "email": "john.doe@abcorp.com"
    }
}
Response:
{
  "response": {}
}

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