× Freshbooks App Logo
FreshBooks
Official App
Free - Google Play
Get it

If you’re using FreshBooks Classic, click here.

Classic FreshBooks invoice
Getting Started
Introduction Postman Collection Tools and Libraries How to migrate from the Classic XML API
Scenarios and Concepts
Make a Test Call Errors Search, Paging and Includes Active and Deleted Request Limits
Tutorials
Authenticating with OAuth 2.0 Enabling Online Payments On An Invoice Receive Online Payments with Checkout API Credit Card Tokenization
Authorization
Authentication Business, Roles, and Identities Identity Model
Clients
Clients Update Secondary Contacts Credits
Invoices
Online Payments Invoices Invoice Profiles Other Income Payments API Taxes
Expenses
Expense Expense Categories
Estimates
Estimates
Time Tracking
Time Entries
Projects
Services Projects
My Team
Staff Users
Reports
Reports
Accounting
Journal Entries
Uploader
Uploader
Webhooks
Webhook Callbacks
Settings
Gateways Items Systems Tasks API
Dev Blog
Accounting API For Reporting Other Income

Clients

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

*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
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
email email 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 email 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
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 string last client activity action
last_login datetime 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 string 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"
      }
    }
  } }

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