;
api login

BigTime's staff api provides access to the list of users in the system.

Getting a listing of Staff
try it
  • Click the GET button below to view the information returned by this url.

  • Get

By submitting a simple query to this api, you'll get a listing of staffer data (we return the "simple" view on the listings page). No additional parameters are required/supported.
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff?{ShowInactive=true}
HTTP RESPONSE:  (array of Staff objects ("basic" view -- see below for details)

Pulling the detail for a specific staffer.
try it
  • Get

You can use a simple GET request to pull the details associated with a single entry. Note that the BASIC view fields will be returned by default. You should also note that a user cannot pull data for an entity they are not permitted to view in the BigTime program. This can often become a problem when back-end services are using the api without system-wide permissions.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/detail/{systemid}?&View={Detailed/Basic}
HTTP RESPONSE:  (Staff object -- see below for details)

Creating a NEW staffer.
try it
  • Post

Note that only the fields listed in the Update view (below) should be included in your post to this url. Any other data will be ignored. BigTime doesn't care about the order in which field data is posted, and none of the fields are case sensitive. Note that any validation errors will return a 400 error, and an invalid permission will return a 405 (eg - attempting to create a staffer when you don't have that right).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/add/?inviteUser={true/false}
HTTP RESPONSE:  (Staff object -- see below for details)

Staffer Custom Fields

By submitting a simple query to this api, you'll get a list of custom fields for a specific staffer.

Getting a list of staffer custom fields.

You can use a GET request to pull the list of custom fields for a specific staffer. Note that a user cannot pull staffer custom field data for a staffer they are not permitted to view in the BigTime program. This can often become a problem when back-end services are using the api without system-wide permissions. No additional parameters are required/supported.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /staff/UDFList/{sid}
HTTP RESPONSE:  (array of Staffer Custom Field objects -- see below for details)

Getting a list of staffer custom fields by field name.

You can use a POST request to pull a list of custom fields with a specific field name. If you decide to not specify a field name or pass an empty list, the below query will return a full list of custom fields for all your staffers. Note that a user cannot pull staffer custom field data for a staffer they are not permitted to view in the BigTime program. This can often become a problem when back-end services are using the api without system-wide permissions. No additional parameters are required/supported.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /staff/UDFListByName
POST CONTENT:
[
	"Custom Field Name 1",
	"Custom Field Name 2",
	..
]
HTTP RESPONSE:  (array of Staffer Custom Field objects -- see below for details)

Updating existing custom fields on a staffer.

You can use a POST request to update an existing staffer's custom field list. To do this, POST to this URL with the staffer SID and a JSON array of Staffer Custom Fields objects. Your staffer's custom fields will be set according to the JSON array passed to this URL. Note again, validation errors will return a 400 error, and an invalid permission will return a 405.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /staff/UDFList/{sid}
POST CONTENT:
{  
   "UDFList":[  
      {  
         "Sid":6789,
         "Value":"0"
      },
      {  
         "Sid":6790,
         "Value":"1"
      }, 
	  ...
   ]
}
HTTP RESPONSE:  (updated array of Staffer Custom Field objects -- see below for details)

Staff: Field Details

For each of the operations listed above, you will post or "get" one or more staff objects. The list below is a complete catalog of fields available through the api (including the views within which those fields are found). Take special note of the AddUpdate and Update views. Required fields are flagged with an "*" character, and fields marked with a "!" character require the ViewPersonalData permit type to view and update.

FieldTypeDescriptionView(s)
StaffSid Integer Unique SID code for this record. Basic, Detailed, Update*
FName String First (given) name. Basic, Detailed, Update
SName String Last (family) name. Basic, Detailed, AddUpdate*
Title String Business title/position Basic, Detailed, Update
ManagerID Integer The StaffSid of the staffer's manager Basic, Detailed, Update
Address Address** The address object attached to this contact (see details below). Basic, Detailed, Update!
EMail String Primary email address Basic, Detailed, AddUpdate*!
Phone_Cell String Primary phone number Basic, Detailed, Update!
Phone_Wk String Additional phone Basic, Detailed, Update!
Phone_Hm String Additional phone Basic, Detailed, Update!
Notes String Free form notes field Basic, Detailed, Update
IsInactive True/False Inactive stafferss have this value set to TRUE. Basic, Detailed, Update
Status Integer The status code controls the specific reason behind a staffer's deactivation (eg - on-leave, terminated). The available values for this list are controlled by the administrator in BigTime's settings section. Detailed,AddUpdate
Start_dt Date Start date for the staff member (defaults to today if a staffer is created without one). Detailed,AddUpdate
Term_dt Date When a staffer is terminated, this date contains the date it is closed "as of." Detailed,AddUpdate
UsePayrollItem Integer TRUE if payroll item data should be posted to the accouting system (QuickBooks or Xero specifically) when BigTime posts timesheet data. Detailed, Update
Capacity Integer We track total 'available' hours per staffer so that we can track utilization. This field will return the total hours this staffer has in a "typical" month (eg - 20 days). Most firms set this number between 140 and 160 by default. Simple,Detailed,AddUpdate
CostFactor Numeric Detailed,AddUpdate
HourRateType Integer Detailed,AddUpdate
Rate1 Integer Staff billing rate (there can be up to 5 billing rates assigned to each staff member and customer's can be assiged "staff rate" 1-5 as their base rate). Detailed,AddUpdate
Rate2 Integer Staff billing rate (there can be up to 5 billing rates assigned to each staff member and customer's can be assiged "staff rate" 1-5 as their base rate). Detailed,AddUpdate
Rate3 Integer Staff billing rate (there can be up to 5 billing rates assigned to each staff member and customer's can be assiged "staff rate" 1-5 as their base rate). Detailed,AddUpdate
Rate4 Integer Staff billing rate (there can be up to 5 billing rates assigned to each staff member and customer's can be assiged "staff rate" 1-5 as their base rate). Detailed,AddUpdate
Rate5 Integer Staff billing rate (there can be up to 5 billing rates assigned to each staff member and customer's can be assiged "staff rate" 1-5 as their base rate). Detailed,AddUpdate
StaffOrgId Integer Detailed,AddUpdate
StaffType Integer Detailed,AddUpdate
HomeTimezone String The staffer's home timezone (see picklist/timezones for possible values). Note that this can be blank if the staffer's home timezone is the same as the firm's. Detailed,AddUpdate
DtCreated Date UTC Date that the staffer was created in the system. Basic, Detailed
DtModified Date UTC Date that the staffer was last modified by anyone (including external systems like QuickBooks or Xero). Basic, Detailed, Update
SecurityGroup Integer ID of Security Group you want staffer to be assigned. Security Groups and their corresponding ID can be pulled from /picklist/FieldValues/SecurityGroups endpoint. Please see the Picklists section of the API documentation for more details. AddUpdate
DefaultRole Integer ID of the Project Team Role you want the staffer to be assigned to. Project Team Roles and their corresponding ID can be pulled from /picklist/FieldValues/LookupProjectTeamRoles endpoint. Please see the Picklists section of the API documentation for more details. Basic, Detailed, Update
UdfList Udfs** A list of custom fields defined on the staffer. Detailed
SSN String A staffer's social security number. This value is encrypted. !
Salary Numeric A staffer's salary. This value is encrypted. !
PostTimeAsBilled Boolean Set TRUE if a Staffer is set to create their time into a Vendor bill. Detailed
Address Object Field Details

FieldTypeDescriptionView(s)
Id Integer Unique SID code for this record. Note that this value is an attribute on the main Address object if you are downloading xml. Basic, Detailed, Update*
Address String Street address (can be multi-line) Basic, Detailed, Update
City String Basic, Detailed, Update
State String State, Province or county (depending on the address' country of origin) Basic, Detailed, Update
Zip String Postal code Basic, Detailed, Update
Country String Country of origin. Basic, Detailed, Update
Staffer Custom Field Object Details

FieldTypeDescriptionView(s)
Sid Integer Unique SID for the Custom Field. Basic, Detailed, Update*
Name String Name of the Custom Field. Basic, Detailed
Value String Value of the Custom Field. Basic, Detailed, Update*