;
api login

Pulling every project in the system (or every task) is a time consuming process. The picklist api provides a simple way to get a simple id+name listing of elements in the system that you may use elsewhere (eg - in time or expense entries). Take a look at the options below to see the types of simple lists BigTime's api will return.

Note that the picklist api is a 'read-only' api. To change these values, you'll need to use one of the detailed api's below (eg - project, client or task "updates"). In addition, the picklist api has been designed to return only the items that the currently logged in user is allowed to see (eg - your project list will contain ONLY the projects that this currently logged in user can view in their timesheet).

Making PickList API Calls

The compelte list of picklist REST url's is listed at the bottom of this article, but calling them works the same no matter which url you are pointing at. In each case, you'll make a GET request to the url and the data you get back with be in the same basic "ID+NAME" format. Below is a simple example (calling the ProjectList api).

headers X-Auth-Token:{your api token} ; X-Auth-Realm: {your api realm}
HTTP GET /picklist/projects
RESULT [{id:123, name:"Allstate Corporation"}, {id:456, name:"ABC Company"}, ...]

Note that results are returned in sorted order (based on the system defaults), and that they are limited to the items that the logged in user has rights to see. Inactive/Completed items are not included.

URLOptionsResults/Notes
/picklist/projects staffsid Returns a list of projects the specified user has rights to log time against. If an alternative staffsid is specified, then the logged in user will need admin rights in order to see the alternate user's data.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ clients Returns a list of customers records for the system (note that we log time against project records, not customer records. When you log time against a project, the clientid is filled in automatically). If the user is not a project admin, then a 405 error is returned instead of a client list.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ staff Returns a list of staffers that exist in a firm. Note that the user must have admin rights (specifically StaffAdmin rights) in order to view this list (Otherwise, the call will return a 405 error).
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ LaborCodes staffsid Returns a list of active labor codes against which time can be logged for the user specified. If an alternative staffsid is specified, then the logged in user will need admin rights in order to see the alternate user's data.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ ExpenseCodes staffsid Returns a list of active expense codes against which expenses can be logged. Note that the expense code list returns more than simply Id+Name. It also returns some supporting informations that you may need if you intend to log expenses via the API.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
FieldTypeDescription
IsUnitBoolTRUE if expenses against this category should be entered per UNIT.
UnitOfMeasureStringIf IsUnit is true, then this field contains the name of the PER UNIT entry (eg- "miles" for mileage).
CostRateNumericThe rate at which reimbursements are to be calculated for a per unit expense (eg - if I enter 100 "miles" at .58/mile, then my expense reimbursement is $58.00).
NtStringNote/Description of the category.
IsTaxableBoolTRUE if sales tax is collected on this item (not used for US firms, but global firms need to track taxes on expenses logged via BigTime).
TaxRateSidIntIf an item is taxable, what is the default tax rate used for it.
SalesRateNumericFor invoicing, the rate at which an item will be billed through to customers. Not used for expense entry
/picklist/ AllTasksByProject/ {projectid} BudgetType (fee/expense)
showInactive (t/f)
Returns a list of tasks/engagements linked to a specific project. Note that you must have rights to see the project id specified (or the system will return a 405 error). You have the option to return active or "all" tasks (and you can specify tasks budget type as well: FeeOnly, ExpenseOnly or FeeAndExpense
try it
  • Get
/picklist/ EstimatesByProject/ {projectid} staffsid
BudgetType (fee/expense)
showInactive (t/f)
This call is valid for BigTime enterprise customers only. It Returns a list of budget items linked to a specific project. Note that you must have rights to see the project id specified (or the system will return a 405 error). You have the option to return active or "all" budget items (and you can specify budget type as well: FeeOnly, ExpenseOnly or FeeAndExpense
/picklist/ QBClasses Some firms track time and expenses against QuickBooks classes. For convenience, you can pull a list of those class values using this url.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ PayrollItems staffsid If the firm uses BigTime to create payroll -- then they may ask users to log time against specific payroll items. A list of those items (filtered for the current user or the specified user) can be returned using this url. If an alternative staffsid is specified, then the logged in user will need admin rights in order to see the alternate user's data.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ CreditCards / {StaffSid} showAll If the firm has credit cards available for use, then this will return a list of credit cards that the current user has rights to see (note that credit cards can be restricted per user). If an alternative staffsid is specified, then the logged in user will need admin rights in order to see the alternate user's data.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ Timezones Returns a list of all of the valid timezone values for this firm. Can be used to set Timezone for a staffer or for the entire firm.
try it
  • Click the GET button below to view the information returned by this url.

  • Get
/picklist/ FieldValues / {FieldEnum} Throughout the system, BigTime presents field that are comprised of "lists of values" that the firm's administrative user controls. To get a list of acceptable values for each of those fields, you'll need to pull a FieldValues list from this section of the api. The data call expects a fieldType parameter, and the following values are accepted:
Lookup Values:
InvoiceType_subttl, rateTypeSimple, LookupStaffHourlyType, LookupStaffType, LookupClientType, LookupProjectType, LookupProjectTeamRoles, LookupContactType, StaffOrgList, StaffTeamList, CurrencyList, SecurityGroups
Status Values:
StatusProduction, StatusBilling, StatusStaff, StatusExpenseRpt
Invoicing/Related Values:
InvoiceTypes, InvoicePostTypes

try it
  • Get

Creating a NEW expense code.
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 an expense code when you don't have that right).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /picklist/ExpenseCode
POST CONTENT:  {  
   "CustomFields":[  
      {  
         "Nm":Travel Expense,
         "Code":1234,
         "Desc":Expenses for everything travel related
		...
      },
      {  
         "Nm":Meal Expense,
         "Code":1233,
         "Desc":Meals provided by the firm
		...
      }, 
	  ...
   ]
}
		
You can include ANY of the Update fields below, 
		but you MUST include the required (*) fields.

HTTP RESPONSE:  (updated ExpenseCode object -- see below for details)

Expense Code Object: Field Details

For each of the operations listed above, you will post or "get" one or more project 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.

FieldTypeDescription
Nm*StringName of new expense code.
Code*IntCode used to identify expense. Must be unique.
DescStringDescription of expense code.
IsUnitBoolTRUE if expenses against this category should be entered per UNIT.
UOMStringUnit of Measure- If IsUnit is true, then this field contains the name of the PER UNIT entry (eg- "miles" for mileage).
IsTaxableBoolTRUE if sales tax is collected on this item (not used for US firms, but global firms need to track taxes on expenses logged via BigTime).
TaxRateSidIntIf an item is taxable, what is the default tax rate used for it.
BaseCostNumericFor invoicing, the rate at which an item will be billed through to customers. Not used for expense entry
SalePriceNumericFor invoicing, the rate at which an item will be billed through to customers. Not used for expense entry
MarkupNumericUsed to calculate CostBill from CostOK. This value is stored as a PERCENT (e.g. 99% is stored as 99.00)
IsServiceFeeboolTrue if there is a service fee associated with code.
IsReimbboolTrue if reimbursement.
IsInactiveboolTrue if code is inactive.
SortOrdIntSort Order.
AcctSysSidIntIf this expense code is linked to an account item, this field will connect to the link.
AcctSysSid2IntIf this expense code is linked to a secondary account item, this field will connect to the SECONDARY link.