;
api login
End Section

BigTime's task api provides access to all of the tasks assigned to any project in the system. Tasks cannot exist unless they are assigned to a project. The api will let you see tasks by staffer assigned as well (if assignments are filled out).

Getting a listing of Tasks by Project
try it

By submitting a simple query to this api, you'll get a listing of task data (we return the "simple" view on the listings page). Note that you must supply a project id, and the system will return ONLY tasks assigned to that project.
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /task/listByProject/{ProjectSid}?{showCompleted=True/False}
HTTP RESPONSE:  (array of Task objects ("basic" view -- see below for details)

By default, we return only tasks that are "in process", but you can pass ShowCompleted=True to see tasks that are archived as well.

Getting "budget status" data for a Project's Tasks

In addition to pulling a list of tasks from the system, you can also pull the current totals for time/expenses and invoice line item amounts on a per-task basis. That information is useful for budget reporting -- but it's not a part of the default view for task data.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /task/BudgetStatusByProject/{ProjectSid}
HTTP RESPONSE:  (array of TaskBudgetStatus objects (see below for details)

Getting a listing of Tasks by Staffer
try it

By submitting a simple query to this api, you'll get a listing of task data (we return the "simple" view on the listings page). Note that you must supply a staffSid, and the system will return ONLY tasks assigned to that staffer.
HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /task/ListByStaffer/{StaffSid}?{showCompleted=True/False}
HTTP RESPONSE:  (array of Task objects ("basic" view -- see below for details)

By default, we return only tasks that are "in process", but you can pass ShowCompleted=True to see tasks that are archived as well.

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

You can use a simple GET request to pull the details associated with a single task. Note that the DETAIL 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:  /task/detail/{TaskSid}?&View={Detailed/Basic}
HTTP RESPONSE:  (Task object -- see below for details)

Creating a NEW task.
try it
  • Post

Note that only the fields listed in the AddUpdate 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 task withing a project you don't have rights to access).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /task/detail
POST CONTENT:  {TaskSid: 0, ProjectSid:0, Tasknm:"Test New Task"}
You can include ANY of the AddUpdate fields below, 
	but you MUST include the required (*) fields.

HTTP RESPONSE:  (new Task object -- see below for details)

Updating Existing Tasks.

Note that only the fields listed in the AddUpdate and Update views (below) should be included in your post to this url. Any other data will be ignored. Note again, validation errors will return a 400 error, and an invalid permission will return a 405 (eg - attempting to update tasks you don't have rights to access).

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP Post:  /task/detail/{taskSid}
POST CONTENT:  {TaskSid: 123, 
		notes: "this is an updated note..."}
		
** You can include ANY of the AddUpdate/Update fields below.  
		However - you cannot "zero-out" or remove any of the 
		required (*) fields.

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

Deleting a Task.

As long as there is no time/expense data logged against a task, BigTime will allow you to delete it through the api.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP DELETE:  /task/detail/{sid}
HTTP RESPONSE:  200 is a successful delete.

Task: Field Details

For each of the operations listed above, you will post or "get" one or more task 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 views. Required fields are flagged with an "*" character.

FieldTypeDescriptionView(s)
TaskSid Integer Unique SID code for this task (0 for new tasks). Basic, Detailed, AddUpdate*
ProjectSid Integer The SystemId of the project to which this task is assigned Basic, Detailed, AddUpdate*
ProjectLinkValue
ProjectLinkType
String
Enum
If you know a project's full displayName or it's Id, but not the project's SystemId, then you can still create a task. Just use these 2 alternate properties instead of the ProjectSid field and BigTime will automatically LOOKUP the correct ProjectSid value for you.

ProjectLinkType Values:
FindBySystemId(default) = 0; FindByProjectDName=2; FindByProjectCode=3;

AddUpdate*
TaskNm String Task "name" (or title) Basic, Detailed, AddUpdate*
TaskGroup String BigTime supports two-level task lists, and project plans can include a mix of tasks/sub-tasks. Any task with a TaskGroup is considered a sub-task. You can group tasks together in reports/UI by assigning them the same TaskGroup value. Basic, Detailed, AddUpdate
FullName String The fullname is another way of referencing a task. FullName is a read-only property that combines TaskGroup and TaskNm in TaskGroup:TaskNm format. A task with a TaskGroup value of "Design" and a TaskNm value of "Initial Project Plan" would have a FullName value of "Design:Initial Project Plan" Basic, Detailed
TaskType
(TypeLinkValue)
Integer
string
Unique Id of the task's type. Every task in the system is assigned a type, and users can manage workflow and settings for each type individually. Think of the type as a "template" into which a given task will fit. Note that I assign a TYPE when I first create a task and then cannot alter that setting.

TaskTypeName can be used in place of TypeSid if you know the full/unique name of this task type, but not the BigTime TypeSid code. If you specify TaskTypeName, then it will be ignored if TypeSid is set (TaskTypeName is valid ONLY for AddTask).
Basic, Detailed, AddOnly*
TaskType_nm String The NAME of the type to which this task is assigned. Basic, Detailed
CurrentStatus
(StatusLinkValue)
Integer
string
The current status is the current workflow "stage" for a task. While firms may have the same workflow stages for all of their task types, each type can support custom workflow.

CurrentStatusName can be used in place of CurrentStatus if you know the full/unique name of this status code, but not the BigTime Id. If you specify CurrentStatusName, then it will be ignored if CurrentStatus is set (CurrentStatusName is valid ONLY for AddUpdate operations).
Basic, Detailed, AddUpdate
CurrentStatus_nm String Status "string" value (for display). Basic, Detailed
TaskId String If a project's tasks are re-orderd by the user, then we assign a taskId to each of them (so that the user's preferred order can be maintained). Basic, Detailed, AddUpdate
Priority String HIGH MEDIUM or LOW. Basic, Detailed, AddUpdate
Notes String Basic, Detailed, AddUpdate
AssignCount Integer Total number of staff members assigned to this task. Basic, Detailed
AssignmentList LIST({Sid,Nm})
Post LIST(Sid)
The Detailed view returns an array of objects ({Sid:0, Nm:""}) with the StaffSid and Nm of any staffer assigned to the task. Then, if you need to update the staffers assigned to a task, you can post back a simple list of StaffSid values (eg - [1,2,3]). Setting this value will REMOVE any old assignments and REPLACE them with the staffers posted to this field. Basic, Detailed, AddUpdate
AssignmentNames String While the AssignmentList[] array has an entry for every assigned staffer, this property returns a simple csv list of names as a string (useful for display). Basic, Detailed
AssignLinkListValue
AssignLinkListType
String
Enum
If you know a staff member's name or their email, but not their BigTime StaffSid, then you can still create a task assignment. Just use these 2 alternate properties instead of the AssignmentList field and BigTime will automatically LOOKUP the correct StaffSid value(s) for you (note: separate multiple values with a comma (",").

AssignListLinkType Values:
FindByStaffSid(default) = 0; FindByFullName(First+Last)=1; FindByLastName=2; FindByEMail=3;

AddUpdate*
DueDt Date Date on which a task is "due." Basic, Detailed, AddUpdate
StartDt Date Tasks can have duration as well as due date. If a task has duration, it has a StartDt Basic, Detailed, AddUpdate
FeeOrExpense Integer If you are going to setup a budget for a task (eg - so that user can bill time/expenses against it) -- then use this value to determine whether the task appears on the user's timesheet, thier expense entry form(s) or both. Values are an enum (FeeOnly, ExpenseOnly, FeeAndExpense). Basic, Detailed, AddUpdate
BudgetHours Numeric HOURLY budget for the task Basic, Detailed, AddUpdate
BudgetFees Numeric Fee budget (eg - hours * bill rate). Note that we are tracking the budget for billable fees (not input cost). Basic, Detailed, AddUpdate
BudgetExps Numeric Expense (billable) budget. Basic, Detailed, AddUpdate
BudgetTotal Numeric Fee+Expense budget (useful for display). Basic, Detailed
PerComp Numeric Tasks can be active/complete, or they can be "partially completed" (often, firms like to track "percentage complete" on tasks so that they can track costs vs budget more carefully). This number is a decimal value between 0 and 1 (eg - a percentage). Basic, Detailed, AddUpdate
IsArchived True/False Setting this value to TRUE will automatically change the PerComp value to 100%. Likewise, setting the PerComp value to <1 (eg <100%) will change this archived value to FALSE. Basic, Detailed
DefaultQBClass Integer The SID code of the QuickBooks class to which time/expenses attached to a given task should be linked. Note that the system maintains a setting to indicate wehere a transactions class data should come from -- and the default hierarchy is STAFFER, PROJECT, TASK (based on the elements time or expense data is atttached to). Basic, Detailed, AddUpdate
IsSeriesMaster True/False If the task is a RECURRING engagement, then this value indicates that it is a series "master" (eg - changing it's values will change ALL of the non-archived tasks in the series). This is a read-only value. Basic, Detailed
MasterTaskSid Integer If this task is a RECURRING engagement, use this value to get the TaskSid for it's series "master." Basic, Detailed
ParentSid Integer Tasks can be arranged in a hierarchy using the parentSid value. Basic, Detailed, AddUpdate

Task: Budget Data

FieldTypeDescription
TaskSid Integer Unique SID code for this task (0 for new tasks).
HoursInput Numeric Total hours input against the task to date.
HoursBill Numeric Total billable hours input against the task to date.
FeesInput Numeric Total billable hours * bill rate input against the task to date.
FeesCost Numeric Total input hours * cost rate input against the task to date.
ExpensesInput Numeric Total expenses (cost) input against the task to date.
ExpensesBillable Numeric Total expenses (billable) input against the task to date.
TotalWip Numeric Total fees+expenses (billable) that have NOT been invoiced yet on a task.