Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Projects and time

Projects for clients, the tasks time is logged against, and the timeslips themselves. Conventions for ids, money, paging and errors are on Working with the tools.

Projects and tasks

ToolKindWhat it doesKey parameters
list_projectsreadProjects with their client (contact), status, budget, billing rate and currencycontact_id, view: active (default), completed, cancelled or hidden; page, per_page
get_projectreadOne project in full: client, status, budget, billing rate, dates and currencyid
create_projectwriteCreate a project for a client. status defaults to Active, budget_units to Hours and currency to the company’scontact_id, name, project fields (below)
update_projectwriteChange only the fields given. Set status Completed to close itid, project fields
list_tasksreadTasks, optionally for one project, with billing rate and whether they are billableproject_id, view: all (default), active, completed or hidden; updated_since, page, per_page
create_taskwriteCreate a task on a project, such as Development or Meetings, so time can be logged against itproject_id, name, billing_rate, billing_period (hour or day), is_billable (default true), status
update_taskwriteChange only the fields givenid, name, billing_rate, billing_period, is_billable, status (Active, Completed or Hidden)

Project fields

name, status (Active, Completed, Cancelled or Hidden), budget and budget_units (Hours, Days or Monetary: what the budget counts), normal_billing_rate (the default rate for its tasks, such as 450) with billing_period (hour or day), hours_per_day (for day rates, such as 7.5), currency (ISO 4217, such as GBP), starts_on, ends_on, contract_po_reference, and extra for any other field by FreeAgent’s name, such as {"is_ir35": true}.

Timeslips and timers

ToolKindWhat it doesKey parameters
list_timeslipsreadLogged time with date, hours, comment, task, project and user, and whether each is billed. view unbilled shows time not yet invoiced; running shows live timersview: all (default), unbilled or running; project_id, task_id, user_id, from_date, to_date, updated_since, nested, page, per_page
log_timewriteCreate one or more timeslips. The user defaults to the signed-in user and the project to the task’s own. Returns the timeslips createdentries (1 to 100, below)
update_timeslipwriteChange a timeslip’s hours, date, comment or task. Billed timeslips cannot be changedid, hours, dated_on, comment, task_id
delete_timeslipwrite, destructiveDelete a timeslipid
start_timerwriteStart the timer on a timeslip. To time new work, create one with log_time and hours 0 first. Only one timer runs at a timeid
stop_timerwriteStop the timer; the timeslip’s hours then include the time timedid

nested: true on list_timeslips includes each timeslip’s user, project and task in full.

Timeslip entries

Each entry of log_time’s entries:

FieldRequiredMeaning
task_idyesThe task worked on (list_tasks)
dated_onyesThe day, YYYY-MM-DD
hoursyesHours as a decimal: 1h30 is 1.5. 0 with start_timer to time it live
commentno
project_idnoDefault: the task’s own project
user_idnoWho did the work. Default: the signed-in user

Unbilled time becomes an invoice with create_invoice and include_timeslips; see Sales.