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

If you’re using FreshBooks Classic, click here.

Classic FreshBooks invoice
Setup
Introduction Postman Collection
Scenarios and Concepts
Make a Test Call Errors Search, Paging and Includes Active and Deleted Request Limits
Authorization
Authentication Business, Roles, and Identities Identity Model
Clients
Clients Update Secondary Contacts
Invoices
Invoices Invoice Profiles Other Income Payments Taxes
Expenses
Expenses Expense Categories
Estimates
Estimates
Time Tracking
Time Entries
Projects
Projects Tasks
My Team
Staff Users
Reports
Reports
Accounting
Journal Entries
Uploader
Uploader
Webhooks
Webhooks
Settings
Gateways Items and Services Systems

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

Filter Type Name Field Description
Like address_like address matches address fields containing the parameter
Equals email email matches exact email
Equals has_credit special no input, filters to clients with credit to apply
Equals has_draft special no input, filters to clients with draft invoices
Equals has_outstanding special no input, filters to clients with outstanding invoices
Equals has_overdue special no input, filters to clients with overdue invoices
Like fname_like fname matches first names containing the parameter
Like lname_like lname matches last names containing the parameter
Like note_like note matches notes containing the parameter
Like organization _like organization matches organizations containing the parameter
Like phone_like special matches mobile phone, home phone, business, phone, or fax containing the parameter
Between updated_min updated updated date greater than or equal to parameter, YYYY-MM-DD format
Between updated_max updated updated date less than parameter, YYYY-MM-DD format
Like user_like special matches fname, lname, or organization containing the parameter
Equals userid userid matches exact userid
In userids userid matches list of userids, one specified per query arginput several userids to be matched
Equals username username matches username exactly
Equals vis_state vis_state matches vis_state exactly
Like email_like email 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 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 username used by client to log in
vat_name string Value Added Tax name
vat_number int 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
    }
  }
}