×
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.

Includes

Include NameDescription
projectidsinclude related projectids in staff

Filters

Filter TypeNameFieldDescription
Equalsuseriduseridmatches exact userid
Inuseridsuseridmatches list of userids, one specified per query arg
Exactuser_levelsspecialexact match for 'admin' or 'staff' to filter for that type of user
Likeuser_likespecialmatches staff with lname, fname, or organization containing parameter
Likenote_likenotenote containing the parameter
PhoneLikephone_likeNonephone number containing the parameter
Likeemail_likeemailemail containing the parameter

Field Descriptions

FieldTypeDescription
faxstringfax number
ratedecimalrate this staff is billed at
num_loginsinthow many times staff has logged in
api_tokenstringtoken used for deprecated FreshBooks Classic API
idintunique to this business id for staff
notestringnotes about staff
display_namestringname chosen by staff member to display
lnamestringlast name
mob_phonestringmobile phone number
last_logindatetimedate staff account was last logged in to, YYYY-MM-DD HH:MM:SS format
home_phonestringhome phone number
emailstringemail address for staff
usernamestringusername for staff; randomly assigned if none specified at creation time
updateddatetimedate staff object was last updated, YYYY-MM-DD HH:MM:SS format
p_provincestringbilling address province
p_citystringbilling address city
p_codestringbilling address zip code
p_countrystringbilling address country
accounting _systemidstringunique identifier of business staff exists on
bus_phonestringbusiness phone number
signup_datedatetimedate staff account was created, YYYY-MM-DD HH:MM:SS format
languagestringstaff's selected language
levelintdeprecated description of access level
useridintduplicate of id
p_street2stringbilling address secondary street info
vis_stateint"visibility state", active, deleted, or archived
fnamestringfirst name
organizationstringorganization staff member is affiliated with
p_streetstringbilling address primary street info
currency_codestring3-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": {}
}

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