Staff

Staff are your employees.

Notice: Do not Create Staff Here!

Staff created via this endpoint are only Accounting representations of the staff members of your business, for the purpose of ownership of invoices, expenses, etc. Staff created here will not be able to log in or work with you.

To create staff members for actual use (which will also create them in sync here), please use the Staff Invitation flow in the new FreshBooks’ web interface.

Access Requirements

Access	Requires Authorization
Scopes	`user:teams:read`

Includes

Include Name	Description
projectids	include related projectids in staff

Filters

Filter Type	Name	Field	Description
Equals	userid	userid	matches exact userid
In	userids	userid	matches list of userids, one specified per query arg
Exact	user_levels	special	exact match for ‘admin’ or ‘staff’ to filter for that type of user
Like	user_like	special	matches staff with lname, fname, or organization containing parameter
Like	note_like	note	note containing the parameter
PhoneLike	phone_like	None	phone number containing the parameter
Like	email_like	email	email containing the parameter

Field Descriptions

underlined fields are required on creation

Field	Type	Description
fax	string	fax number
rate	decimal	rate this staff is billed at
num_logins	int	how many times staff has logged in
api_token	string	token used for deprecated FreshBooks Classic API
id	int	unique to this business id for staff
note	string	notes about staff
display_name	string	name chosen by staff member to display
lname	string	last name
mob_phone	string	mobile phone number
last_login	datetime	date staff account was last logged in to, YYYY-MM-DD HH:MM:SS format
home_phone	string	home phone number
email	string	email address for staff
username	string	username for staff; randomly assigned if none specified at creation time
updated	datetime	date staff object was last updated, YYYY-MM-DD HH:MM:SS format
p_province	string	billing address province
p_city	string	billing address city
p_code	string	billing address zip code
p_country	string	billing address country
accounting _systemid	string	unique identifier of business staff exists on
bus_phone	string	business phone number
signup_date	datetime	date staff account was created, YYYY-MM-DD HH:MM:SS format
language	string	staff’s selected language
level	int	deprecated description of access level
userid	int	duplicate of id
p_street2	string	billing address secondary street info
vis_state	int	“visibility state”, active, deleted, or archived
fname	string	first name
organization	string	organization staff member is affiliated with
p_street	string	billing address primary street info
currency_code	string	3-letter shortcode for preferred currency

Get Single Staff

Request: GET https://api.freshbooks.com/accounting/account/<accountid>/users/staffs/<id>

Response:

{
  "response": {
    "result": {
      "staff": {
        "fax": "",
        "rate": null,
        "num_logins": 0,
        "api_token": null,
        "id": 2194844,
        "note": null,
        "display_name": "",
        "lname": "",
        "mob_phone": "",
        "last_login": "2016-08-05 10:38:41",
        "home_phone": null,
        "email": "[email protected]",
        "username": "MHzxqDerKq",
        "updated": "2016-08-05 10:38:41",
        "p_province": "",
        "p_city": "",
        "p_code": "",
        "p_country": "",
        "accounting_systemid": "KAG77",
        "bus_phone": "",
        "signup_date": "2016-08-05 10:38:41",
        "language": "en",
        "level": 1,
        "userid": 2194844,
        "p_street2": "",
        "vis_state": 0,
        "fname": "",
        "organization": "",
        "p_street": "",
        "currency_code": null
      },
    }
  }
}

Create Single Staff (deprecated)

Create

Do not create Staff using this endpoint!

To create staff members for actual use (which will also create them in sync here), please use the Staff Invitation flow in the new FreshBooks’ web interface.

Update Single Staff

Request: PUT https://api.freshbooks.com/accounting/account/<accountid>/users/staffs/<id>

{
  "staff": {
    "email": "[email protected]"
  }
}

Response:

{
  "response": {
    "result": {
      "staff": {
        "fax": "",
        "rate": null,
        "num_logins": 0,
        "api_token": null,
        "id": 2194844,
        "note": null,
        "display_name": "",
        "lname": "",
        "mob_phone": "",
        "last_login": "2016-08-05 10:38:41",
        "home_phone": null,
        "email": "[email protected]",
        "username": "MHzxqDerKq",
        "updated": "2016-08-05 10:38:41",
        "p_province": "",
        "p_city": "",
        "p_code": "",
        "p_country": "",
        "accounting_systemid": "KAG77",
        "bus_phone": "",
        "signup_date": "2016-08-05 10:38:41",
        "language": "en",
        "level": 1,
        "userid": 2194844,
        "p_street2": "",
        "vis_state": 0,
        "fname": "",
        "organization": "",
        "p_street": "",
        "currency_code": null
      },
    }
  }
}

Delete Single Staff

Request: PUT https://api.freshbooks.com/accounting/account/<accountid>/users/staffs/<id>

{
  "staff": {
    "vis_state": 1
  }
}

Response:

{
  "response": {}
}

List Staff

Request: GET https://api.freshbooks.com/accounting/account/<accountid>/users/staffs

Response:

{
  "response": {
    "result": {
      "per_page": 15,
      "pages": 1,
      "total": 3,
      "page": 1,
      "staff": [
        {
          // same format as single staff
        },
        {
          // same format as single staff
        },
        {
          // same format as single staff
        }
      ]
    }
  }
}

Get Single Staff

Request: GET
https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs/&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": {
      "staff": {
        "fax": "",
        "rate": null,
        "num_logins": 0,
        "api_token": null,
        "id": 2194844,
        "note": null,
        "display_name": "",
        "lname": "",
        "mob_phone": "",
        "last_login": "2016-08-05 10:38:41",
        "home_phone": null,
        "email": "[email protected]",
        "username": "MHzxqDerKq",
        "updated": "2016-08-05 10:38:41",
        "p_province": "",
        "p_city": "",
        "p_code": "",
        "p_country": "",
        "accounting_systemid": "KAG77",
        "bus_phone": "",
        "signup_date": "2016-08-05 10:38:41",
        "language": "en",
        "level": 1,
        "userid": 2194844,
        "p_street2": "",
        "vis_state": 0,
        "fname": "",
        "organization": "",
        "p_street": "",
        "currency_code": null
      },
    }
  }
}

Create Single Staff(deprecated)

Do not create staff using this endpoint!

To create staff members for actual use (which will also create them in sync here), please use the staff invitation flow in the new FreshBooks’ web interface.

Update Single Staff

Request: PUT
https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
  "staff": {
    "email": "[email protected]"
  }
}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Delete Single Staff

Request: PUT
https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
  "vis_state": 1
}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Response:


{
  "response": {}
}

List Staff

Request: GET
https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/users/staffs"
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,
      "pages": 1,
      "total": 3,
      "page": 1,
      "staff": [
        {
          // same format as single staff
        },
        {
          // same format as single staff
        },
        {
          // same format as single staff
        }
      ]
    }
  }
}