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

Staff

General Info

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.

*Requires Authorization*

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": "staff@freshbooks.com",
        "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!

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.

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

{
    "staff": {
        "email": "john.doe@abcorp.com",
        "fname": "John",
        "lname": "Doe"
    }
}

Response:

{
  "response": {
    "result": {
      "staff": {
        "fax": "",
        "rate": null,
        "num_logins": 0,
        "api_token": null,
        "id": 2325586,
        "note": null,
        "display_name": null,
        "lname": "Doe",
        "mob_phone": "",
        "last_login": null,
        "home_phone": null,
        "email": "john.doe@abcorp.com",
        "username": "johndoe2",
        "updated": "2016-09-29 19:10:25",
        "p_province": "",
        "p_city": "",
        "p_code": "",
        "p_country": "",
        "accounting_systemid": "zDmNq",
        "bus_phone": "",
        "signup_date": "2016-09-29 23:10:26",
        "language": "en",
        "level": 1,
        "userid": 2325586,
        "p_street2": "",
        "vis_state": 0,
        "fname": "John",
        "organization": "",
        "p_street": "",
        "currency_code": null
      }
    }
  }
}

Update Single Staff

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

{
  "staff": {
    "email": "test@test.test"
  }
}

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": "test@test.test",
        "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>

{
  "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": "staff@freshbooks.com",
        "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!

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.

Request: POST
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'}
payload = {
  "staff": { 
    "email": "john.doe@abcorp.com",
    "fname": "John",
    "lname": "Doe"
  }
}
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response:


{
  "response": {
    "result": {
      "staff": {
        "fax": "",
        "rate": null,
        "num_logins": 0,
        "api_token": null,
        "id": 2325586,
        "note": null,
        "display_name": null,
        "lname": "Doe",
        "mob_phone": "",
        "last_login": null,
        "home_phone": null,
        "email": "john.doe@abcorp.com",
        "username": "johndoe2",
        "updated": "2016-09-29 19:10:25",
        "p_province": "",
        "p_city": "",
        "p_code": "",
        "p_country": "",
        "accounting_systemid": "zDmNq",
        "bus_phone": "",
        "signup_date": "2016-09-29 23:10:26",
        "language": "en",
        "level": 1,
        "userid": 2325586,
        "p_street2": "",
        "vis_state": 0,
        "fname": "John",
        "organization": "",
        "p_street": "",
        "currency_code": null
      }
    }
  }
}

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": "test@test.test"
  }
}
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
        }
      ]
    }
  }
}